126 lines
7.9 KiB
Markdown
126 lines
7.9 KiB
Markdown
# 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](docs/exec-plans/active/001-implementation-roadmap.md).
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```mermaid
|
||
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`](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`](AGENTS.md) | Entry point for coding agents and contributors — pointers and non-negotiable rules |
|
||
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | System structure, boundaries, interfaces, invariants — also defines document precedence (§1) |
|
||
| [`docs/product/software-specification.md`](docs/product/software-specification.md) | Functional requirements — what the gateway shall do |
|
||
| [`docs/product/codex-implementation-specification.md`](docs/product/codex-implementation-specification.md) | Implementation process: phases, task sizing, testing strategy, completion criteria |
|
||
| [`docs/configuration/configuration-reference.md`](docs/configuration/configuration-reference.md) | Configuration model, fields, defaults, validation rules |
|
||
| [`docs/protocol/`](docs/protocol) | AquaCom protocol knowledge: evidence, operation registry, gap registry, test vectors |
|
||
| [`docs/exec-plans/active/001-implementation-roadmap.md`](docs/exec-plans/active/001-implementation-roadmap.md) | Implementation roadmap (ExecPlan 001): phases 0–14, gates, decisions |
|
||
| [`missing_docs.md`](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](docs/protocol/protocol-gaps.md) — never guessed.
|
||
|
||
| Document | Content |
|
||
|---|---|
|
||
| [`docs/protocol/AquaCom_RTU_1_6_eng.pdf`](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`](docs/protocol/known-operations.md) | Registry of implementable operations, each with evidence and scope status |
|
||
| [`docs/protocol/protocol-gaps.md`](docs/protocol/protocol-gaps.md) | Open protocol questions with working hypotheses and workarounds |
|
||
| [`docs/protocol/test-vectors.md`](docs/protocol/test-vectors.md) | Checksum-verified test vectors for the codec (35 source vectors recomputed and confirmed) |
|
||
|
||
## Repository layout
|
||
|
||
```text
|
||
.
|
||
├── 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
|
||
|
||
- [x] Complete, consistent specification and architecture documentation
|
||
- [x] Protocol evidence acquired and catalogued; 35 checksum vectors verified by recomputation
|
||
- [x] 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](docs/exec-plans/active/001-implementation-roadmap.md)
|
||
|
||
## Getting started
|
||
|
||
**Reading the project** (suggested order): this file → [`ARCHITECTURE.md`](ARCHITECTURE.md) → [`docs/product/software-specification.md`](docs/product/software-specification.md) → the [roadmap](docs/exec-plans/active/001-implementation-roadmap.md).
|
||
|
||
**Contributing / implementing**: read [`AGENTS.md`](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. |