aquacom-gateway-suite/docs/protocol/known-operations.md

# AquaCom known operations registry

**Source of all evidence:** *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 (`AquaCom_RTU_1_6_eng.pdf`; markdown conversion in this folder). Section references below are to that document.

**Purpose.** Registers every AquaCom operation the gateway may implement, with its evidence and implementation status. An operation enters this registry *before* implementation begins; adding an operation with status beyond `REGISTERED` requires its evidence to be complete and its gaps resolved or scoped. Open questions live in `protocol-gaps.md` — this registry never invents behavior not stated in the source.

**Status values:** `REGISTERED` (evidence located, not yet implemented) · `PARTIAL` (framework-level support only) · `IMPLEMENTED` (codec + tests + traceability) · `OUT-OF-SCOPE` (deliberately not implemented in the initial release; evidence retained for future phases).

**Framing note (applies to every operation):** CS→RTU telegrams are `SOH + SPACE + DEST + SPACE + TYPE + SPACE + DATA… + SPACE + '#' + SPACE + CHK + CR`; RTU→CS telegrams are `STX + SPACE + DATA… + SPACE + '#' + SPACE + CHK + CR` (§2.3.2). Checksum per §2.4; `Wait` (DC3) bytes are stripped before parsing and excluded from the checksum (§3.6.4).

---

## Session / control operations

### OPS-001 — Connection message (`OK`)

| Field | Content |
|---|---|
| Direction | RTU→CS (CS dialled) · CS→RTU (RTU dialled in alarm) |
| Purpose | Dialled-line connection answer; the answering side sends OK before conversation begins. The answering phase is "6×OK with 2.5s delay between each, aborted as soon as a telegram arrives"; some RTUs send 2×OK ≈4s apart instead (§2.2.3, §3.3.1). |
| Evidence | §2.2.3, §3.3.1, examples §3.4.1.2, §3.4.5.3, §3.4.7.2, §3.4.9.2, §3.4.10.3, §3.4.11.3, §3.4.12.2 |
| Gaps | — |
| Status | REGISTERED (dialled lines only; not applicable to fixed/TCP operation) |

### OPS-002 — Break (`BRK`)

| Field | Content |
|---|---|
| Direction | CS→RTU |
| Purpose | End communication. No answer is returned. Send 3× in a row before hanging up. Mandatory after a WGS containing a control command — some RTUs stay "remote controlled" until BRK (§3.4.13). |
| Evidence | §3.4.13 |
| Gaps | — |
| Status | REGISTERED (required for session teardown; harmless on fixed lines) |

### OPS-003 — Break with acknowledge (`EBR`)

| Field | Content |
|---|---|
| Direction | CS→RTU |
| Purpose | BRK variant expecting a `SCO` answer; retransmit up to 6 times on timeout or wrong answer. Not supported in Forth RTUs (§3.5.4, §3.2 summary table). |
| Evidence | §3.5.4 |
| Gaps | — |
| Status | REGISTERED (Basic RTUs only) |

### OPS-004 — Caller identification (dialled lines)

| Field | Content |
|---|---|
| Direction | RTU→CS |
| Purpose | Identifies the calling RTU (`STX DEST ACT # CHK CR`); capability-dependent (§2.2.3.2). |
| Evidence | §2.2.3.2–3 |
| Gaps | AQ-GAP-008 (ACT values unknown) |
| Status | REGISTERED — blocked by AQ-GAP-008 |

---

## Live-data operations

### OPS-005 — Status request (`WGS`)

| Field | Content |
|---|---|
| Direction | CS→RTU, answer RTU→CS |
| Purpose | Live-values polling. Answer: `ver, prod, Nal, alp, rem, r1–r4, mp1–mpN` (measuring points for the requested picture), followed by `Nal` alarm codes (§3.4.10). This is the protocol's primary live-acquisition operation. |
| Evidence | §3.4.10, examples §3.4.10.2–3, §2.2.3.1, §3.6.4; CFG picture/command sections §3.4.10.4–5 |
| Gaps | AQ-GAP-002 (alp semantics; hypothesis `mp count = alp−1` consistent with all four examples), AQ-GAP-005 (long-example checksums pending PDF transcription) |
| Status | REGISTERED (live acquisition is core scope; see `software-specification.md` §11) |

The `dir` field (F/B/N/M/!) is machine **control** — excluded from the initial release (`software-specification.md` §3.2); the decoder shall tolerate its syntax, and the gateway shall always transmit `!` (ignore).

### OPS-006 — Alarm request (`WCA`) and answers `ALR`/`ALN`/`ALO`

| Field | Content |
|---|---|
| Direction | CS→RTU (`WCA`, `ALO`), RTU→CS (`ALR`, `ALN`) |
| Purpose | Alarm polling/acknowledgement; `set=2` sets the RTU clock from the request's date/time (§3.4.1). Alarm retrieval is extension scope but the evidence now exists. |
| Evidence | §3.4.1, §2.2.3.3, §3.5.1.1 (Basic ALR variant) |
| Gaps | AQ-GAP-010 |
| Status | REGISTERED — alarm retrieval is OUT-OF-SCOPE for the initial release; clock setting (`set=2`) also OUT-OF-SCOPE (audit + confirmation architecture required first, cf. implementation specification §76) |

---

## Historical-data operations

### OPS-007 — Historical trend (`WGH`)

