CLI Commands Reference

This page documents all available commands for the pydoover CLI, organized by interface.

Platform Interface Commands

Commands for interacting with the Platform Interface container. Access device I/O and system information.

test_comms

Test connection by sending a basic echo response to the platform interface container.

pydoover platform test_comms [--message MESSAGE]

Options:

Option	Type	Default	Description
`--message`	str	"Comms Check Message"	Message to send for echo response

Example:

pydoover platform test_comms --message "Hello Platform"

get_di

Get digital input values.

pydoover platform get_di <pin>

Arguments:

Argument	Type	Description
`pin`	int	Digital input pin number

Example:

# Get digital input pin 0
pydoover platform get_di 0

# Get digital input pin 3
pydoover platform get_di 3

get_ai

Get analog input values.

pydoover platform get_ai <pin>

Arguments:

Argument	Type	Description
`pin`	int	Analog input pin number

Example:

# Get analog input pin 0
pydoover platform get_ai 0

get_do

Get digital output values.

pydoover platform get_do <pin>

Arguments:

Argument	Type	Description
`pin`	int	Digital output pin number

Example:

pydoover platform get_do 0

set_do

Set digital output values.

pydoover platform set_do <do> <value>

Arguments:

Argument	Type	Description
`do`	int or list	Digital output pin number(s)
`value`	int or list	Value(s) to set (0 or 1)

Examples:

# Set digital output pin 1 to high
pydoover platform set_do 1 1

# Set digital output pin 2 to low
pydoover platform set_do 2 0

schedule_do

Schedule digital output values to change after a delay.

pydoover platform schedule_do <do> <value> <in_secs>

Arguments:

Argument	Type	Description
`do`	int or list	Digital output pin number(s)
`value`	bool or list	Value(s) to set
`in_secs`	int	Seconds until the change takes effect

Example:

# Set digital output pin 1 to high in 10 seconds
pydoover platform schedule_do 1 1 10

get_ao

Get analog output values.

pydoover platform get_ao <pin>

Arguments:

Argument	Type	Description
`pin`	int	Analog output pin number

Example:

pydoover platform get_ao 0

set_ao

Set analog output values.

pydoover platform set_ao <ao> <value>

Arguments:

Argument	Type	Description
`ao`	int or list	Analog output pin number(s)
`value`	float or list	Value(s) to set

Examples:

# Set analog output pin 1 to 3.3V
pydoover platform set_ao 1 3.3

# Set analog output pin 2 to 1.5V
pydoover platform set_ao 2 1.5

schedule_ao

Schedule analog output values to change after a delay.

pydoover platform schedule_ao <ao> <value> <in_secs>

Arguments:

Argument	Type	Description
`ao`	int or list	Analog output pin number(s)
`value`	float or list	Value(s) to set
`in_secs`	int	Seconds until the change takes effect

Example:

# Set analog output pin 1 to 2.5V in 5 seconds
pydoover platform schedule_ao 1 2.5 5

get_system_voltage

Get the system input voltage.

pydoover platform get_system_voltage

Returns: System input voltage in volts.

get_system_power

Get the system input power.

pydoover platform get_system_power

Returns: System input power in watts.

get_system_temperature

Get the system temperature (e.g., Raspberry Pi CM4 temperature on Doovit).

pydoover platform get_system_temperature

Returns: System temperature in degrees Celsius.

get_location

Get the device location (typically via ModemManager on 4G-enabled devices).

pydoover platform get_location

Returns: Location object with latitude, longitude, and altitude.

reboot

Reboot the device.

pydoover platform reboot

Warning: This will immediately reboot the device. Use with caution.

shutdown

Shutdown the device.

pydoover platform shutdown

Warning: This will immediately shut down the device. Use with caution.

get_immunity_seconds

Get the number of seconds the device is immune from shutdown requests.

pydoover platform get_immunity_seconds

Returns: Immunity time in seconds.

set_immunity_seconds

Set the number of seconds the device is immune from shutdown requests.

pydoover platform set_immunity_seconds <immunity_secs>

Arguments:

Argument	Type	Description
`immunity_secs`	int	Immunity duration in seconds

Example:

# Set 120 seconds of shutdown immunity
pydoover platform set_immunity_seconds 120

schedule_shutdown

