3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: refactor [power] documentation 

Separate the configuration for each device type, making it
easier for users to identify options specific for each
device.

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2021-12-20 06:45:22 -05:00
parent d7bfb7744a
commit 828be30466
1 changed files with 287 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

365
docs/configuration.md
View File

@ -276,16 +276,20 @@ gcode:
``` ```
### `[power]` ### `[power]`
Enables device power control. Currently GPIO (relays), RF transmitter, TPLink Smartplug, Enables device power control. Multiple "power" devices may be configured,
and Tasmota (via http) devices, HomeAssistant switch are supported. each with their own section, ie: `[power my_printer]`, `[power my_led]`.
#### Options common to all power devices
The following configuration options are available for all power device types:
```ini ```ini
# moonraker.conf # moonraker.conf
[power device_name] [power device_name]
type: gpio type:
# The type of device. Can be either gpio, rf, tplink_smartplug, tasmota # The type of device. Can be either gpio, rf, tplink_smartplug, tasmota
# shelly, homeseer, homeassistant, or loxonev1. # shelly, homeseer, homeassistant, loxonev1, or mqtt.
# This parameter must be provided. # This parameter must be provided.
off_when_shutdown: False off_when_shutdown: False
# If set to True the device will be powered off when Klipper enters # If set to True the device will be powered off when Klipper enters
@ -318,8 +322,87 @@ bound_service:
# been set the service will be started when the device powers on and stopped # been set the service will be started when the device powers on and stopped
# when the device powers off. The default is no service is bound to the # when the device powers off. The default is no service is bound to the
# device. # device.
# ```
# *** The following options apply to "gpio" and "rf" types ***
!!! Tip
Moonraker is authorized to manage the `klipper`, `klipper_mcu`,
`webcamd`, `MoonCord`, `KlipperScreen`, and `moonraker-telegram-bot`
services. It can also manage multiple instances of a service, ie:
`klipper_1`, `klipper_2`. Keep in mind that service names are case
sensitive.
!!! Note
If a device has been bound to the `klipper` service and the
`restart_klipper_when_powered` option is set to `True`, the restart
will be scheduled to execute after Klipper reports that its startup
sequence is complete.
#### GPIO Device Configuration
The following options are available for `gpio` device types:
```ini
# moonraker.conf
pin: gpiochip0/gpio26
# The pin to use for GPIO and RF devices. The chip is optional, if left out
# then the module will default to gpiochip0. If one wishes to invert
# the signal, a "!" may be prefixed to the pin. Valid examples:
# gpiochip0/gpio26
# gpio26
# !gpiochip0/gpio26
# !gpio26
# This parameter must be provided for "gpio" type devices
initial_state: off
# The initial state for GPIO type devices. May be on or
# off. When moonraker starts the device will be set to this
# state. Default is off.
timer:
# A time (in seconds) after which the device will power off after being.
# switched on. This effectively turns the device into a momentary switch.
# This option is available for gpio, tplink_smartplug, shelly, and tasmota
# devices. The timer may be a floating point value for gpio types, it should
# be an integer for all other types. The default is no timer is set.
```
!!! Note
Moonraker can only be used to toggle host device GPIOs (ie: GPIOs on your
PC or SBC). Moonraker cannot control GPIOs on an MCU, Klipper should be
used for this purpose.
Examples:
```ini
# moonraker.conf
# Control a relay providing power to the printer
[power printer]
type: gpio
pin: gpio26 # uses pin 26 on gpiochip0
off_when_shutdown: True
initial_state: off
# Control a status led
[power printer_led]
type: gpio
pin: !gpiochip0/gpio16 # inverts pin
initial_state: off
# Control a printer illumination, powers on when
# Moonraker starts
[power light_strip]
type: gpio
pin: gpiochip0/gpio17
initial_state: on
```
#### RF Device Configuration
The following options are available for gpio controlled `rf` device types:
```ini
# moonraker.conf
pin: gpiochip0/gpio26 pin: gpiochip0/gpio26
# The pin to use for GPIO and RF devices. The chip is optional, if left out # The pin to use for GPIO and RF devices. The chip is optional, if left out
# then the module will default to gpiochip0. If one wishes to invert # then the module will default to gpiochip0. If one wishes to invert
@ -339,14 +422,19 @@ timer:
# This option is available for gpio, tplink_smartplug, shelly, and tasmota # This option is available for gpio, tplink_smartplug, shelly, and tasmota
# devices. The timer may be a floating point value for gpio types, it should # devices. The timer may be a floating point value for gpio types, it should
# be an integer for all other types. The default is no timer is set. # be an integer for all other types. The default is no timer is set.
#
# *** The following options apply to "rf" devices ***
on_code: on_code:
off_code: off_code:
# Valid binary codes that are sent via the RF transmitter. # Valid binary codes that are sent via the RF transmitter.
# For example: 1011. # For example: 1011.
# ```
# *** The following options apply to "tplink_smartplug" devices ***
#### TPLink Smartplug Configuration
The following options are availble for `tplink_smartplug` device types:
```ini
# moonraker.conf
address: address:
# A valid ip address or hostname for the tplink device. "Power Strips" can # A valid ip address or hostname for the tplink device. "Power Strips" can
# be controlled by including the socket index in the ip address. For example, # be controlled by including the socket index in the ip address. For example,
@ -356,7 +444,23 @@ address:
port: port:
# The port to connect to. Default is 9999. # The port to connect to. Default is 9999.
# #
# *** The following options apply to "tasmota" devices *** ```
Example:
```ini
# moonraker.conf
[power printer_plug]
type: tplink_smartplug
address: 192.168.1.123
```
#### Tasmota Configuration
The following options are available for `tasmota` device types:
```ini
# Note: # Note:
# If your single-relay Tasmota device switches on/off successfully, # If your single-relay Tasmota device switches on/off successfully,
# but fails to report its state, ensure that 'SetOption26' is set in # but fails to report its state, ensure that 'SetOption26' is set in
@ -369,8 +473,29 @@ password:
output_id: output_id:
# The output_id (or relay id) to use if the Tasmota device supports # The output_id (or relay id) to use if the Tasmota device supports
# more than one output. Default is 1. # more than one output. Default is 1.
# ```
# *** The following options apply to "shelly" devices ***
!!! Note
This implmentation communicates with Tasmota firmware through its
HTTP APIs. It is also possible to use [MQTT](#mqtt-device-configuration)
to control devices flashed with Tasmota.
Example:
```ini
# moonraker.conf
[power tasmota_plug]
type: tasmota
address: 192.168.1.124
password: mypassword
```
#### Shelly Configuration
The following options are available for `shelly` device types:
```ini
address: address:
# A valid ip address or hostname for the shelly device. This parameter # A valid ip address or hostname for the shelly device. This parameter
# must be provided. # must be provided.
@ -383,8 +508,32 @@ password:
output_id: output_id:
# The output_id (or relay id) to use if the Shelly device supports # The output_id (or relay id) to use if the Shelly device supports
# more than one output. Default is 1. # more than one output. Default is 1.
# ```
# *** The following options apply to "homeseer" devices ***
!!! Note
This implmentation communicates with Shelly firmware through its
HTTP APIs. It is also possible to use [MQTT](#mqtt-device-configuration)
to control Shelly devices.
Example:
```ini
# moonraker.conf
[power shelly_plug]
type: shelly
address: 192.168.1.125
user: user2
password: password2
```
#### Homeseer Configuration
The following options are available for `homeseer` device types:
```ini
# moonraker.conf
address: address:
# A valid ip address or hostname for the homeseer device. This parameter # A valid ip address or hostname for the homeseer device. This parameter
# must be provided. # must be provided.
@ -400,7 +549,15 @@ user:
password: password:
# The password for request authentication. The default is no password. # The password for request authentication. The default is no password.
# #
# *** The following options apply to "homeassistant" devices *** ```
#### Home Assistant Configuration (HTTP)
The following options are available for `homeassistant` device types:
```ini
# moonraker.conf
address: address:
# A valid ip address or hostname for the Home Assistant server. This # A valid ip address or hostname for the Home Assistant server. This
# parameter must be provided. # parameter must be provided.
@ -420,7 +577,26 @@ status_delay: 1.0
# to validate that Home Assistant has successfully toggled the device, # to validate that Home Assistant has successfully toggled the device,
# as the API is currently broken on their end. Default is 1 second. # as the API is currently broken on their end. Default is 1 second.
# #
# *** The following options apply to "loxone" devices *** ```
Example:
```ini
# moonraker.conf
[power homeassistant_switch]
type: homeassistant
address: 192.168.1.126
port: 8123
device: switch.1234567890abcdefghij
token: home-assistant-very-long-token
domain: switch
```
#### Loxone Device Configuration
The following options are available for `loxone` device types:
```ini
address: address:
# A valid ip address or hostname for the Loxone server. This # A valid ip address or hostname for the Loxone server. This
# parameter must be provided. # parameter must be provided.
@ -432,7 +608,13 @@ output_id:
# The name of a programmed output, virtual input or virtual # The name of a programmed output, virtual input or virtual
# output in the loxone configuration. The default is no output id. # output in the loxone configuration. The default is no output id.
# #
# *** The following options apply to "mqtt" devices. *** ```
#### MQTT Device Configuration
The following options are available for `mqtt` device types:
```ini
qos: qos:
# The MQTT QOS level to use when publishing and subscribing to topics. # The MQTT QOS level to use when publishing and subscribing to topics.
# The default is to use the setting supplied in the [mqtt] section. # The default is to use the setting supplied in the [mqtt] section.
@ -440,10 +622,10 @@ command_topic:
# The mqtt topic used to publish commands to the device. This parameter must # The mqtt topic used to publish commands to the device. This parameter must
# be provided. # be provided.
command_payload: command_payload:
# The payload sent with the topic. This can be a template, with a "request" # The payload sent with the topic. This can be a template, with a "command"
# variable included in the template context, where "request" is either "on" # variable included in the template context, where "command" is either "on"
# or "off". For example: # or "off". For example:
# {% if request == "on" %} # {% if command == "on" %}
# TURN_ON # TURN_ON
# {% else %} # {% else %}
# TURN_OFF # TURN_OFF
@ -451,24 +633,24 @@ command_payload:
# the device on, and "TURN_OFF" if the request is to turn the device off. # the device on, and "TURN_OFF" if the request is to turn the device off.
# This parameter must be provided. # This parameter must be provided.
retain_command_state: retain_command_state:
# When set to true, the retain flag will be set when the command topic is # If set to True the retain flag will be set when the command topic is
# published. Default is False # published. Default is False.
state_topic: state_topic:
# The mqtt topic to subscribe to for state updates. This parameter must be # The mqtt topic to subscribe to for state updates. This parameter must be
# provided. # provided.
state_response_template: state_response_template:
# A template used to parse the payload received with the state topic. A # A template used to parse the payload received with the state topic. A
# "payload" variable is included with the request context. This template # "payload" variable is provided the template's context. This template
# must resolve to "on" or "off". For example: # must resolve to "on" or "off". For example:
# {% set resp = payload|fromjson %} # {% set resp = payload|fromjson %}
# {resp["POWER"]|lower} # {resp["POWER"]}
# The above example assumes a json response is received, with a "POWER" field # The above example assumes a json response is received, with a "POWER" field
# that set to either "ON" or "OFF". The resolved response will always be # that set to either "ON" or "OFF". The resolved response will always be
# trimmed of whitespace and converted to lowercase. The default is the payload. # trimmed of whitespace and converted to lowercase. The default is the payload.
state_timeout: state_timeout:
# The amount of time (in seconds) to wait for the state topic to receive an # The amount of time (in seconds) to wait for the state topic to receive an
# update before putting the device in an "error" state. This timeout is # update. If the timeout expires the device revert to an "error" state. This
# applied during initialization and after a command has been sent. # timeout is applied during initialization and after a command has been sent.
# The default is 2 seconds. # The default is 2 seconds.
query_topic: query_topic:
# The topic used to query command state. It is expected that the device will # The topic used to query command state. It is expected that the device will
@ -477,66 +659,52 @@ query_payload:
# The payload to send with the query topic. This may be a template or a string. # The payload to send with the query topic. This may be a template or a string.
# The default is no payload. # The default is no payload.
query_after_command: query_after_command:
# If set to True, Moonraker will publish the query topic after publishing the # If set to True Moonraker will publish the query topic after publishing the
# command topic. This should only be necessary if the device does not publish a # command topic. This should only be necessary if the device does not publish a
# reponse to a command request to the state topic. The default is false. # reponse to a command request to the state topic. The default is False.
``` ```
!!! Note
Moonraker's MQTT client must be properly configured to add a MQTT device.
See the [mqtt](#mqtt) section for details.
!!! Tip !!! Tip
Moonraker is authorized to manage the `klipper`, `klipper_mcu`, MQTT is the most robust way of managing networked devices through
`webcamd`, `MoonCord`, `KlipperScreen`, and `moonraker-telegram-bot` Moonraker. A well implemented MQTT device will publish all
services. It can also manage multiple instances of a service, ie: changes in state to the `state_topic`. Moonraker recieves these changes,
`klipper_1`, `klipper_2`. Keep in mind that service names are case updates its internal state, and notifies connected clients. This allows
sensitive. for device control outside of Moonraker. Note however that post command
actions, such as bound services, will not be run if a device is toggled
outside of Moonraker.
!!! Note Example:
If a device has been bound to the `klipper` service and the
`restart_klipper_when_powered` option is set to `True`, the restart
will be scheduled to execute after Klipper reports that its startup
sequence is complete.
Below are some potential examples:
```ini ```ini
# moonraker.conf # moonraker.conf
[power printer] # Example configuration for ing with Tasmota firmware over mqtt
type: gpio [power mqtt_plug]
pin: gpio26 type: mqtt
off_when_shutdown: True command_topic: cmnd/tasmota_switch/POWER
initial_state: off # Tasmota uses "on" and "off" as the payload, so our template simply renders
# the command
[power printer_led] command_payload:
type: gpio {command}
pin: !gpiochip0/gpio16 # There is no need to set the retain flag for Tasmota devices. Moonraker
initial_state: off # will use the query topic to initalize the device. Tasmota will publish
# all changes in state to the state topic.
[power light_strip] retain_command_state: False
type: gpio # To query a tasmota device we send the command topic without a payload.
pin: gpiochip0/gpio17 # Otpionally we could send a "?" as the payload.
initial_state: on query_topic: cmnd/tasmota_switch/POWER
# query_payload: ?
[power wifi_switch] state_topic: stat/tasmota_switch/POWER
type: tplink_smartplug # The response is either "ON" or "OFF". Moonraker will handle converting to
address: 192.168.1.123 # lower case.
state_response_template:
[power tasmota_plug] {payload}
type: tasmota # Tasmota updates the state topic when the device state changes, so it is not
address: 192.168.1.124 # not necessary to query after a command
password: password1 query_after_command: False
[power shelly_plug]
type: shelly
address: 192.168.1.125
user: user2
password: password2
[power homeassistant_switch]
type: homeassistant
address: 192.168.1.126
port: 8123
device: switch.1234567890abcdefghij
token: home-assistant-very-long-token
domain: switch
``` ```
#### Toggling device state from Klipper #### Toggling device state from Klipper
@ -935,3 +1103,44 @@ easily detect and use Moonraker instances.
[zeroconf] [zeroconf]
``` ```
## Jinja2 Templates
Some Moonraker configuration options make use of Jinja2 Templates. For
consistency, Moonraker uses the same Jinja2 syntax as Klipper. Statements
should be enclosed in `{% %}`, and expressions in `{ }`. There are some
key differences, as outlined below:
- Moonraker templates do not currently include globals like
`printer` and `params` in the context. Variables included in the
context will be specified in the option's documentation.
- Moonraker's template environment adds the `ext.do` extension. The
`{% do expression %}` statement can be used to modify variables without
printing any text. See the example below for details.
- Klipper uses Jinja2 exclusively for evaluating gcode statements. Moonraker
uses it to provide configuration options that may need to change based on
runtime parameters.
For an example of how to use the `do` statement, lets assume we need to
send a specific json payload with an MQTT power device command. Rather
than attempt to type out the json ourselves, it may be easier to create
a `dictionary` object and convert it to json:
```ini
# moonraker.conf
[power my_mqtt_device]
type: mqtt
command_topic: my/mqtt/command
# Lets assume this device requres a json payload with each command.
# We will use a dict to generate the payload
command_payload:
{% set my_payload = {} %}
{% do my_payload["SOME_FIELD"] = "some_string" %}
{% do my_payload["ANOTHER_FIELD"] = True %}
# Here we set the actual command, the "command" variable
# is passed to the context of this template
{% do my_payload["POWER_COMMAND"] = command %}
# generate the json output
{ my_payload|tojson }
```