| Field | Content |
|---|---|
| Direction | CS→RTU, answer RTU→CS (data or `NDA`) |
| Purpose | 5-minute-block historical trend retrieval. Request carries the timestamp of the last stored block; the answer continues from there, up to max 6 hours / 4000 chars; `NDA` ends the stream. This is the backfill/watermark operation the Historical Acquisition Manager is built around (§3.4.12). |
| Evidence | §3.4.12 incl. full multi-answer example §3.4.12.2 and CFG scaling §3.4.12.3; wire-level example §3.7 |
| Gaps | AQ-GAP-003 (block value count), AQ-GAP-001(e/g) |
| Status | REGISTERED (core scope; requires `protocol-gaps.md` AQ-GAP-003 working hypothesis wired to station point configuration) |

Semantics confirmed by example: a day's final block is timestamped `00:00` of the *next* day (§3.4.12.2 comment); requests use the last received block's timestamp to resume — the exact pattern the gateway's synchronization watermark must reproduce.

### OPS-008 — Periodical report (`WGD`)

| Field | Content |
|---|---|
| Direction | CS→RTU, answer RTU→CS (data or `NDA`) |
| Purpose | Per-day segmented aggregates (default 00-06 / 06-09 / 09-16 / 16-00 + sum) per reporting point (§3.4.11). Maps to canonical `AcquisitionSource = AQUACOM_REPORT`. Request also sets the RTU clock (same caveat as WCA). |
| Evidence | §3.4.11 incl. CFG section and scaling formula |
| Gaps | AQ-GAP-009, AQ-GAP-010(b) |
| Status | REGISTERED (implemented after WGH; report points configured separately from trend points per §3.4.11.4) |

---

## Configuration / definition operations

### OPS-009 — Function channels (`MCC`, `MPA`, `MPB`, `MPC`, `MPD`, `MPL`)

| Field | Content |
|---|---|
| Direction | CS→RTU (set) and RTU→CS (fetch) |
| Purpose | Setpoint/config channel write & fetch. **Fetch limitation (Forth):** the RTU echoes only the *last sent* telegram — you must send what you want to receive; a cold-started RTU cannot be fetched from (§3.4.2–3, §3.4.3 "Important 2"). Types: `A`/`D` integer, `T` text (quoted, `_` = empty/space-as-underscore), `0–4` float decimals (§3.4.2.2; Basic variant §3.5.2). |
| Evidence | §3.4.2–3, §3.4.2.3 CFG/AquaView examples |
| Gaps | AQ-GAP-001(a), AQ-GAP-004 |
| Status | REGISTERED (used for station configuration; **writes to setpoints are control operations — OUT-OF-SCOPE initially**; read-back of a previously sent telegram is acceptable) |

### OPS-010 — Analogue channels (`MAS`)

| Field | Content |
|---|---|
| Direction | CS→RTU (set) and RTU→CS (fetch) |
| Purpose | Analogue input config (signal type, alarm levels, hysteresis, decimals; `htr` trend flag on Basic RTUs). Fetch requires a prior send, as with MCC (§3.4.4–5, §3.5.3). |
| Evidence | §3.4.4–5, §3.5.3, CFG examples |
| Gaps | AQ-GAP-003 (htr vs. Forth CFG trend section) |
| Status | REGISTERED (definitions source; writes OUT-OF-SCOPE initially, as OPS-009) |

### OPS-011 — Alarm code filter (`MAT`) and priorities (`SLT`)

| Field | Content |
|---|---|
| Direction | CS→RTU (set) and RTU→CS (fetch, capability-dependent per ATF controller-type digits) |
| Purpose | Alarm code remapping and A–Z priorities. The document itself states MAT "is not necessary to implement" (§3.4.6.3). |
| Evidence | §3.4.6–9 |
| Gaps | AQ-GAP-006 |
| Status | OUT-OF-SCOPE (alarm system extension; revisit when alarm retrieval is scheduled) |

---

## Answer telegrams (all operations)

### OPS-012 — Fixed answers `SCO` / `SCE` / `NDA` / `!!` (Wait)

| Field | Content |
|---|---|
| Direction | RTU→CS |
| Purpose | `SCO` = telegram OK; `SCE` = error in telegram (optional rejected-channel payload, AQ-GAP-007); `NDA` = requested data not available (normal WGH/WGD stream terminator — **not** an error); `!!` = single DC3 (13H) byte, may be embedded *inside* another telegram, must be stripped before parsing, excluded from checksum, and resets the CS receive timeout (§3.6). |
| Evidence | §3.6, §3.6.4 checksum-identical pair of examples (both verified: 2925), §3.7 |
| Gaps | AQ-GAP-007 (SCE payload) |
| Status | REGISTERED (the `!!` handling is a hard requirement for any long-answer operation: WGH, WGD, WGS, MCC fetch) |

---

## Implementation order (evidence-complete subset)

1. Framing + checksum + `!!` stripping (OPS-012 + framing note) — fully evidenced, unblocked.
2. OPS-005 `WGS` (live) — blocked only by AQ-GAP-002, which has a documented workaround (decode via `Nal`, cross-check `alp` diagnostically).
3. OPS-007 `WGH` (history) — blocked by AQ-GAP-003 working-hypothesis wiring (station configuration drives block layout).
4. OPS-008 `WGD` (reports) — after WGH; AQ-GAP-009 defaults.
5. Session ops OPS-001/002 as transports require (BRK for fixed-line WGS sessions).

This order matches the implementation phases (Phase 3 codec → Phase 6 live → Phase 10 historical) and honors live-over-history scheduling.