From fca0cf30279b7f93e56c9b0bb47f5c3ad979d9ad Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Wed, 15 May 2024 07:31:20 -0400 Subject: [PATCH] docs: update sensor documentation Signed-off-by: Eric Callahan --- docs/configuration.md | 28 +++++++++++ docs/web_api.md | 114 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 135 insertions(+), 7 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 2d10df7..8d5d6a9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2866,6 +2866,18 @@ type: name: # The friendly display name of the sensor. # The default is the sensor source name. +parameter_{parameter_name}: +# Optional parameter descriptions. Each sensor can report +# one or parameters. Frontends can use this data to accurately +# present sensor details to the user. The {parameter_name} must +# be a valid measurement reported by the sensor. The value should be +# a newline separated list of key-value pairs describing the +# the measurement. Currently the only key used is "units". For +# example, the configuration for a parameter may look like the follwing: +# +# parameter_energy: +# units=kWh +# history_field_{field_name}: # Optional history field description. When provided the named # field will be tracked in Moonraker's Job History component. @@ -3015,6 +3027,14 @@ Example: [sensor mqtt_powermeter] type: mqtt name: Powermeter +parameter_power: + units=W +parameter_voltage: + units=V +parameter_current: + units=mA +parameter_energy: + units=kWh # Use a different display name state_topic: shellypro1pm-8cb113caba09/status/switch:0 # The response is a JSON object with a multiple fields that we convert to @@ -3048,6 +3068,14 @@ state_response_template: {set_result("voltage", edata["Voltage"])} {set_result("power", edata["Power"])} {set_result("current", edata["Current"])} +parameter_power: + units=W +parameter_voltage: + units=V +parameter_current: + units=mA +parameter_energy: + units=kWh history_field_energy_consumption: parameter=energy desc=Printer energy consumption diff --git a/docs/web_api.md b/docs/web_api.md index a0697dc..666bb00 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -5794,19 +5794,32 @@ The APIs below are available when the `[sensor]` component has been configured. #### Get Sensor List HTTP request: ```http -GET /server/sensors/list +GET /server/sensors/list?extended=False ``` JSON-RPC request: ```json { "jsonrpc": "2.0", "method": "server.sensors.list", + "params": { + "extended": false + } "id": 5646 } ``` + +Parameters: + +- `extended`: When set to `true` then each sensor will also include + parameter info and history field configuration. The default is false. + + Returns: -An array of objects containing info for each configured sensor. +An array of objects containing info for each configured sensor. The +`parameter_info` and `history_fields` items will only be present when +the `extended` parameter is set to true. + ```json { "sensors": { @@ -5817,7 +5830,45 @@ An array of objects containing info for each configured sensor. "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" + } + ] } } } @@ -5828,7 +5879,7 @@ Returns the status for a single configured sensor. HTTP request: ```http -GET /server/sensors/info?sensor=sensor1 +GET /server/sensors/info?sensor=sensor1&extended=false ``` JSON-RPC request: ```json @@ -5836,14 +5887,25 @@ JSON-RPC request: "jsonrpc": "2.0", "method": "server.sensors.info", "params": { - "sensor": "sensor1" + "sensor": "sensor1", + "extended": false }, "id": 4564 } ``` + +Parameters: + +- `extended`: When set to `true` then the response will also include + parameter info and history field configuration. The default is false. + + Returns: -An object containing sensor information for the requested sensor: +An object containing sensor information for the requested sensor. The +`parameter_info` and `history_fields` items will only be present when +the `extended` parameter is set to true. + ```json { "id": "sensor1", @@ -5852,7 +5914,45 @@ An object containing sensor information for the requested sensor: "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" + } + ] } ```