docs: document history additions

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

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
 

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
@@ -1326,7 +1326,6 @@ address:
 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)

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 `<WIDTH>x<HEIGHT>`      |^
+
 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
         }
+    ]
 }
 ```