Merge pull request #3784 from Maxwell456/feature/repeater-history

Add min/max/avg history queries to repeaters
This commit is contained in:
fdlamotte authored and GitHub committed 2026-11-10 12:42:53 -04:00
commit 66d404eac8
14 files changed
+530 -85

No files matched your search

+7
View File
@@ -1247,6 +1247,13 @@ Covers serial NMEA receivers (`MicroNMEALocationProvider`).
---
### Repeater health history
History is queried over the mesh using the sensor-compatible `0x04` min/max/average
request; there is no history CLI command. Retention and recording interval are controlled
by `REPEATER_HISTORY_SLOTS` and `REPEATER_HISTORY_INTERVAL_SECS` at build time.
See [Repeater health history](repeater_history.md) for the channel mapping and flags.
### Ethernet (when Ethernet support is compiled in)
Ethernet support is available on RAK4631 boards with a RAK13800 (W5100S) Ethernet module. Use the `_ethernet` firmware variants (e.g. `RAK_4631_repeater_ethernet`) to enable this feature.
+24 -2
View File
@@ -103,7 +103,7 @@ For the common chat/server helpers in `BaseChatMesh`, the current request type v
| `0x01` | get stats | get stats of repeater or room server |
| `0x02` | keepalive | (deprecated) |
| `0x03` | get telemetry | request node telemetry |
| `0x04` | get min/max/avg | get sensor node stats on time series data |
| `0x04` | get min/max/avg | get sensor or repeater time series statistics |
| `0x05` | get acl | node ACL query |
| `0x06` | get neighbors | node neighbors query |
| `0x08` | subscribe | subscribe to telemetry push |
@@ -140,7 +140,7 @@ Gets information about the node, possibly including the following:
| req type | 1 | 0x03 (request sub type) |
| permission mask | 1 | bitwise inverse mask to AND to permissions (0 = get ALL telem values) |
#### Get Min/Max/Ave (Sensor nodes)
#### Get Min/Max/Ave (Sensor and repeater nodes)
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
@@ -150,6 +150,28 @@ Gets information about the node, possibly including the following:
| end | 4 | ending time, seconds ago |
| reserved | 2 | should be zeroes |
Requires an authenticated client with the READ_ONLY role or higher. The range includes
samples whose age is `end <= age < start`, in seconds. Request integers are little-endian.
The repeater uses exactly the sensor request and response layout.
The response body (after decryption) is:
| Field | Size (bytes) | Description |
|----------------|--------------|-------------|
| tag | 4 | echoed request timestamp, little-endian |
| current time | 4 | current node RTC Unix time, little-endian |
| series | variable | up to 8 series records, described below |
Each series record contains a channel byte, an LPP type byte, then min, max, and average
in that order. Each value uses the type's Cayenne LPP size, multiplier, sign, and
big-endian encoding. There is no count byte; parse records to the end of the response.
Nonzero reserved bytes return only the tag and current time.
Repeater history is pull-only, uses uptime internally, and omits series with no valid
samples in the requested range. Its returned current time still comes from the RTC;
an unset or corrected RTC does not affect sampling or range selection. See
[Repeater health history](repeater_history.md) for channels, retention, and build flags.
#### Subscribe to Telemetry push - (Sensor nodes)
| Field | Size (bytes) | Description |
+84
View File
@@ -0,0 +1,84 @@
# Repeater health history
The simple repeater keeps health samples in RAM and answers mesh request
`REQ_TYPE_GET_AVG_MIN_MAX` (`0x04`). A logged-in client needs READ_ONLY access or
higher. This is pull-only: recording history sends no packets. Existing GET_STATUS
and telemetry responses are unchanged.
## Series
| Channel | LPP type | Value recorded each interval |
|---------|----------|------------------------------|
| 200 | `LPP_VOLTAGE` (116) | Battery voltage in V, averaged from periodic reads every 15 seconds |
| 201 | `LPP_ANALOG_INPUT` (2, signed) | Radio noise floor in dBm at the end of the interval |
| 202 | `LPP_PERCENTAGE` (120) | TX airtime percentage over the elapsed interval |
| 203 | `LPP_PERCENTAGE` (120) | RX airtime percentage over the elapsed interval |
| 204 | `LPP_TEMPERATURE` (103) | MCU temperature in degrees C, when supported |
These channels are dedicated to history. Existing self telemetry and GPS use channel 1;
`EnvironmentSensorManager` assigns at most 16 active entries to channels 2–17. Channels
200–204 therefore do not collide with current repeater telemetry. Custom sensor managers
should leave this range free. History channels do not change the channels in `0x03`.
Battery averaging reduces the effect of short voltage dips during transmission. Noise
floor and temperature are point samples. Recording advances on fixed interval boundaries
without accumulating loop delays; the airtime denominator uses a separate actual
measurement timestamp. TX/RX values are unsigned counter deltas in
milliseconds divided by the actual elapsed interval, multiplied by 100. Percentages
use the sensor protocol's integer LPP encoding, so fractional percentages are truncated.
NaN temperatures and the radio driver's uncalibrated noise-floor sentinel (0 dBm)
are skipped. At most five series are returned, below the eight-series reply limit.
## Query and retention
Use the [sensor-compatible `0x04` request](payloads.md#get-minmaxave-sensor-and-repeater-nodes):
start and end are seconds ago, followed by two zero reserved bytes. For example,
`start=3600, end=0` selects samples from the last hour, including age zero and excluding
age 3600. The reply echoes the request timestamp, adds the current RTC time, and then
encodes each series as channel, LPP type, min, max, average. There is no series count.
Empty series are omitted; an empty range returns just the eight-byte header.
Sampling and queries use monotonic uptime, accumulated across `millis()` wraps. The
RTC is used only for the response timestamp. Samples occupy a fixed interval grid
anchored at the first valid sample. Missed intervals are empty (NaN) slots; a gap
at least as long as the ring capacity expires the old ring. Late readings are assigned
to their interval boundary, so their reported age can differ by less than one interval.
Only one timestamp is stored per series.
Unsigned second differences handle seconds-counter wrap; retained samples and query
ranges must span less than one full 32-bit seconds cycle (about 136 years).
The first sample is recorded after one interval. Each series retains the configured
number of interval slots, including missing intervals. History is lost on reboot and
is not written to flash.
## Build flags
| Flag | Default | Description |
|------|---------|-------------|
| `REPEATER_HISTORY_INTERVAL_SECS` | `300` | Positive recording interval in seconds |
| `REPEATER_HISTORY_SLOTS` | `288`, or `0` on STM32/RP2040 | Interval slots per series; nominally 24 hours at five-minute intervals when enabled |
Set these using PlatformIO `build_flags`, for example `-D REPEATER_HISTORY_SLOTS=144`
for nominally 12 hours. `-D REPEATER_HISTORY_SLOTS=0` removes history members,
allocations, sampling, and handling of `0x04` entirely. STM32 and RP2040 builds default
to disabled history to conserve RAM; they can explicitly opt in with a smaller slot count.
There are no history CLI settings.
For both nRF52 and ESP32, sample storage is `5 * slots * 4` bytes (one float per
interval), or 5,760 bytes at the defaults. Comparing enabled and disabled builds shows
168 additional bytes in the enclosing mesh object on both platforms (including padding),
for a total of 5,928 bytes plus allocator overhead for five arrays. Unsupported temperature still reserves
its series storage. Query results use temporary stack space, not retained history RAM.
## Custom sensor sketch compatibility
The old `examples/simple_sensor/TimeSeriesData.h` include forwards to the shared helper.
Deprecated `RTCClock*` overloads remain available for existing custom sketches. They
ignore the RTC and use a shared, wrap-safe `millis()` accumulator; callers should migrate
to explicit monotonic seconds. Call the legacy API regularly enough to observe each
`millis()` wrap (less than about 49 days between calls), and use one clock API consistently
for each series. The shared legacy clock is linked only when these overloads are used.
The integer literal `0` is ambiguous between the seconds and pointer overloads. Use a
`uint32_t` variable (or `uint32_t(0)`) for uptime zero, and `nullptr` for a legacy null
clock argument.