163 lines
13 KiB
Markdown
163 lines
13 KiB
Markdown
# AquaCom protocol gap registry
|
||
|
||
**Source:** *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 — present in this folder as `AquaCom_RTU_1_6_eng.pdf` (markdown conversion: `AquaCom_RTU_1_6_eng_markdown/AquaCom_RTU_1_6_eng.md`). The PDF is authoritative wherever the conversion is ambiguous.
|
||
|
||
**Policy.** AquaCom protocol behavior may only be implemented from verified evidence (`AGENTS.md`; implementation specification §3.1). Unresolved protocol questions are recorded here instead of guessed (implementation specification §62, case C). An entry is closed only when the missing evidence exists; closing requires citing the evidence, adding a resolution note, and changing the status. Entries are never deleted.
|
||
|
||
**Entry format** (implementation specification §17): Gap ID, Description, Affected operation, Evidence available, Evidence missing, Impact, Implementation status.
|
||
|
||
**Status values:**
|
||
|
||
- `OPEN` — evidence missing; implement only what is documented, never the undocumented part.
|
||
- `VERIFY` — evidence exists in the PDF; the markdown conversion is unreliable at the cited places; check the PDF before implementing.
|
||
- `CLOSED` — resolved; cite evidence and date in a resolution note.
|
||
|
||
---
|
||
|
||
## AQ-GAP-001 — Fidelity of the markdown conversion
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-001 |
|
||
| Description | The PDF→markdown conversion is lossy at several places. Confirmed instances: (a) §3.4.2.2 MCC DATA type table is mangled — the type rows are merged ("A = D = Integer (0-32767) … Analogue (0-200)"); (b) §3.4.10.1 WGS status-answer table merges the `mp1–mp128` byte-range cell into the description text (recoverable reading: 1–12 bytes each, measuring points 1–128); (c) §2.2.3.2 caller-ID field table formatting is broken; (d) §3.4.2.3.3 controller-type example prints `101 001` while the surrounding text refers to `(010)` (the parallel sections print `101 010` and `101 100` consistently); (e) the §3.7 detailed example is truncated mid-telegram ("…_0_1_1" followed by the document footer), so the answer's checksum is never reached; (f) WGS request examples print `0!` for the `mash`/`dir` fields — checksum verification proves the wire form is `0 !` (two space-separated fields), so this instance is resolved, but the PDF rendering should be confirmed for the record; (g) §3.4.12.1 states the WGH block `YY` is 2 bytes, but checksum-verified examples transmit single-digit years (e.g. `1 4 30 23 35`) — all block date fields shall be accepted as 1–2 digits. |
|
||
| Affected operation | all telegram parsing |
|
||
| Evidence available | authoritative PDF in this folder |
|
||
| Evidence missing | none — each affected table must be checked against the PDF before implementation |
|
||
| Impact | wrong field layouts if implemented from the markdown conversion alone |
|
||
| Status | `VERIFY` |
|
||
|
||
---
|
||
|
||
## AQ-GAP-002 — WGS status answer: `alp` semantics and measuring-point/alarm boundary
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-002 |
|
||
| Description | `Nal` ("number of alarms following last measuring point") is unambiguous and consistent with all examples: alarm codes are appended after the measuring points, `Nal` of them. `alp` ("position where the first alarm is to be found") does not define its reference frame in the document. Arithmetic across **all four** printed examples is consistent with `alp` = the 1-based position, within the measuring-point sequence, of the first alarm, i.e. `measuring-point count = alp − 1`: §2.2.3.1 (alp=48, Nal=3), §3.4.10.2 (alp=22, Nal=1), §3.4.10.3 (alp=64, Nal=1), §3.6.4 (alp=11, Nal=1, 10 measuring points explicit). The earlier note that §2.2.3.1 "does not reconcile" was an analysis error (a mis-split field list), now retracted. What remains missing is an explicit definition, and a capture from a real station (the four examples agree but are all from the same vendor document). |
|
||
| Affected operation | WGS status answer decoding |
|
||
| Evidence available | §3.4.10.1 field definitions; arithmetic of examples §2.2.3.1, §3.4.10.2–3, §3.6.4 |
|
||
| Evidence missing | an explicit definition, or a validated capture from a station whose measuring-point count is independently known |
|
||
| Impact | the boundary between measuring points and trailing alarm codes; a misparse shifts every subsequent value |
|
||
| Status | `OPEN` — hypothesis strengthened but still vendor-document-internal; do not treat `alp` as confirmed |
|
||
|
||
**Working hypothesis (not confirmed — do not rely on it):** `alp` is the 1-based position, within the measuring-point sequence, of the first alarm; measuring points number `alp − 1`. An initial implementation may split measuring points from alarms using `Nal` alone (documented unambiguously), cross-check against `alp − 1` diagnostically, and shall not reject telegrams on an `alp` mismatch until this gap is closed.
|
||
|
||
---
|
||
|
||
## AQ-GAP-003 — WGH: number of values per block and trend-point membership
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-003 |
|
||
| Description | Historical trend blocks contain `v1…v32`; "the actual numbers is depending of the type of RTU and version". The count is not signaled in the telegram. Examples: §3.4.12.2 has 7 values per block; §3.7 has 6. On Forth RTUs the station CFG contains a dedicated historical-trend section ("; ##3 / Number of points for Historical trend", with per-point wagon mapping) which presumably governs both membership and count; on Basic RTUs the MAS `htr` flag marks trend participation instead (§3.5.3.2). The document never explicitly states that the decoder must derive the per-block value count from station configuration. |
|
||
| Affected operation | WGH historical trend data decoding |
|
||
| Evidence available | §3.4.12.1 block format; examples §3.4.12.2 and §3.7; CFG sections §3.4.12.3 and §3.5.3.2 |
|
||
| Evidence missing | an explicit statement, or a validated capture from a station whose CFG is known |
|
||
| Impact | block splitting is ambiguous: values are numeric and cannot be distinguished from the following block's date fields by form alone |
|
||
| Status | `OPEN` |
|
||
|
||
**Working hypothesis (not confirmed):** the expected value count comes from the station's point configuration (CFG historical-trend section); the decoder validates each block's structure against it. Values are wagon-mapped and scaled per point (`Scaled = Raw*(Max−Min)/Max_input + Min`, §3.4.12.3).
|
||
|
||
---
|
||
|
||
## AQ-GAP-004 — Character encoding of text values
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-004 |
|
||
| Description | Telegrams are "an ASCII-string with support of IBM extended codes. E.g. codes 01H to FFH is supported" — the code page for IBM extended codes (e.g. Å/Ä/Ö in Swedish station names) is not defined. Some RTUs support UTF-8 in the MCC data part, capability-dependent (ATF controller-type position 3). The checksum is byte-based and unaffected. |
|
||
| Affected operation | MCC T-type values (station names, telephone numbers), any text-bearing points |
|
||
| Evidence available | §2.3.1; §3.4.2.3.3 Note 4 |
|
||
| Evidence missing | a code-page definition, or a capture containing non-ASCII text |
|
||
| Impact | garbled text values; incorrect string comparisons |
|
||
| Status | `OPEN` (low priority until text points are used) |
|
||
|
||
---
|
||
|
||
## AQ-GAP-005 — Example checksum integrity in the source document
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-005 |
|
||
| Description | **35 single-line examples** from the document were recomputed against the §2.4 algorithm and verify exactly (see `test-vectors.md` §1), confirming the algorithm itself, including the Wait-exclusion rule (§3.6.4 pair: both forms sum to 2925). However: (a) the long multi-line examples (WGS answers 7679/3633/6967/6968, WGH answers 6922/6479/4220, WGD answers 4984/5632, MCC 24268/28910, SLT 14331/15425/15061) **cannot be byte-exactly recomputed from the markdown conversion** — blockquote `>` prefixes, `\#` escapes and line-wrap artifacts (e.g. `1\n4 30` splitting a block, `- 16384` splitting a value) survive in the conversion and change byte sums; manual cleanup attempts give near-miss values (e.g. SLT 14331 → 14330/14295 depending on artifact handling), proving the artifacts, not the algorithm, are the problem; (b) example narratives contain destination mismatches (§2.2.3.1 says plant number 89 but the telegram uses dest 86; §3.4.10.2 gives a fixed-line dest as "plant number 901" although fixed-line dest should be the Node ID). |
|
||
| Affected operation | approved test vectors only — the checksum algorithm is confirmed for all short vectors |
|
||
| Evidence available | 35 verified recomputations in `test-vectors.md`; authoritative PDF |
|
||
| Evidence missing | PDF text extraction (or manual transcription) of the long examples free of conversion artifacts |
|
||
| Impact | the long examples cannot be approved fixtures until transcribed from the PDF; they are the only candidates exercising 16-bit wraparound (sums > 65535), so synthetic vectors cover that branch in the meantime |
|
||
| Status | `OPEN` |
|
||
|
||
---
|
||
|
||
## AQ-GAP-006 — MAT fetch request checksum
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-006 |
|
||
| Description | The MAT fetch **request** `9 MAT 0 1 # 557` (§3.4.7.2) recomputes to **540**. 557 is exactly the checksum of the structurally identical SLT fetch request `9 SLT 0 1` (§3.4.9.2, verified), indicating a copy-paste error in the source document. The MAT fetch **answer** `7 9001 # 353` verifies exactly (353), so the answer side is sound. |
|
||
| Affected operation | MAT fetch request vector |
|
||
| Evidence available | §3.4.7.2 examples; recomputation (request: 540; answer: 353 verified) |
|
||
| Evidence missing | PDF confirmation of which checksum the printed request should carry |
|
||
| Impact | minor — use 540 for the request vector once PDF-confirmed; the verified answer vector may be approved independently |
|
||
| Status | `OPEN` |
|
||
|
||
---
|
||
|
||
## AQ-GAP-007 — SCE payload semantics
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-007 |
|
||
| Description | "A SCE answer for a MCC telegram might contain the channel number the RTU rejected. Example: SCE 48 # 423." Whether and when the payload field is present is unspecified ("might"). |
|
||
| Affected operation | SCE (error in telegram) handling |
|
||
| Evidence available | §3.4.2.3 example (checksum verifies) |
|
||
| Evidence missing | a rule for payload presence |
|
||
| Impact | low — treat any payload as optional diagnostic data, never as parse-critical |
|
||
| Status | `OPEN` (low) |
|
||
|
||
---
|
||
|
||
## AQ-GAP-008 — Caller-ID telegram `ACT` field contents
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-008 |
|
||
| Description | §2.2.3.2 defines the dialled-line caller-ID telegram (`STX DEST ACT # CHK CR`) with `ACT` = "Type of message, 3 bytes", but lists no valid `ACT` values. The §2.2.3.3 example transmits the literal string `ACT`, and its checksum (369) is consistent with that literal — suggesting an unexpanded placeholder rather than real traffic. |
|
||
| Affected operation | dialled-line caller identification |
|
||
| Evidence available | §2.2.3.2–3 |
|
||
| Evidence missing | valid `ACT` values, or a capture of a real caller-ID telegram |
|
||
| Impact | low for fixed-line/TCP-first deployments (feature is dialled-only and capability-dependent) |
|
||
| Status | `OPEN` (low) |
|
||
|
||
---
|
||
|
||
## AQ-GAP-009 — WGD segment boundaries configurability
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-009 |
|
||
| Description | WGD answer segments are documented as "default 00-06 / 06-09 / 09-16 / 16-00". The word "default" implies configurability, but no mechanism is documented in this document. |
|
||
| Affected operation | WGD periodical data interpretation |
|
||
| Evidence available | §3.4.11.1 |
|
||
| Evidence missing | the configuration mechanism (possibly an AquaView/CFG setting outside this document) |
|
||
| Impact | low — use the documented defaults; record deviation diagnostically |
|
||
| Status | `OPEN` (low) |
|
||
|
||
---
|
||
|
||
## AQ-GAP-010 — Minor source-document inconsistencies in alarm telegrams
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| Gap ID | AQ-GAP-010 |
|
||
| Description | (a) The WCA field table gives the hour range as 0–24 (§3.4.1) while ALR gives 0–23 (§3.4.1.6); 24 is likely a source typo — validate as 0–23 unless the PDF shows otherwise. (b) The semantics of the WCA date/time fields when `set=0` (poll mode) are not stated; the examples always carry the CS's current time, but the document does not say what the RTU does with it when `set=0`. |
|
||
| Affected operation | WCA request encoding; alarm polling |
|
||
| Evidence available | §3.4.1, §2.2.3.3, §3.4.1.2–3 examples |
|
||
| Evidence missing | PDF confirmation; a statement of `set=0` time semantics |
|
||
| Impact | low — alarms are extension scope; do not implement clock setting or rely on `set=0` time semantics until resolved |
|
||
| Status | `OPEN` (low) |
|
||
|
||
---
|
||
|
||
## Closed gaps
|
||
|
||
None yet. When closing an entry: keep the original text, append a **Resolution** note citing the evidence and date, and set the status to `CLOSED`. |