Schedule a shutdown to occur after a delay.

pydoover platform schedule_shutdown <time_secs>

Arguments:

Argument	Type	Description
`time_secs`	int	Seconds until shutdown

get_io_table

Get the I/O table configuration.

pydoover platform get_io_table

Returns: JSON representation of the I/O table.

sync_rtc

Synchronize the real-time clock (RTC) with the system (network) time.

pydoover platform sync_rtc

get_di_events

Get digital input events for a specific pin.

pydoover platform get_di_events <di_pin> <edge> [--include_system_events] [--events_from TIMESTAMP]

Arguments:

Argument	Type	Description
`di_pin`	int	Digital input pin number
`edge`	str	Edge type: "rising", "falling", or "both"

Options:

Option	Type	Default	Description
`--include_system_events`	bool	False	Include system events
`--events_from`	int	0	Starting event ID or timestamp (milliseconds)

Device Agent Interface Commands

Commands for interacting with the Device Agent container. Manage channels and cloud connectivity.

test_comms

Test connection by sending a basic echo response to the device agent container.

pydoover device_agent test_comms [--message MESSAGE]

Options:

Option	Type	Default	Description
`--message`	str	"Comms Check Message"	Message to send for echo response

get_is_dda_available

Check if the Device Agent service is available.

pydoover device_agent get_is_dda_available

Returns: Boolean indicating availability.

get_is_dda_online

Check if the Device Agent service is currently online.

pydoover device_agent get_is_dda_online

Returns: Boolean indicating online status.

get_has_dda_been_online

Check if the Device Agent service has been online at least once since startup.

pydoover device_agent get_has_dda_been_online

Returns: Boolean.

await_dda_available

Wait for the Device Agent to become available.

pydoover device_agent await_dda_available [--timeout SECONDS]

Options:

Option	Type	Default	Description
`--timeout`	int	10	Maximum seconds to wait

get_channel_aggregate

Fetch a channel's current aggregate payload.

pydoover device_agent get_channel_aggregate <channel_name>

Arguments:

Argument	Type	Description
`channel_name`	str	Name of the channel

Example:

pydoover device_agent get_channel_aggregate my_channel

Returns: Channel aggregate data as JSON or string.

publish_to_channel

Publish a message to a channel.

pydoover device_agent publish_to_channel <channel_name> <message> [--record_log] [--max_age SECONDS]

Arguments:

Argument	Type	Description
`channel_name`	str	Name of the channel
`message`	dict or str	Message payload (JSON or string)

Options:

Option	Type	Default	Description
`--record_log`	bool	True	Whether to save to log
`--max_age`	int	None	Maximum age before publishing to cloud (-1 for immediate)

Example:

pydoover device_agent publish_to_channel my_channel '{"foo": "bar"}'

get_temp_token

Get a temporary API token.

pydoover device_agent get_temp_token

Returns: Tuple of (token, expiry_time, endpoint).

Note: This is deprecated. WSS tokens are now valid for API calls.

listen_channel

Listen to a channel and print updates to the console.

pydoover device_agent listen_channel <channel_name>

Arguments:

Argument	Type	Description
`channel_name`	str	Name of the channel to listen to

Example:

pydoover device_agent listen_channel my_channel

This command runs continuously, printing channel updates as they arrive. Press Ctrl+C to stop.

Modbus Interface Commands

Commands for interacting with the Modbus Interface container. Manage modbus buses and registers.

test_comms

Test connection by sending a basic echo response to the modbus interface container.

pydoover modbus test_comms [--message MESSAGE]

Options:

Option	Type	Default	Description
`--message`	str	"Comms Check Message"	Message to send for echo response

open_bus

Open a modbus bus connection.

pydoover modbus open_bus [options]

Options:

Option	Type	Default	Description
`--bus_type`	str	"serial"	Bus type: "serial" or "tcp"
`--name`	str	"default"	Bus identifier name
`--serial_port`	str	"/dev/ttyS0"	Serial port path
`--serial_baud`	int	9600	Serial baud rate
`--serial_method`	str	"rtu"	Modbus method
`--serial_bits`	int	8	Data bits
`--serial_parity`	str	"N"	Parity: "N", "E", or "O"
`--serial_stop`	int	1	Stop bits
`--serial_timeout`	float	0.3	Serial timeout in seconds
`--tcp_uri`	str	"127.0.0.1:5000"	TCP address for TCP bus
`--tcp_timeout`	int	2	TCP timeout in seconds

