Skip to content

Switches, Sensors, and Devices

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.

Power Endpoints

Moonraker's power component enables switch-like device management. Various device types are supported, including GPIOs and HTTP controlled devices.

The endpoints in this section are available when one or more [power <device_name>] sections are configured in moonraker.conf.

Get Device List

HTTP Request
GET /machine/device_power/devices
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.devices",
    "id": 5646
}
Example Response
{
    "devices": [
        {
            "device": "green_led",
            "status": "off",
            "locked_while_printing": true,
            "type": "gpio"
        },
        {
            "device": "printer",
            "status": "off",
            "locked_while_printing": false,
            "type": "tplink_smartplug"
        }
    ]
}
Response Specification
Field Type Description
devices [object] An array of Power Device Status objects.
Power Device Status
Field Type Description
device string The configured name of the device.
status string The current state of the device.
locked_while_printing bool When set to true the power device status may not be changed when Klipper is printing.
type string The Device Type of the device.
Power Device State
Device State Description
on The device is powered on.
off The device is powered off.
init The device is initializing.
error The device encountered an error.
Device Type
Device Type Description
gpio The device is controlled by a GPIO on the local machine.
klipper_device The device is controlled by Klipper.
tplink_smartplug The device is a TPLink Smartplug Device (aka Kasa Device.)
tasmota The device is a HTTP device running Tasmota firmware.
shelly The device is a Shelly branded device (V1 API).
homeseer The device is a device managed by HomeSeer.
homeassistant The device is a device managed by Home Assistant.
loxonev1 The device is a Loxone V1 device.
rf The device is a RF device with a GPIO interface.
mqtt The device is a device available over MQTT.
smartthings The device is a Samsung SmartThings device.
hue The device is a Phillips Hue device.
http The device is a generic HTTP device.
uhubctl The device is a USB port with a controller compatible with uhubctl.

Note

It is possible for unofficial 3rd party extensions to register their own Device Types and implementations.

Get Device State

Requests the device state for a single configured device.

HTTP Request
GET /machine/device_power/device?device=green_led
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.get_device",
    "params": {
        "device": "green_led"
    },
    "id": 4564
}
Example Response
{
    "green_led": "off"
}
Response Specification
Field Type Description
device_name string The current state of the requested device.

Set Device State

Toggle, turn on, or turn off a specified device.

HTTP Request
POST /machine/device_power/device
Content-Type: application/json

{
    "device": "green_led",
    "action": "on"
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.post_device",
    "params": {
        "device": "green_led",
        "action": "on"
    },
    "id": 4564
}
Parameters
Name Type Default Description
device string REQUIRED The name of the device to manage.
action string REQUIRED The action to perform on the device.
Power Device Action
Action Description
on Turns the device on.
off Turns the device off.
toggle Toggles device state.
Example Response
{
    "green_led": "off"
}
Response Specification
Field Type Description
device_name string The current state of the requested device.

Get Batch Device Status

Get power status for the requested devices. At least one device must be specified.

HTTP Request
GET /machine/device_power/status?dev_one&dev_two
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.status",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}
Parameters
Name Type Default Description
device null null 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.

Example Response
{
    "green_led": "off",
    "printer": "off"
}
Response Specification
Field Type Description
device_name string The current state of the requested device.

Batch Power On Devices

Power on the requested devices. At least one device must be specified.

HTTP Request
POST /machine/device_power/on
Content-Type: application/json

