docs: update documentation for changes to "power" plugin
The power APIs were never properly documented, so this adds them to web_api.md. In addition, a new "user_changes.md" document has been added to help users transition to the new plugin. Signed-off-by: Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Arksine
parent
675fe750f6
commit
01a48e530f
14
README.md
14
README.md
|
|
@ -8,4 +8,16 @@ is used to provide Moonraker's server functionality.
|
|||
Note that Moonraker does not come bundled with a client, you will need to
|
||||
install one. The following web clients are currently available:
|
||||
- [Mainsail](https://github.com/meteyou/mainsail) by Meteyou
|
||||
- [Fluidd](https://github.com/cadriel/fluidd) by Cadriel
|
||||
- [Fluidd](https://github.com/cadriel/fluidd) by Cadriel
|
||||
|
||||
### Changes
|
||||
|
||||
This section contains changelogs that users and developers may reference
|
||||
to see if any action is necessary on their part. The date of the most
|
||||
recent change is included.
|
||||
|
||||
Users:\
|
||||
[user_changes.md](/docs/user_changes.md) - November 19th 2020
|
||||
|
||||
Developers:\
|
||||
[api_changes.md](/docs/api_changes.md) - November 19th 2020
|
||||
|
|
|
|||
|
|
@ -1,6 +1,37 @@
|
|||
This document keeps a record of all changes to Moonraker's remote
|
||||
facing APIs.
|
||||
|
||||
### November 19th 2020
|
||||
- The path for the power APIs has changed from `gpio_power` to `device_power`:
|
||||
- `GET /machine/device_power/devices`\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.devices","id":"1"}`\
|
||||
Returns an array of objects listing all detected devices.
|
||||
Each object in the array is guaranteed to have the following
|
||||
fields:
|
||||
- `device`: The device name
|
||||
- `status`: May be "init", "on", "off", or "error"
|
||||
- `type`: May be "gpio" or "tplink_smartplug"
|
||||
- `GET /machine/device_power/status?dev_name`\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.status","id":"1",
|
||||
"params":{"dev_name":null}}`\
|
||||
It is no longer possible to call this method with no arguments.
|
||||
Status will only be returned for the requested device, to get
|
||||
status of all devices use `/machine/device_power/devices`. As
|
||||
before, this returns an object in the format of
|
||||
`{device_name: status}`, where device_name is the name of the device
|
||||
and `status` is the devices current status.
|
||||
- `POST /machine/device_power/on?dev_name`\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.on","id":"1",
|
||||
"params":{"dev_name":null}}`\
|
||||
Toggles device on. Returns the current status of the device.
|
||||
- `POST /machine/device_power/off?dev_name`\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.off","id":"1",
|
||||
"params":{"dev_name":null}}`\
|
||||
Toggles device off. Returns the current status of the device.
|
||||
- The `notify_power_changed` notification now includes an object
|
||||
containing device info, matching that which would be recieved
|
||||
from a single item in `/machine/power/devices`.
|
||||
|
||||
### November 12th 2020
|
||||
- Two new fields have been added to the gcode metadata:
|
||||
- `gcode_start_byte`: Indicates the byte position in the
|
||||
|
|
|
|||
|
|
@ -262,33 +262,44 @@ gcode:
|
|||
Power Plugin Configuration. One may use this module to toggle the
|
||||
state of a relay using a linux GPIO, enabling the ability to power
|
||||
a printer on/off regardless of Klippy's state. GPIOs are toggled
|
||||
using linux sysfs.
|
||||
using libgpiod. A configuration section should be added for each
|
||||
device as shown below:
|
||||
```
|
||||
[power]
|
||||
devices: printer, led
|
||||
# A comma separated list of devices you wish to control. Device names may not
|
||||
# contain whitespace. This parameter must be provided.
|
||||
#
|
||||
# Each device specified in "devices" should define its own set of the below
|
||||
# options:
|
||||
{dev}_name: Friendly Name
|
||||
# An optional alias for the device. The default is the name specifed in
|
||||
# "devices".
|
||||
{dev}_pin: 23
|
||||
# The sysfs GPIO pin number you wish to control. This parameter must be
|
||||
# provided.
|
||||
{dev}_active_low: False
|
||||
# When set to true the pin signal is inverted. Default is False.
|
||||
[power device name]
|
||||
type: gpio
|
||||
# The type of device. Can be either gpio or tplink_smartplug. This
|
||||
# parameter must be provided.
|
||||
pin: gpiochip0/gpio26
|
||||
# The pin to use for GPIO 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
|
||||
address:
|
||||
port:
|
||||
# The above options are used for "tplink_smartplug" devices. The
|
||||
# address should be a valid ip or hostname for the tplink device.
|
||||
# The port should be the port the device is configured to use. The
|
||||
# address must be provided. The port defaults to 9999.
|
||||
|
||||
```
|
||||
Below are some potential examples:
|
||||
```
|
||||
[power printer]
|
||||
type: gpio
|
||||
pin: gpio26
|
||||
|
||||
Define the devices you wish to control under _devices_ with a comma separated
|
||||
list. For device specific configrations, swap {dev} for the name of the device
|
||||
that you listed under devices.
|
||||
[power printer_led]
|
||||
type: gpio
|
||||
pin: !gpiochip0/gpio16
|
||||
|
||||
Each device can have a Friendly Name, pin, and activehigh set. Pin is the only
|
||||
required option. For devices that should be active when the signal is 0 or low,
|
||||
set {dev}_active_low to False, otherwise don't put the option in the
|
||||
configuration.
|
||||
[power wifi_switch]
|
||||
type: tplink_smartplug
|
||||
address: 192.168.1.123
|
||||
```
|
||||
|
||||
It is possible to toggle device power from the Klippy host, this can be done
|
||||
with a gcode_macro, such as:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,34 @@
|
|||
This file will track changes that require user intervention,
|
||||
such as a configuration change or a reinstallation.
|
||||
|
||||
### November 19th 2020
|
||||
- The install script (`install_moonraker.sh`) now has command-line
|
||||
options:\
|
||||
`-r` Rebuild the python virtual env\
|
||||
`-f` Force an overwrite of `/etc/default/moonraker` during installation\
|
||||
`-c /path/to/moonraker.conf` Allows user to specify the path to
|
||||
moonraker.conf during configuration. Using this in conjunction with `-f`
|
||||
will update the defaults file wih the new path.
|
||||
- New dependencies have been added to Moonraker which require reinstallation.
|
||||
Run the following command to reinstall and rebuild the virtualenv:
|
||||
```
|
||||
~/moonraker/scripts/install_moonraker.sh -r
|
||||
```
|
||||
- The power plugin configuration has changed. See the
|
||||
[install guide](installation.md#power-control-plugin) for
|
||||
details on the new configuration.
|
||||
- Users transitioning from the previous version of the power plugin will need
|
||||
to unexport any curently used pins. For example, the following command
|
||||
may be used to unexport pin 19:
|
||||
```
|
||||
echo 19 > /sys/class/gpio/unexport
|
||||
```
|
||||
Alternatively one may reboot the machine after upgrading:
|
||||
```
|
||||
cd ~/moonraker/
|
||||
git pull
|
||||
~/moonraker/scripts/install_moonraker.sh -r
|
||||
sudo reboot
|
||||
```
|
||||
Make sure that the power plugin configuration has been updated prior
|
||||
to rebooting the machine.
|
||||
|
|
@ -788,6 +788,84 @@ only be used once, making them relatively for inclusion in the query string.
|
|||
to any API endpoint. The query string should be added in the form of:
|
||||
`?token=randomly_generated_token`
|
||||
|
||||
## Power APIs
|
||||
The APIs below are available when the "power" plugin has been enabled.
|
||||
|
||||
### Get Devices
|
||||
- HTTP command:\
|
||||
`GET /machine/device_power/devices`
|
||||
|
||||
- Websocket command:\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.devices","id":"1"}`
|
||||
|
||||
- Returns:\
|
||||
An array of objects containing info for each configured device.
|
||||
```json
|
||||
{
|
||||
devices: [
|
||||
{
|
||||
device: <device_name>,
|
||||
status: <device_status>,
|
||||
type: <device_type>
|
||||
}, ...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Get Device Status
|
||||
- HTTP command:\
|
||||
`GET /machine/device_power/status?dev_one&dev_two`
|
||||
|
||||
- Websocket command:\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.status","id":"1",
|
||||
"params":{"dev_one":null, "dev_two": null}}`
|
||||
|
||||
- Returns:\
|
||||
An object containing status for each requested device
|
||||
```json
|
||||
{
|
||||
dev_one: <device_status>,
|
||||
dev_two: <device_status>,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### Power On Device(s)
|
||||
- HTTP command:\
|
||||
`POST /machine/device_power/on?dev_one&dev_two`
|
||||
|
||||
- Websocket command:\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.on","id":"1",
|
||||
"params":{"dev_one":null, "dev_two": null}}`
|
||||
|
||||
- Returns:\
|
||||
An object containing status for each requested device
|
||||
```json
|
||||
{
|
||||
dev_one: <device_status>,
|
||||
dev_two: <device_status>,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### Power Off Device(s)
|
||||
- HTTP command:\
|
||||
`POST /machine/device_power/off?dev_one&dev_two`
|
||||
|
||||
- Websocket command:\
|
||||
`{"jsonrpc":"2.0","method":"machine.device_power.off","id":"1",
|
||||
"params":{"dev_one":null, "dev_two": null}}`
|
||||
|
||||
- Returns:\
|
||||
An object containing status for each requested device
|
||||
```json
|
||||
{
|
||||
dev_one: <device_status>,
|
||||
dev_two: <device_status>,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket notifications
|
||||
Printer generated events are sent over the websocket as JSON-RPC 2.0
|
||||
notifications. These notifications are sent to all connected clients
|
||||
|
|
|
|||
Loading…
Reference in New Issue