This document covers the API for managing various devices
through Moonraker. It should be noted that the endpoints
here are only available when such devices are added to
Moonraker's configuration.
There may be multiple devices specified, where the keys the requested device names. Values should always be null.
Note
The strangeness of this parameter specification is an artifact
from an early attempt to simplify the query string and maintain
compatibility with JSON parameters.
There may be multiple devices specified, where the keys the requested device names. Values should always be null.
Note
The strangeness of this parameter specification is an artifact
from an early attempt to simplify query string parameters and maintain
compatibility with JSON parameters.
Example Response
{"green_led":"on","printer":"on"}
Response Specification
Field
Type
Description
device_name
string
The current state of the requested device. The field name of the response is the device's configured name. The response may contain multiple devices.
There may be multiple devices specified, where the keys the requested device names. Values should always be null.
Note
The strangeness of this parameter specification is an artifact
from an early attempt to simplify query string parameters and maintain
compatibility with JSON parameters.
Example Response
{"green_led":"off","printer":"off"}
Response Specification
Field
Type
Description
device_name
string
The current state of the requested device. The field name of the response is the device's configured name. The response may contain multiple devices.
Toggle, turn on, turn off, turn on with preset, turn on with brightness, or
turn on preset will some of brightness, intensity, and speed. Or simply set
some of brightness, intensity, and speed.
The numbered preset stored on the WLED controller. The preset is only applied when a strip is enabled, either through the on or toggle actions.
brightness
int
CURRENT_VAL
Changes the brightness of the LEDs on the strip. The permitted range is 1-255.
intensity
int
CURRENT_VAL
Changes the intensity value of the current preset. The permitted range is 0-255. This setting is ignored if no preset is active.
speed
int
CURRENT_VAL
Changes the speed value of the current preset. The permitted range is 0-255. This setting is ignored if no preset is active.
WLED Action
Action
Description
on
Enable the strip. The on action may be accompanied by one or more of the preset, brightness, intensity or speed parameters, which will be applied immediately.
off
Disable the strip.
toggle
Toggle the strip's enabled state.
control
Modify brightness, intensity, and/or speed without changing the current enabled state. At least one of the these parameters must be provided when the action is control.
Note
When a strip is enabled the brightness, intensity, and speed
values will be reset to the preset's default values.
When set to true the status for each sensor will include parameter_info and history_fields fields.
Example Response
{"sensors":{"sensor1":{"id":"sensor1","friendly_name":"Sensor 1","type":"mqtt","values":{"value1":0,"value2":119.8},"parameter_info":[{"units":"kWh","name":"value1"},{"units":"V","name":"value2"}],"history_fields":[{"field":"power_consumption","provider":"sensor sensor1","description":"Printer Power Consumption","strategy":"delta","units":"kWh","init_tracker":true,"exclude_paused":false,"report_total":true,"report_maximum":true,"precision":6,"parameter":"value1"},{"field":"max_voltage","provider":"sensor sensor1","description":"Maximum voltage","strategy":"maximum","units":"V","init_tracker":true,"exclude_paused":false,"report_total":false,"report_maximum":false,"precision":6,"parameter":"value2"}]}}}
Response Specification
Field
Type
Description
sensors
object
An object containing the sensor status. Each key will be the sensor's ID, each value will be a sensor status object.
Sensor Status
Field
Type
Description
id
string
The sensor's configured ID.
friendly_name
string
The sensor's configured friendly name.
type
string
The sensor's configured type. Currently only mqtt types are supported.
values
object
A Sensor Values object reporting the most recent values measured by the sensor.
Sensor Values
Field
Type
Description
value_name
any
The object may contain multiple values, where each key is the name of a parameter tracked by the sensor, and the value is the most recent reported measurement.
parameter_info
[object]
An array of Parameter Info objects. Only included with extended responses.
history_fields
[object]
An array of History Field objects. Only reported with extended responses. Will be an empty list if no history fields are configured for the sensor.
Parameter Info
Field
Type
Description
name
string
The name of a parameter measured by the sensor.
custom
string
The parameter_info object may contain additional custom fields provided in the sensor's configuration. It is common for a sensor to add a units field specifying the type of data measured by the sensor.
History Fields
Field
Type
Description
field
string
The name of the auxiliary field to be stored in the job history.
provider
string
The object providing data for history tracking. Will be the sensor's config section name, ie: sensor my_sensor.
description
string
A brief description of the measurement.
strategy
string
The strategy used to track data stored in the job history.
units
string | null
The units, if applicable, for the value stored in history.
init_tracker
bool
When true the first value tracked will be initialized to the most recent sensor measurement.
exclude_paused
bool
When true tracking will exclude measurements taken while a job is paused.
report_total
bool
When true the final tracked value will be accumulated and included in the history component's job totals.
report_maximum
bool
When true the maximum final tracked value during a job will be included in the history component's job totals.
precision
int
The precision of the final tracked value, presuming it is a float.
parameter
string
The name of the sensor parameter to track.
History Tracking Strategy
Strategy
Description
basic
Stores the last value measured during a job.
delta
Stores the difference between the last and first values measured during a job.
accumulate
Stores the cumulative value of all measurements reported during the job.
average
Stores an average of all measurements taken during the job.
maximum
Stores the maximum value measured during the job.
minimum
Stores the minimum value measured during the job.
collect
Stores all values measured during the job in an array.
An array of decimal numbers containing all stored measurements for the named parameter. There may be multiple items in this object, where they keys are parameter names.
Moonraker supports mqtt connections for communicating with other
devices on the network. In addition to the power
and sensor implementations Moonraker provides
endpoints for clients to publish and subscribe to topics on the
network. These endpoints are available when [mqtt] has been configured
in moonraker.conf.
Note
These endpoints are not available over the mqtt transport as they
are redundant. MQTT clients can publish and subscribe to
topics directly.
The payload to send with the topic. May be a boolean, float, integer, object, or array. Objects and Arrays are JSON encoded. When this parameter is omitted an empty payload is sent.
qos
int
CONFIG_DEFAULT
The QOS level to use when publishing a topic. Valid range is 0-2.
retain
bool
false
When set to true the topic's retain flag is set.
timeout
float
null
A timeout, in seconds, in which Moonraker will wait for acknowledgement from the broker. If the timeout is exceeded the request will return with a 504 error. Only applies to QOS levels 1 2. When omitted the request will wait indefinitely.
Tip
The retain flag tells the broker to save, or "retain", the payload
associated with the topic. Only the most recent payload published
to the topic is retained. Subsequent subscribers to the topic will
immediately receive the retained payload.
To clear a retained value of a topic, publish the topic with an empty
payload and retain set to true.
The topic to subscribe to. Wildcards are not allowed.
qos
int
CONFIG_DEFAULT
The QOS level to use for the subscription. Valid range is 0-2.
timeout
float
null
A timeout, in seconds, to wait until a response is received. The request will return with a 504 error if the timeout is exceeded. By default the request will wait indefinitely.
Note
If the topic was previously published with a retained payload this request
will return immediately with the retained value.
Example Response
{"topic":"home/test/pub","payload":"test"}
Response Specification
Field
Type
Description
topic
string
The name of the topic subscribed to.
payload
string | object | array | null
The payload received with the topic.
Note
If the payload contains a JSON value it will decoded and
set as an object or array before re-encoding the full response back
to JSON. Otherwise it will be a string or null if the
payload is empty.