3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: document history additions 

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2024-05-03 08:16:50 -04:00
parent 81899e04fd
commit 326d23a509
3 changed files with 319 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/changelog.md
View File

@ -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

150
docs/configuration.md
View File

@ -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)

172
docs/web_api.md
View File

@ -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
}
]
}
```