feat: updates to 0.8.0 - initial write functions
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
Ground-up Python replacement for **Blastware**, Instantel's Windows-only software for
|
||||
managing MiniMate Plus seismographs. Connects over direct RS-232 or cellular modem
|
||||
(Sierra Wireless RV50 / RV55). Current version: **v0.7.0**.
|
||||
(Sierra Wireless RV50 / RV55). Current version: **v0.8.0**.
|
||||
|
||||
---
|
||||
|
||||
@@ -25,9 +25,9 @@ CHANGELOG.md ← version history
|
||||
|
||||
---
|
||||
|
||||
## Current implementation state (v0.7.0)
|
||||
## Current implementation state (v0.8.0)
|
||||
|
||||
Full read pipeline working end-to-end over TCP/cellular:
|
||||
Full read pipeline + write pipeline working end-to-end over TCP/cellular:
|
||||
|
||||
| Step | SUB | Status |
|
||||
|---|---|---|
|
||||
@@ -39,12 +39,14 @@ Full read pipeline working end-to-end over TCP/cellular:
|
||||
| Event header / first key | 1E | ✅ |
|
||||
| Waveform header | 0A | ✅ |
|
||||
| Waveform record (peaks, timestamp, project) | 0C | ✅ |
|
||||
| **Bulk waveform stream (event-time metadata)** | **5A** | ✅ **new v0.6.0** |
|
||||
| **Bulk waveform stream (event-time metadata)** | **5A** | ✅ new v0.6.0 |
|
||||
| Event advance / next key | 1F | ✅ |
|
||||
| Write commands (push config to device) | 68–83 | ❌ not yet implemented |
|
||||
| **Write commands (push config to device)** | **68–83** | ✅ **new v0.8.0** |
|
||||
|
||||
`get_events()` sequence per event: `1E → 0A → 0C → 5A → 1F`
|
||||
|
||||
`push_config_raw()` write sequence: `68→73 | 71×3→72 | 82→83 | 69→74→72`
|
||||
|
||||
---
|
||||
|
||||
## Protocol fundamentals
|
||||
@@ -432,8 +434,144 @@ Server retries once on `ProtocolError` for TCP connections (handles cold-boot ti
|
||||
|
||||
---
|
||||
|
||||
## Write commands (SUBs 68–83) — confirmed 2026-04-07
|
||||
|
||||
All confirmed from 3-11-26 BW TX capture (`raw_bw_20260311_170151.bin`, frames 102–112).
|
||||
|
||||
### Write frame format — CRITICAL: minimal DLE stuffing
|
||||
|
||||
Write frames do NOT use the same DLE stuffing as read frames. **Only the BW_CMD byte
|
||||
(0x10 at payload position [0]) is doubled on the wire. All other bytes — flags, sub,
|
||||
offset, params, data, and checksum — are written RAW without stuffing.**
|
||||
|
||||
Confirmed from all 11 write frames in the 3-11-26/170151 BW capture. ✅ 2026-04-07
|
||||
|
||||
Do NOT use `dle_stuff()` or `build_bw_frame()` for write commands. Use `build_bw_write_frame()`.
|
||||
|
||||
```
|
||||
Actual wire layout:
|
||||
[41] ACK
|
||||
[02] STX
|
||||
[10 10] BW_CMD doubled (ONLY DLE stuffing applied)
|
||||
[00] flags
|
||||
[sub] write command byte (0x68–0x83)
|
||||
[00] always zero
|
||||
[hi][lo] offset uint16 BE — RAW (not stuffed even if hi=0x10)
|
||||
[params] 10 bytes — RAW
|
||||
[data] variable-length write payload — RAW (0x10 bytes not stuffed)
|
||||
[chk] checksum — RAW (not stuffed even if 0x10)
|
||||
[03] ETX
|
||||
|
||||
Total wire length = 2 (ACK+STX) + 2 (doubled BW_CMD) + 15 (raw header) + len(data) + 1 (chk) + 1 (ETX)
|
||||
= 21 + len(data)
|
||||
```
|
||||
|
||||
De-stuffed payload (logical; used for checksum computation only):
|
||||
```
|
||||
[0] BW_CMD 0x10
|
||||
[1] flags 0x00
|
||||
[2] SUB write command byte (0x68–0x83)
|
||||
[3] 0x00 always zero
|
||||
[4] offset_hi
|
||||
[5] offset_lo
|
||||
[6:16] params 10-byte field (see per-SUB notes below)
|
||||
[16:] data write payload (variable length; absent for confirm frames)
|
||||
[-1] chk large-frame DLE-aware checksum (see below)
|
||||
```
|
||||
|
||||
Write SUBs = Read SUB + 0x60. Response SUB follows the standard 0xFF − Request SUB rule.
|
||||
|
||||
### Write frame checksum
|
||||
|
||||
All write frames (data frames AND confirm frames) use the **large-frame DLE-aware checksum**:
|
||||
|
||||
```python
|
||||
chk = (sum(b for b in payload[2:] if b != 0x10) + 0x10) & 0xFF
|
||||
```
|
||||
|
||||
This is identical to the SUB 5A DLE-aware checksum. Confirmed against all 11 write frames in
|
||||
the 3-11-26/170151 capture. ✅ 2026-04-07
|
||||
|
||||
Note: confirm frames contain no embedded 0x10 bytes, so both the standard SUM8 and the
|
||||
DLE-aware formula produce the same result for them — but `build_bw_write_frame` always uses
|
||||
the DLE-aware formula for consistency.
|
||||
|
||||
### Write ack responses
|
||||
|
||||
All device acks for write commands are **17-byte zero-data S3 frames**:
|
||||
|
||||
```
|
||||
[DLE=0x10][STX=0x02][stuffed(header + chk)][bare ETX=0x03]
|
||||
```
|
||||
|
||||
The data section carries zeros; RSP_SUB = 0xFF − write_request_SUB.
|
||||
|
||||
### Write SUB constants and sequences
|
||||
|
||||
| Request SUB | Function | Offset | Response SUB |
|
||||
|---|---|---|---|
|
||||
| 0x68 | Event index write | `data[1] + 2` | 0x97 |
|
||||
| 0x73 | Confirm B (follows 68) | 0 | 0x8C |
|
||||
| 0x71 | Compliance write (×3 chunks) | see below | 0x8E |
|
||||
| 0x72 | Confirm A (follows 71×3, 69) | 0 | 0x8D |
|
||||
| 0x82 | Trigger config write | `data[1] + 2` | 0x7D |
|
||||
| 0x83 | Trigger confirm (follows 82) | 0 | 0x7C |
|
||||
| 0x69 | Waveform data write | `data[1] + 2` | 0x96 |
|
||||
| 0x74 | Confirm C (follows 69) | 0 | 0x8B |
|
||||
|
||||
**Offset formula for single-chunk writes (0x68, 0x69, 0x82):** `offset = data[1] + 2`
|
||||
|
||||
The write payload always begins with a 2-byte header `[0x00][length]`, where `data[1]` is
|
||||
an embedded length field. The offset encodes this inner length + 2 (accounting for the
|
||||
header bytes). Confirmed from all three single-chunk write frames in the 3-11-26 capture:
|
||||
|
||||
| SUB | data[0:4] (hex) | data[1] | offset | total data len |
|
||||
|---|---|---|---|---|
|
||||
| 0x68 | `00 58 09 00` | 0x58=88 | 0x5A=90 | 91 |
|
||||
| 0x82 | `00 1A D5 00` | 0x1A=26 | 0x1C=28 | 29 |
|
||||
| 0x69 | `00 C8 08 00` | 0xC8=200 | 0xCA=202 | 204 |
|
||||
|
||||
Full sequence: `68→73 | 71×3→72 | 82→83 | 69→74→72`
|
||||
|
||||
### SUB 71 — compliance write chunk parameters
|
||||
|
||||
The full compliance config payload (~2128 bytes) is split into exactly 3 chunks.
|
||||
Confirmed from 3-11-26 BW TX capture frames 104–108:
|
||||
|
||||
| Chunk | Size | `offset` | `params` (10 bytes hex) |
|
||||
|---|---|---|---|
|
||||
| 1 (first) | 1027 bytes | 0x1004 | `00 00 00 00 00 00 00 00 00 00` |
|
||||
| 2 (middle) | 1055 bytes | 0x1004 | `00 00 00 10 04 00 00 00 00 00` |
|
||||
| 3 (last) | remainder | 0x002C | `00 00 08 00 00 00 00 00 00 00` |
|
||||
|
||||
Total: 1027 + 1055 + N = 2082 + N bytes (N ≈ 46 for a standard 2128-byte config).
|
||||
|
||||
After all 3 chunks are acked (SUB 0x8E each), send SUB 72 confirm → device acks 0x8D.
|
||||
|
||||
### `build_bw_write_frame()` — framing.py
|
||||
|
||||
```python
|
||||
build_bw_write_frame(sub, data, *, offset=0, params=bytes(10)) -> bytes
|
||||
```
|
||||
|
||||
Use for all write commands (SUBs 68–83) including confirm frames (data=b"").
|
||||
**Do NOT use `build_bw_frame` for write commands** — it uses standard SUM8, not the
|
||||
large-frame DLE-aware checksum required for writes.
|
||||
|
||||
### `push_config_raw()` — client.py
|
||||
|
||||
```python
|
||||
client.push_config_raw(event_index_data, compliance_data, trigger_data, waveform_data)
|
||||
```
|
||||
|
||||
Orchestrates the full write sequence in the confirmed order. All payloads are raw bytes
|
||||
(no encoding performed at this level). A higher-level encoder that builds payloads from
|
||||
a `ComplianceConfig` object is a future task.
|
||||
|
||||
---
|
||||
|
||||
## What's next
|
||||
|
||||
- Write commands (SUBs 68–83) — push compliance config, channel config, trigger settings to device
|
||||
- Compliance config encoder — build raw write payloads from a `ComplianceConfig` object
|
||||
- ACH inbound server — accept call-home connections from field units
|
||||
- Modem manager — push RV50/RV55 configs via Sierra Wireless API
|
||||
|
||||
Reference in New Issue
Block a user