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.