{
    "dev_one": null,
    "dev_two": null
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.on",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}
Parameters
Name Type Default Description
device null null 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.

Batch Power Off Devices

Power off the requested devices. At least one device must be specified.

HTTP Request
POST /machine/device_power/off?dev_one&dev_two
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.device_power.off",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}
Parameters
Name Type Default Description
device null null 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.

WLED Endpoints

The wled component can be used to perform high level management of devices running WLED firmware.

The endpoints in this section are available when one or more [wled <dev_name>] sections are configured in moonraker.conf.

For lower-level control of wled consider using the WLED JSON API directly.

Get strips

HTTP Request
GET /machine/wled/strips
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.strips",
    "id": 7123
}
Example Response
{
    "strips": {
        "lights": {
            "strip": "lights",
            "status": "on",
            "chain_count": 79,
            "preset": -1,
            "brightness": 255,
            "intensity": -1,
            "speed": -1,
            "error": null
        },
        "desk": {
            "strip": "desk",
            "status": "on",
            "chain_count": 60,
            "preset": 8,
            "brightness": -1,
            "intensity": -1,
            "speed": -1,
            "error": null
        }
    }
}
Response Specification
Field Type Description
strips object A container of WLED Strip Status objects. The keys in this object will be the name of strip with the values containing strip status.
WLED Strip Status
Field Type Description
strip string The configured name of the strip.
status string The current state of the WLED strip. Will be on if the strip is enabled or off if the strip is disabled.
chain_count int The number of LEDs configured on the chain.
preset int The numbered preset. Will be -1 if no preset is selected.
brightness int The brightness value set by Moonraker. Will be -1 if Moonraker has not set this value.
intensity int The intensity value set by Moonraker. Will be -1 if Moonraker has not set this value.
speed int The speed value set by Moonraker. Will be -1 if Moonraker has not set this value.
error string | null A message describing last error returned from an attempted WLED command. Will be null if no error is returned.

Get strip status

HTTP Request
GET /machine/wled/status?strip1&strip2
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.status",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7124
}
Parameters
Name Type Default Description
strip null null There may be multiple strips specified, where the keys the requested strip names. Values should always be null.
Example Response
{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "on",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}
Response Specification
Field Type Description
strip object There may be multiple strips, where the keys are strip names and the values are WLED strip status objects.

Turn strip on

Turns the specified strips on to the initial colors or initial preset.

HTTP Request
POST /machine/wled/on
Content-Type: application/json

{
    "lights": null,
    "desk": null
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.on",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7125
}
Example Response
{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "on",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}
Response Specification
Field Type Description
strip object There may be multiple strips, where the keys are strip names and the values are WLED strip status objects.

Turn strip off

Turns off all specified strips.

HTTP Request
POST /machine/wled/off
Content-Type: application/json

{
    "lights": null,
    "desk": null
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.off",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7126
}
Parameters
Name Type Default Description
strip null null There may be multiple strips specified, where the keys the requested strip names. Values should always be null.
Example Response
{
    "lights": {
        "strip": "lights",
        "status": "off",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "off",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}
Response Specification
Field Type Description
strip object There may be multiple strips, where the keys are strip names and the values are WLED strip status objects.

Toggle strip on/off state

Toggles the current enabled state for the requested strips.

HTTP Request
POST /machine/wled/toggle
Content-Type: application/json

{
    "lights": null,
    "desk": null
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.toggle",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7127
}
Parameters
Name Type Default Description
strip null null There may be multiple strips specified, where the keys the requested strip names. Values should always be null.
Example Response
{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "off",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}
Response Specification
Field Type Description
strip object There may be multiple strips, where the keys are strip names and the values are WLED strip status objects.

Get individual strip state

HTTP Request
GET /machine/wled/strip?strip=lights
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.get_strip",
    "params": {
        "strip": "lights"
    }
    "id": 7128
}
Example Response
{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": 1,
        "brightness": 50,
        "intensity": 255,
        "speed": 255,
        "error": null
    }
}
Response Specification
Field Type Description
strip object An object containing the requested strip's current status. The key is the strip's name, the value is an WLED strip status object.

Control individual strip state

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.

HTTP Request
POST /machine/wled/strip
Content-Type: application/json

{
    "strip": "lights",
    "action" "on",
    "preset": 3,
    "brightness": 200,
    "intensity": 50,
    "speed": 180
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "machine.wled.post_strip",
    "params": {
        "strip": "lights",
        "action" "on",
        "preset": 3,
        "brightness": 200,
        "intensity": 50,
        "speed": 180
    },
    "id": 7128
}
Parameters
Name Type Default Description
strip string REQUIRED The name of the strip to control.
action string REQUIRED The WLED Action to execute on the strip.
preset int INITIAL_VAL 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.

