tim/bmspy
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Simplify wording in the documentation

Browse Source 
Put each condition before its statement. Split long sentences. Use one term for each concept. Replace the description of possible checklist changes with a statement of the present behavior.
This commit is contained in:
tim
2026-10-10 10:12:35 +02:00
parent 82def5737f
commit ef7a6b5f92
3 changed files with 25 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ecoflow-river2-fields.md
+3 -3
View File
@@ -98,10 +98,10 @@ Empty or truncated reports do not count. Inverter (INV) and solar-controller
(MPPT) reports are optional and do not delay completion.
Raw packet keys include the source module: `ef_pkt_<src>_<cmdset>_<cmdid>`.
This keeps reports from different modules separate, even when they share a
command number. Watch mode also shows optional reports and unclassified packets.
If different modules share a command number, this still keeps their reports
separate. Watch mode also shows optional reports and unclassified packets.
Live R601 checks cover idle, charging, and discharging operation. Automated tests
use synthetic packets. These results do not validate River 3 operation.
use synthetic packets. These results apply to River 2.
See the [README](../README.md#ecoflow-bluetooth-le-devices) for setup and commands.
docs/ecoflow-river3-fields.md
+15 -23
View File
@@ -36,7 +36,8 @@ Diagnostic collection combines each field's latest value across reports, not one
simultaneous measurement. Zero and explicit unavailable values count as received.
Malformed messages and required fields with an unexpected encoding do not count.
Missing fields do not erase earlier measurements. The normal snapshot omits
unusable values even when the diagnostic checklist counts their receipt.
unusable values. If the diagnostic checklist counts the receipt of such a value,
the snapshot still omits it.
## Reported fields available to clients
@@ -51,8 +52,8 @@ InfluxDB and Prometheus export them alongside the normal measurements.
Prometheus adds fields that first arrive after the exporter starts.
Numbers and boolean values use `BMSScalarField.raw_value`.
Enum values are named numeric codes. They retain the code in `raw_value` and the
name in `value`, when the schema defines a name.
Enum values are named numeric codes. They retain the code in `raw_value`.
If the schema defines a name, they retain the name in `value`.
Only fields with existing unit annotations carry units.
Do not assume that an untranslated code or an unannotated number is a physical measurement.
@@ -131,7 +132,7 @@ still establish that a field arrived.
| 254 | `bms_dsg_rem_time` | Battery-management estimate of remaining discharge time, minutes. |
| 255 | `bms_chg_rem_time` | Battery-management estimate of remaining charge time, minutes. |
| 258 | `bms_min_cell_temp` | Minimum battery-cell temperature, degrees Celsius. |
| 259 | `bms_max_cell_temp` | Maximum battery-cell temperature, degrees Celsius. This supplies the normal snapshot temperature when present. |
| 259 | `bms_max_cell_temp` | Maximum battery-cell temperature, degrees Celsius. If present, this supplies the normal snapshot temperature. |
| 260 | `bms_min_mos_temp` | Minimum temperature at battery switching transistors, degrees Celsius. This is not a cell temperature. |
| 261 | `bms_max_mos_temp` | Maximum temperature at battery switching transistors, degrees Celsius. |
| 262 | `cms_batt_soc` | Device-level charge estimate, %. This supplies the normal snapshot charge ratio. |
@@ -145,8 +146,8 @@ still establish that a field arrived.
| 361 | `pow_get_pv` | Solar/DC input power, W. |
| 368 | `pow_get_ac_out` | AC output power, W. |
Individual channel power can be signed even when aggregate output power is
positive. Do not apply one sign convention to every power field. The current
If aggregate output power is positive, individual channel power can still be
signed. Do not apply one sign convention to every power field. The current
snapshot uses battery power, not an untranslated state code, to select direction.
The two time estimates can both be present while only one direction is active.
@@ -155,7 +156,7 @@ Their presence does not mean simultaneous charging and discharging. A value of
## Current configuration checklist: 22 fields
These values describe settings, limits, and connection state. A configured power
These values describe configuration, limits, and connection state. A configured power
limit is not a measurement of current power. A charger flag alone does not prove
that the battery is receiving power.
@@ -315,22 +316,13 @@ exit before the third report arrives. If the third report arrives before the
next completion check, its fields still appear in the accumulated final view.
There is no separate, shorter wait period assigned to the second report.
Collection checks progress every half second. It stops when the required
information is present, rather than when a selected report count or idle period
is reached. The watch output does not timestamp each packet, so it cannot
Collection checks progress every half second. If the required
information is present, it stops. It does not stop at a selected report count or
idle period. The watch output does not timestamp each packet, so it cannot
establish the exact interval between these reports.
Adding fields 30, 140, 213, 215, and 232 to a required status group would increase
the checklist from 53 to 58 fields. With the observed report layout, collection
would then wait for the third report. It would finish on receipt rather than
wait until the full timeout. The third report can still take additional time to
arrive. No fixed arrival time is established by this capture.
Requiring those five fields would not guarantee receipt of the other 15 fields
on firmware that splits the reports differently. Requiring all 20 would need a
broader, firmware-aware policy, especially for reserved and connector fields.
Neither change is implemented by this reference. The existing 53-field checklist
and verbose missing-field output remain unchanged.
The checklist requires 53 fields, and the first two reports supply all of them.
With this report layout, use `--watch` to receive the third report.
## Information that remains unresolved
@@ -339,7 +331,7 @@ are 17 such messages with seven distinct payloads. Their structure and meaning
remain unverified. They must not be assigned field meanings from the protobuf
schema merely because some bytes resemble protobuf tags.
This capture contains no confirmed `0x02/0xFE/0x16` runtime report. It therefore
This capture contains no known `0x02/0xFE/0x16` runtime report. It therefore
does not establish runtime voltage/current fields from that route. The schema
also contains many fields that this device did not report during the capture.
@@ -369,7 +361,7 @@ and raw bytes, with an error rather than a misleading interpreted value.
Unknown future field numbers remain numeric/raw. The eight-byte `0x35/0x35/0x20`
message is still unclassified. Full schema coverage does not establish the
meaning of that separate message or confirm runtime message routing.
meaning of that separate message or runtime message routing.
The descriptor source is upstream commit
`511e04702c83ddcc90cdcd575a1bbeffe2f061ad`. Only protocol declarations are retained,