Command-line reference

Note

Issuing the pyziggy command is interchangeable with issuing python -m pyziggy. With this you can easily debug any command by creating a run configuration in PyCharm, and selecting the module option and specifying pyziggy in the text field.

pyziggy autogenerates Python classes using the device information shared by Zigbee2MQTT. User code can interact with stateful device and parameter objects, and pyziggy will continuously translate this into MQTT communication.

If you run the following command in an empty PROJECT_DIRECTORY it will initialize it into a home automation project and create an automation.py file that you can edit and run any time by issuing the same command again. During initialization a config file will be created where you can provide information about how to connect to the MQTT broker.

example:

pyziggy run PROJECT_DIRECTORY/automation.py

usage: pyziggy [-h] [--version] [-v] {run,check} ...

Named Arguments

--version

show program’s version number and exit

-v, --verbose

enables debug level logging

Default: False

Sub-commands

run

This is the main command that will load and run the automation project specified by the module file containing a DevicesClient object. If the specified module file doesn’t exist, but its parent directory does, then this command will set up the directory as a pyziggy automation project, and create the module file, that instantiates an autogenerated AvailableDevices(DevicesClient) object. To see what options can be used with the run subcommand, issue ‘pyziggy run -h’.

pyziggy run [-h] [--no_startup_query] [--no_mypy] devices_client_file

Positional Arguments

devices_client_file

Python module file that creates a DevicesClient object. Use the autogenerated AvailableDevices(DevicesClient) class in pyziggy_autogenerate.available_devices.

Named Arguments

--no_startup_query

By default pyziggy sends a query for every parameter of every device immediately after launching an automation. This setting switches that off, leaving parameter values in an unknown state until Zigbee2MQTT sends an update for them. This can be desirable during development, when an automation is started and stopped very often. Querying every parameter in a large Zigbee network every time can generate a lot of Zigbee traffic.

Default: False

--no_mypy

Disables the mypy correctness check that runs on the automation project module prior to launching it.

Default: False

check

Similar to a dry-run. This subcommand is identical to run, except it doesn’t enter an infinite message loop, but exits with 0 if it could and 1 otherwise. This command will still connect to the MQTT broker, still autogenerate the AvailableDevices class, and still run a mypy correctness check on your automation project module. The only difference is not entering the message loop at the end of this process..

pyziggy check [-h] [--no_mypy] devices_client_file

Positional Arguments

devices_client_file

Python module file that instantiates a DevicesClient object. For simple use-cases it should specifically instantiate an AvailableDevices(DevicesClient) object.

Named Arguments

--no_mypy

Disables the mypy correctness check that runs on the automation project module prior to launching it.

Default: False