Example Response
{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": 1,
        "brightness": 50,
        "intensity": 255,
        "speed": 255,
        "error": null
    }
}
Response Specification
Field Type Description
strip object An object containing the requested strip's current status. The key is the strip's name, the value is an WLED strip status object.

Sensor endpoints

The endpoints in this section are available when at least one [sensor <sensor_name>] section has been configured in moonraker.conf.

Get Sensor List

HTTP Request
GET /server/sensors/list?extended=False
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.sensors.list",
    "params": {
        "extended": false
    }
    "id": 5646
}
Parameters
Name Type Default Description
extended bool false 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.

Get Sensor Information

Returns the status for a single configured sensor.

HTTP Request
GET /server/sensors/info?sensor=sensor1&extended=false
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.sensors.info",
    "params": {
        "sensor": "sensor1",
        "extended": false
    },
    "id": 4564
}
Parameters
Name Type Default Description
sensor string REQUIRED The ID of the requested sensor.
extended bool false When set to true the status for the sensor will include parameter_info and history_fields fields.
Example Response
{
    "id": "sensor1",
    "friendly_name": "Sensor 1",
    "type": "mqtt",
    "values": {
        "value1": 0.0,
        "value2": 120.0
    },
    "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

The response specification is a Sensor Status object.

Get Sensor Measurements

Returns all recorded measurements for a configured sensor.

HTTP Request
GET /server/sensors/measurements?sensor=sensor1
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.sensors.measurements",
    "params": {
        "sensor": "sensor1"
    },
    "id": 4564
}
Parameters
Name Type Default Description
sensor string REQUIRED The ID of the requested sensor.
Example Response
{
    "sensor1": {
        "value1": [
            3.1,
            3.2,
            3.0
        ],
        "value2": [
            120.0,
            120.0,
            119.9
        ]
    }
}
Response Specification
Field Type Description
sensor_id object A Sensor Measurements object. The key for this item will be the sensor id.
Sensor Measurements
Field Type Description
param_name [float | int] 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.

Get Batch Sensor Measurements

Returns recorded measurements for all sensors.

HTTP Request
GET /server/sensors/measurements
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.sensors.measurements",
    "id": 4564
}
Example Response
{
    "sensor1": {
        "value1": [
            3.1,
            3.2,
            3.0
        ],
        "value2": [
            120.0,
            120.0,
            119.9
        ]
    },
    "sensor2": {
        "value_a": [
            1,
            1,
            0
        ]
    }
}
Response Specification
Field Type Description
sensor_id object A Sensor Measurements
object. There may be multiple sensor items, where the keys are sensor IDs.

MQTT Endpoints

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.

Publish a topic

HTTP Request
POST /server/mqtt/publish
Content-Type: application/json

{
    "topic": "home/test/pub",
    "payload": "hello",
    "qos": 0,
    "retain": false,
    "timeout": 5
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.mqtt.publish",
    "params":{
        "topic": "home/test/pub",
        "payload": "hello",
        "qos": 0,
        "retain": false,
        "timeout": 5
    },
    "id": 4564
}
Parameters
Name Type Default Description
topic string REQUIRED The topic to publish to the network.
payload any null 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.

Example Response
{
    "topic": "home/test/pub"
}
Response Specification
Field Type Description
topic string The topic that was successfully published.

Subscribe to a topic

HTTP Request
POST /server/mqtt/subscribe
Content-Type: application/json

{
    "topic": "home/test/sub",
    "qos": 0,
    "timeout": 5
}
JSON-RPC Request
{
    "jsonrpc": "2.0",
    "method": "server.mqtt.subscribe",
    "params":{
        "topic": "home/test/sub",
        "qos": 0,
        "timeout": 5
    },
    "id": 4564
}
Parameters
Name Type Default Description
topic string REQUIRED 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.