diff --git a/README.md b/README.md index fb62c62..f4d3086 100644 --- a/README.md +++ b/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 \ No newline at end of file +- [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 diff --git a/docs/api_changes.md b/docs/api_changes.md index 169083f..8b28e04 100644 --- a/docs/api_changes.md +++ b/docs/api_changes.md @@ -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 diff --git a/docs/installation.md b/docs/installation.md index 93715d5..38f6c8a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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: diff --git a/docs/user_changes.md b/docs/user_changes.md new file mode 100644 index 0000000..6911001 --- /dev/null +++ b/docs/user_changes.md @@ -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. diff --git a/docs/web_api.md b/docs/web_api.md index 9990511..ab06132 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -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: , + status: , + 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: , + dev_two: , + ... + } + ``` + +### 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: , + dev_two: , + ... + } + ``` + +### 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: , + dev_two: , + ... + } + ``` + ## Websocket notifications Printer generated events are sent over the websocket as JSON-RPC 2.0 notifications. These notifications are sent to all connected clients