diff --git a/docs/changelog.md b/docs/changelog.md index 708e343..f45e555 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -35,6 +35,10 @@ The format is based on [Keep a Changelog]. - **machine**: Add support for system peripheral queries - **mqtt**: Added the `status_interval` option to support rate limiting - **mqtt**: Added the `enable_tls` option to support ssl/tls connections +- **history**: Added `user` field to job history data +- **history**: Added support for auxiliary history fields +- **spoolman**: Report spool ids set during a print in history auxiliary data +- **sensor**: Added support for history fields reported in auxiliary data ### Fixed diff --git a/docs/configuration.md b/docs/configuration.md index 0aab6f7..6645a16 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -41,7 +41,7 @@ opt_four: Once again\# not a comment resulting `#` is stored in the value. - Option `opt_three` resolves to a value of `This is the value`. The comment specifier is preceded by whitespace, thus the remainder of the line is - evaluted as a comment and removed from the option. + evaluated as a comment and removed from the option. - Option `opt_four` resolves to a value of `Once again\# not a comment`. The `\` character is not preceded by whitespace and not evaluated as an escape sequence, thus the escape character is not removed from the value. @@ -128,7 +128,7 @@ check_klipper_config_path: True # By default Moonraker will validate that Klipper's configuration file exists # within the data path's "config" folder, as this is a requirement for # Moonraker to write to the configuration. If this validation check fails -# Moonaker will warn the user. Installations that do not wish to use Moonraker +# Moonraker will warn the user. Installations that do not wish to use Moonraker # to manage Klipper's configuration may set this option to False to bypass the # location check. The default is True. enable_object_processing: False @@ -1324,9 +1324,8 @@ address: # A valid ip address or hostname of the Philips Hue Bridge. This # parameter must be provided. port: -# A port number if an alternative Zigbee bridge is used on a HTTP port +# A port number if an alternative Zigbee bridge is used on a HTTP port # different from the default 80/443 -# user: # The api key used for request authorization. This option accepts # Jinja2 Templates, see the [secrets] section for details. @@ -2814,8 +2813,102 @@ type: name: # The friendly display name of the sensor. # The default is the sensor source name. +history_field_{field_name}: +# Optional history field description. When provided the named +# field will be tracked in Moonraker's Job History component. +# The "field_name" portion of the option is the identifier used +# when reported in the history. Multiple history fields may be +# added and tracked for a sensor. See the "History Fields" note +# for a detailed explanation of this option. ``` +!!! note "History Fields" + A `history_field_{name}` option must contain a series of key-value pairs. + The key and value must be separated by an equal sign (=), and each + pair must be separated by a newline. The following keys are + available: + + - `parameter`: The name of the sensor parameter which is used to + provide values for this field. This name must match a field name + set in the specific sensor implementation (ie: see the + "state_response_template" option for the MQTT type.) This must + be provided. + - `desc`: A brief description of the field. + - `strategy`: The tracking strategy used to calculate the value + stored in the history. See below for available strategies. + The default is "basic". + - `units`: An optional unit specifier for the value + - `init_tracker`: When set to true the tracked value will be initialized + to the last sensor measurement when a job starts. The "delta" + strategy will initialize its "last value", setting this measurement + as the reference rather than the first received after the print starts. + Default is false. + - `exclude_paused`: When set to true the values received when + a job is paused will be ignored. Default is false. + - `report_total`: When set to true the value reported for all + jobs will be accumulated and reported in the history totals. + Default is false. + - `report_maximum`: When set to true maximum value for all jobs + will be reported in the history totals. Default is false. + - `precision`: An integer value indicating the precision to use when + reporting decimal values. This precision applies to both job history + AND job totals. The default is no precision, ie: no rounding will + occur. + + Note that job totals for history fields only persist for a currently + configured sensor and history field name. If the name of the sensor + changes, the name of the field changes, or if either are removed + from the configuration, then their totals will be discarded. This + prevents the accumulation of stale totals. + + Moonraker provides several history tracking strategies that can be used + accommodate how values should be tracked and stored in the job history: + + - `basic`: This strategy should be used if the value should be stored + in history directly as it is received. Simply put, the last value + received before a job completes wiill the the value stored in the job + history. + - `accumulate`: When a job starts, the tracked value initialized to 0 or + the last received measurement. New measurements will be added to the + tracked value as they are received. The total cumulative value will be + reported when the job ends. + - `delta`: When a job starts the tracked value is 0. The total value + will be the delta between the final measurement received before the job + ends and the first measurement received when after job begins. Note that + if `exclude_paused` is set then the tracker will accumulate deltas + between pauses. If the measurement does not update frequently this could + significantly alter the final result. + - `average`: Reports an average of all measurements received during the job. + - `maximum`: Reports the maximum value of all measurements received during + the job. + - `minimum`: Reports the minimum value of all measurements received during + the job. + - `collect`: Measurements are stored in a list as they are received. + Duplicate measurements are discarded. A maximum of 100 entries may + be stored, the oldest measurements will be discarded when this limit + is exceeded. This strategy is useful for a sensor that reports some + data infrequently and its desirable to include all measurements in the + job history. For example, the `spoolman` component uses this strategy + to report all spool IDs set during a job. When this strategy is enabled + the `track_total` and `track_maximum` options are ignored, as it is not + possible to report totals for a collection. + + Example: + + ``` + history_field_total_energy: + parameter=energy + desc=Printer power consumption + strategy=delta + units=kWh + init_tracker=false + exclude_paused=false + report_total=true + report_maximum=true + precision=6 + ``` + + #### MQTT Sensor Configuration The following options are available for `mqtt` sensor types: @@ -2881,6 +2974,55 @@ state_response_template: {set_result("energy", notification["aenergy"]["by_minute"][0]|float * 0.000001)} ``` +Tasmota Example: + +!!! Note + It may be necessary to set Tasmota's Telemetry Period to a low value + to acheive a decent response. This can be done in the with the + `TelePeriod` command via the console. For example, the command + to set the telemetry period to 10 seconds is: + + `cmnd/%device_name%/TelePeriod` with a payload of `10`. + +```ini +[sensor tasmota_power] +type: mqtt +state_topic: tele/tasmota_switch/SENSOR +state_response_template: + {% set resp = payload|fromjson %} + {% set edata = resp["ENERGY"] %} + {set_result("energy", edata["Total"])} + {set_result("voltage", edata["Voltage"])} + {set_result("power", edata["Power"])} + {set_result("current", edata["Current"])} +history_field_energy_consumption: + parameter=energy + desc=Printer energy consumption + strategy=delta + units=kWh + init_tracker=true + precision=6 + exclude_paused=false + report_total=true + report_maximum=true +history_field_average_current: + parameter=current + desc=Average current draw + strategy=average + units=A + report_total=false + report_maximum=true +# Mulitple history fields may track the same sensor parameter: +history_field_max_current: + parameter=current + desc=Maximum current draw + strategy=maximum + units=A + init_tracker=true + report_total=false + report_maximum=false +``` + ### `[spoolman]` Enables integration with the [Spoolman](https://github.com/Donkie/Spoolman) diff --git a/docs/web_api.md b/docs/web_api.md index abffcd7..a0697dc 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -1939,6 +1939,7 @@ GET /machine/peripherals/video "camera_name": "unicam", "driver_name": "unicam", "hardware_bus": "platform:3f801000.csi", + "modes": [], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -1958,6 +1959,62 @@ GET /machine/peripherals/video "camera_name": "UVC Camera (046d:0825)", "driver_name": "uvcvideo", "hardware_bus": "usb-3f980000.usb-1.1", + "modes": [ + { + "format": "YUYV", + "description": "YUYV 4:2:2", + "flags": [], + "resolutions": [ + "640x480", + "160x120", + "176x144", + "320x176", + "320x240", + "352x288", + "432x240", + "544x288", + "640x360", + "752x416", + "800x448", + "800x600", + "864x480", + "960x544", + "960x720", + "1024x576", + "1184x656", + "1280x720", + "1280x960" + ] + }, + { + "format": "MJPG", + "description": "Motion-JPEG", + "flags": [ + "COMPRESSED" + ], + "resolutions": [ + "640x480", + "160x120", + "176x144", + "320x176", + "320x240", + "352x288", + "432x240", + "544x288", + "640x360", + "752x416", + "800x448", + "800x600", + "864x480", + "960x544", + "960x720", + "1024x576", + "1184x656", + "1280x720", + "1280x960" + ] + } + ], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -1975,6 +2032,7 @@ GET /machine/peripherals/video "camera_name": "bcm2835-isp", "driver_name": "bcm2835-isp", "hardware_bus": "platform:bcm2835-isp", + "modes": [], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -1992,6 +2050,7 @@ GET /machine/peripherals/video "camera_name": "bcm2835-isp", "driver_name": "bcm2835-isp", "hardware_bus": "platform:bcm2835-isp", + "modes": [], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -2009,6 +2068,7 @@ GET /machine/peripherals/video "camera_name": "bcm2835-isp", "driver_name": "bcm2835-isp", "hardware_bus": "platform:bcm2835-isp", + "modes": [], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -2026,6 +2086,7 @@ GET /machine/peripherals/video "camera_name": "bcm2835-isp", "driver_name": "bcm2835-isp", "hardware_bus": "platform:bcm2835-isp", + "modes": [], "capabilities": [ "VIDEO_CAPTURE", "EXT_PIX_FORMAT", @@ -2134,6 +2195,7 @@ V4L2 Device | `alt_name` | string? | An alternative device name optionally reported by | | | | sysfs. Will be `null` if the name file does not exist. |^ | `hardware_bus` | string | A description of the hardware location of the device | +| `modes` | array | An array of V4L2 mode objects. | | `capabilities` | array | An array of strings indicating the capabilities the | | | | device supports as reported by V4L2. |^ | `version` | string | The device version as reported by V4L2. | @@ -2145,6 +2207,16 @@ V4L2 Device | `usb_location` | string? | An identifier derived from the reported usb bus and | | | | device numbers. Will be `null` for non-usb devices. |^ +V4L2 Mode + +| Field | Type | Description | +| ------------- | :----: | ------------------------------------------------------------ | +| `description` | string | The description of the mode reported by the V4L2 driver. | +| `flags` | array | An array of strings describing flags reported by the driver. | +| `format` | string | The pixel format of the mode. | +| `resolutions` | array | An array of strings describing the resolutions supported by | +| | | the mode. Each entry is reported as `x` |^ + Libcamera Device | Field | Type | Description | @@ -6374,7 +6446,61 @@ An array of requested historical jobs: "print_duration": 18.37201827496756, "status": "completed", "start_time": 1615764496.622146, - "total_duration": 18.37201827496756 + "total_duration": 18.37201827496756, + "user": "testuser", + "auxiliary_data": [ + { + "provider": "sensor hist_test", + "name": "power_consumption", + "value": 4.119977, + "description": "Printer Power Consumption", + "units": "kWh" + }, + { + "provider": "sensor hist_test", + "name": "max_current", + "value": 2.768851, + "description": "Maximum current draw", + "units": "A" + }, + { + "provider": "sensor hist_test", + "name": "min_current", + "value": 0.426725, + "description": "Minmum current draw", + "units": "A" + }, + { + "provider": "sensor hist_test", + "name": "avg_current", + "value": 1.706872, + "description": "Average current draw", + "units": "A" + }, + { + "provider": "sensor hist_test", + "name": "status", + "value": 2, + "description": "Power Switch Status", + "units": null + }, + { + "provider": "sensor hist_test", + "name": "filament", + "value": 19.08058495194607, + "description": "filament usage tracker", + "units": "mm" + }, + { + "provider": "spoolman", + "name": "spool_ids", + "value": [ + 1 + ], + "description": "Spool IDs used", + "units": null + } + ] } ] } @@ -6406,7 +6532,27 @@ An object containing the following total job statistics: "total_filament_used": 11615.718840001999, "longest_job": 11665.191012736992, "longest_print": 11348.794790096988 - } + }, + "auxiliary_totals": [ + { + "provider": "sensor hist_test", + "field": "power_consumption", + "maximum": 4.119977, + "total": 4.119977 + }, + { + "provider": "sensor hist_test", + "field": "avg_current", + "maximum": 1.706872, + "total": null + }, + { + "provider": "sensor hist_test", + "field": "filament", + "maximum": 19.08058495194607, + "total": 19.08058495194607 + } + ] } ``` @@ -6439,7 +6585,27 @@ The totals prior to the reset: "total_filament_used": 11615.718840001999, "longest_job": 11665.191012736992, "longest_print": 11348.794790096988 - } + }, + "last_auxiliary_totals": [ + { + "provider": "sensor hist_test", + "field": "power_consumption", + "maximum": 4.119977, + "total": 4.119977 + }, + { + "provider": "sensor hist_test", + "field": "avg_current", + "maximum": 1.706872, + "total": null + }, + { + "provider": "sensor hist_test", + "field": "filament", + "maximum": 19.08058495194607, + "total": 19.08058495194607 + } + ] } ```