AquaCom Integration Gateway

The AquaCom Integration Gateway connects AquaCom-compatible field equipment (legacy MacTec-standard RTUs used in pump stations and similar water-utility installations) to modern OT/IT systems.

The gateway:

communicates with AquaCom stations over TCP or serial transports;
acquires current (live) process values;
retrieves historical process values recorded in the field equipment;
normalizes everything into a protocol-independent canonical data model;
exposes current values through OPC UA Data Access;
exposes historical values through OPC UA Historical Access;
delivers history to one or more independent, configurable storage destinations;
recovers historical data automatically after communication interruptions (watermark-based backfill with store-and-forward buffering);
provides operational and protocol diagnostics.

It is deliberately an integration gateway, not merely an OPC UA server: the long-term asset is the normalized information layer and the historical recovery mechanism, so OPC UA, the storage technology, and the AquaCom equipment can each evolve or be replaced independently.

Status: specification & planning phase. This repository currently contains the complete documentation set, the verified protocol evidence, and the implementation roadmap. Runtime code does not exist yet — implementation begins with Phase 0 of the implementation roadmap.

Architecture

graph TB
    RTU[AquaCom stations / RTUs] --> TR[AquaCom Transport]
    TR --> PE[AquaCom Protocol Engine]
    PE --> SM[Station / Session Manager]
    SM --> CM[Canonical data model]

    CM --> CS[Current-State Service]
    CM --> HAM[Historical Acquisition Manager]
    HAM --> HP[Historical pipeline: validate → deduplicate → durable spool]
    HP --> REPO[(History repository)]
    HP --> SINKS[(Storage sinks A…N)]

    CS --> SRV[OPC UA server: Data Access + Historical Access + diagnostics]
    REPO --> SRV
    SRV --> CLIENTS[SCADA / historian / analytics clients]

Core architectural rules (normative in ARCHITECTURE.md):

AquaCom protocol parsing lives only in the AquaCom modules; no OPC UA, history or storage code touches a telegram.
Data crosses subsystem boundaries only through the canonical model.
A historical sample describes the process at its SourceTimestamp — it never becomes a current value merely because it was recently received.
OPC UA Historical Access queries the gateway's history repository; a client HistoryRead never triggers AquaCom traffic.
StationId, PointId and OPC UA NodeIds remain stable across restart, upgrade, renaming and transport-address changes.
Live acquisition takes priority over bulk historical backfill.

Documentation

Document	Role
`AGENTS.md`	Entry point for coding agents and contributors — pointers and non-negotiable rules
`ARCHITECTURE.md`	System structure, boundaries, interfaces, invariants — also defines document precedence (§1)
`docs/product/software-specification.md`	Functional requirements — what the gateway shall do
`docs/product/codex-implementation-specification.md`	Implementation process: phases, task sizing, testing strategy, completion criteria
`docs/configuration/configuration-reference.md`	Configuration model, fields, defaults, validation rules
`docs/protocol/`	AquaCom protocol knowledge: evidence, operation registry, gap registry, test vectors
`docs/exec-plans/active/001-implementation-roadmap.md`	Implementation roadmap (ExecPlan 001): phases 0–14, gates, decisions
`missing_docs.md`	Planned documents that do not exist yet

When documents overlap, the precedence defined in ARCHITECTURE.md §1 applies: the software specification for requirements, ARCHITECTURE.md for structure, the implementation specification for process, the configuration reference for configuration semantics. No other document overrides them.

Protocol evidence

The AquaCom implementation is strictly evidence-based: telegram framing, checksums, operations, addressing, timestamp encoding and historical-data semantics may only be implemented from verified evidence (the authoritative vendor protocol description, validated traffic captures, or known-good implementations). Unknown protocol behavior is recorded in the gap registry — never guessed.

Document	Content
`docs/protocol/AquaCom_RTU_1_6_eng.pdf`	Authoritative source: Technical description – AquaCom – RTU level, Rev 1.6, ITT Flygt AB, July 2004
`docs/protocol/known-operations.md`	Registry of implementable operations, each with evidence and scope status
`docs/protocol/protocol-gaps.md`	Open protocol questions with working hypotheses and workarounds
`docs/protocol/test-vectors.md`	Checksum-verified test vectors for the codec (35 source vectors recomputed and confirmed)

Repository layout

.
├── AGENTS.md                     # entry point for agents / contributors
├── ARCHITECTURE.md               # system structure, boundaries, invariants
├── README.md                     # this file
├── missing_docs.md               # planned documents not yet created
└── docs/
    ├── architecture/             # detailed subsystem architecture (planned)
    ├── configuration/
    │   └── configuration-reference.md
    ├── exec-plans/
    │   └── active/
    │       └── 001-implementation-roadmap.md
    ├── product/
    │   ├── software-specification.md
    │   └── codex-implementation-specification.md
    └── protocol/
        ├── AquaCom_RTU_1_6_eng.pdf          # authoritative protocol source
        ├── AquaCom_RTU_1_6_eng_markdown/    # markdown conversion (lossy — see gap registry)
        ├── known-operations.md
        ├── protocol-gaps.md
        └── test-vectors.md

Current status and next steps

Complete, consistent specification and architecture documentation
Protocol evidence acquired and catalogued; 35 checksum vectors verified by recomputation
Implementation roadmap (ExecPlan 001) with phase gates and decision log
Technology selection (decision D-001): implementation language + OPC UA server stack — server-side Historical Access support is the make-or-break capability to verify per candidate
Phase 0: repository skeleton, CI, configuration schema
Phases 1–14 per the roadmap

Getting started

Reading the project (suggested order): this file → ARCHITECTURE.md → docs/product/software-specification.md → the roadmap.

Contributing / implementing: read AGENTS.md first — it defines the evidence rules, architectural boundaries, testing requirements and the ExecPlan process that all substantial work must follow.

Third-party material

The AquaCom protocol description under docs/protocol/ is a third-party copyrighted document (© 2004 ITT Flygt AB). It is kept in this repository for internal engineering reference; do not redistribute it outside your organization without the copyright holder's permission.

License

Not yet chosen. Licensing will be decided before the first public release of implementation code.

7.9 KiB Raw Permalink Blame History Unescape Escape