Examples:

# Open a serial RTU bus
pydoover modbus open_bus --bus_type serial --name my_bus --serial_port /dev/ttyUSB0 --serial_baud 19200

# Open a TCP modbus bus
pydoover modbus open_bus --bus_type tcp --name tcp_bus --tcp_uri 192.168.1.100:502

close_bus

Close a modbus bus connection.

pydoover modbus close_bus [--bus_id BUS_ID]

Options:

Option	Type	Default	Description
`--bus_id`	str	"default"	Bus identifier to close

Example:

pydoover modbus close_bus --bus_id my_bus

get_bus_status

Get the status of a modbus bus.

pydoover modbus get_bus_status [--bus_id BUS_ID]

Options:

Option	Type	Default	Description
`--bus_id`	str	"default"	Bus identifier

Returns: Boolean indicating if the bus is open.

read_registers

Read registers from a modbus device.

pydoover modbus read_registers [options]

Options:

Option	Type	Default	Description
`--bus_id`	str	"default"	Bus identifier
`--modbus_id`	int	1	Modbus device ID
`--start_address`	int	0	Starting register address
`--num_registers`	int	1	Number of registers to read
`--register_type`	int	4	Register type (4 = holding registers)
`--configure_bus`	bool	True	Auto-configure bus if unavailable

Examples:

# Read 10 holding registers starting at address 0
pydoover modbus read_registers --bus_id my_bus --modbus_id 1 --start_address 0 --num_registers 10

# Read input registers (type 3)
pydoover modbus read_registers --modbus_id 2 --start_address 100 --num_registers 5 --register_type 3

Returns: Integer value (single register) or list of integers (multiple registers).

write_registers

Write values to registers on a modbus device.

pydoover modbus write_registers [options]

Options:

Option	Type	Default	Description
`--bus_id`	str	"default"	Bus identifier
`--modbus_id`	int	1	Modbus device ID
`--start_address`	int	0	Starting register address
`--values`	list[int]	None	Register values to write
`--register_type`	int	4	Register type (4 = holding registers)
`--configure_bus`	bool	True	Auto-configure bus if unavailable

Example:

# Write values to holding registers
pydoover modbus write_registers --bus_id my_bus --modbus_id 1 --start_address 0 --values "[100, 200, 300]"

Returns: Boolean indicating success.

Command Decorators

The CLI uses decorators to register methods as CLI commands.

@command Decorator

The @command decorator from pydoover.cli.decorators marks a method as a CLI command:

from pydoover.cli.decorators import command as cli_command

@cli_command(name="custom_name", description="Custom description", setup_api=False)
def my_method(self, arg1: str, arg2: int = 10):
    """Method docstring used if no description provided."""
    pass

Parameters:

Parameter	Type	Default	Description
`name`	str	None	Custom command name (defaults to method name)
`description`	str	None	Command description (defaults to docstring)
`setup_api`	bool	False	Whether to set up API before running

@annotate_arg Decorator

Add custom descriptions to arguments:

from pydoover.cli.decorators import annotate_arg

@cli_command()
@annotate_arg("pin", "The GPIO pin number to read")
def read_pin(self, pin: int):
    pass

@ignore_alias Decorator

Prevent a method from being registered as a CLI command:

from pydoover.cli.decorators import ignore_alias

@ignore_alias
def internal_method(self):
    """This method will not be available via CLI."""
    pass

Type Parsing

The CLI supports special type parsing for complex argument types:

Python Type	CLI Input Format	Example
`int`	Integer	`42`
`float`	Decimal	`3.14`
`str`	String	`"hello"`
`bool`	Boolean	`True` or `False`
`list[int]`	JSON array	`"[1, 2, 3]"`
`list[bool]`	JSON array	`"[true, false]"`
`list[float]`	JSON array	`"[1.0, 2.5]"`
`dict` or `str`	JSON or string	`'{"key": "value"}'`

BoolFlag Type

For boolean flags that toggle behavior:

from pydoover.cli.parsers import BoolFlag

def my_command(self, verbose: BoolFlag = False):
    pass

This creates a --verbose flag that toggles the default value.