jobe/aquacom-gateway-suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fbec27ff8c7d034fb04cfc1bd77eace657819297
aquacom-gateway-suite/docs/product/software-specification.md
T
Jonas Bengtsson fbec27ff8c 🎉 Initial commit
2026-10-05 20:32:13 +02:00

3289 lines
47 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
\# Software Specification – AquaCom Integration Gateway
\*\*Document type:\*\* Software Requirements and Architecture Specification
\*\*Status:\*\* Draft
\*\*Version:\*\* 0.1
\*\*System name:\*\* AquaCom Integration Gateway
\*\*Primary interfaces:\*\* AquaCom, OPC UA
\*\*Implementation language:\*\* Not specified
\*\*Database/storage technology:\*\* Not specified
\---
\# 1. Purpose
The purpose of the AquaCom Integration Gateway is to provide a modern integration layer between legacy AquaCom-compatible field equipment and higher-level OT/IT systems.
The gateway shall communicate with AquaCom devices and provide:
\- current/live process values;
\- historical process values retrieved from AquaCom devices;
\- normalized timestamps and data quality;
\- OPC UA access to current values;
\- OPC UA Historical Access to historical values;
\- configurable storage of historical data in one or several independent storage systems;
\- controlled buffering and backfill following communication interruptions;
\- diagnostics concerning AquaCom communication, history synchronization, storage and OPC UA operation.
The architecture shall separate AquaCom-specific communication from OPC UA and historical storage so that each component can evolve independently.
The gateway shall not require an OPC UA client to understand AquaCom.
\---
\# 2. Design objectives
The system shall be designed around the following principles:
1\. \*\*Protocol isolation\*\*
  AquaCom telegram handling shall be isolated from OPC UA, persistence and application logic.
2\. \*\*Canonical data model\*\*
  AquaCom information shall be transformed into an internal protocol-independent representation before being exposed or stored.
3\. \*\*Separation of live and historical processing\*\*
  Historical samples retrieved from an RTU shall not be replayed as current values.
4\. \*\*Source timestamp preservation\*\*
  Timestamps originating from the field device shall be retained throughout the system.
5\. \*\*Storage independence\*\*
  Historical information shall not be coupled to a specific database technology.
6\. \*\*Multiple storage targets\*\*
  The gateway shall support simultaneous writing to zero, one or several configured historical destinations.
7\. \*\*OPC UA as an interface, not the internal data model\*\*
  OPC UA shall expose information from the gateway but shall not dictate the internal architecture.
8\. \*\*Recoverability\*\*
  Temporary failure of a communication channel, storage destination or OPC UA client shall not result in unnecessary loss of recoverable historical data.
9\. \*\*Deterministic and testable protocol implementation\*\*
  AquaCom encoding, decoding and state handling shall be independently testable.
10\. \*\*Secure-by-default operation\*\*
  OPC UA security and gateway administration shall use authenticated and protected communication by default.
\---
\# 3. Scope
\## 3.1 Included
The initial system scope includes:
\- AquaCom connection management;
\- AquaCom telegram encoding and decoding;
\- configuration of AquaCom stations;
\- acquisition of live/current values;
\- acquisition of available AquaCom historical information;
\- detection and retrieval of historical data after communication interruptions;
\- normalization of AquaCom values into a canonical model;
\- live-value cache;
\- historical-data processing;
\- duplicate detection;
\- local buffering;
\- one or multiple storage adapters;
\- OPC UA Server;
\- OPC UA Data Access;
\- OPC UA Historical Access;
\- communication status;
\- gateway diagnostics;
\- logging;
\- configuration management;
\- auditability;
\- health monitoring.
\## 3.2 Not mandatory in the initial implementation
The following shall be considered extensions unless separately specified:
\- AquaCom machine control;
\- AquaCom setpoint modification;
\- OPC UA write access to control process equipment;
\- OPC UA Alarms \& Conditions;
\- historian aggregates;
\- report-generation services;
\- HTTP/REST interfaces;
\- MQTT publishing;
\- clustered gateway operation;
\- active/standby gateway redundancy.
The architecture shall not prevent these capabilities from being implemented later.
\---
\# 4. System context
The intended conceptual architecture is:
```text
  AquaCom field systems
  │
  ┌───────────┴───────────┐
  │ │
  Current values Stored history
  │ │
  ▼ ▼
  ┌────────────────────────────────────────┐
  │ AquaCom Protocol Layer │
  │ │
  │ Transport │
  │ Telegram codec │
  │ Session/state management │
  │ Station capability model │
  └───────────────────┬────────────────────┘
  │
  ▼
  ┌────────────────────────────────────────┐
  │ Canonical Gateway Model │
  └──────────┬───────────────────┬─────────┘
  │ │
  Current state Historical pipeline
  │ │
  │ ┌────────┴───────────┐
  │ │ │
  │ History store Storage adapters
  │ │ │
  │ │ ┌──────┼───────┐
  │ │ │ │ │
  │ │ DB File Historian
  │ │
  ▼ ▼
  ┌────────────────────┐
  │ OPC UA Server │
  │ │
  │ Data Access │
  │ Historical Access │
  └─────────┬──────────┘
  │
  ▼
  SCADA / clients
```
The OPC UA server and storage mechanisms shall consume the canonical gateway model rather than AquaCom telegrams directly.
\---
\# 5. Logical components
\## 5.1 AquaCom Transport Layer
The transport layer shall provide physical or network communication required by the target AquaCom implementation.
It shall be responsible for:
\- establishing communication;
\- maintaining connections;
\- reconnecting following failure;
\- sending telegrams;
\- receiving telegrams;
\- detecting transport timeout;
\- exposing transport diagnostics.
Transport handling shall not interpret process values.
The architecture shall allow multiple AquaCom transports to be implemented without changing higher-level application logic.
\---
\# 6. AquaCom Protocol Engine
The AquaCom Protocol Engine shall implement the AquaCom application protocol.
Its responsibilities shall include:
\- telegram framing;
\- address handling;
\- checksum validation;
\- telegram validation;
\- request generation;
\- response decoding;
\- error-response interpretation;
\- mapping protocol operations to logical operations;
\- protocol timeout handling;
\- detection of malformed telegrams.
The protocol implementation shall not directly:
\- write database records;
\- create OPC UA nodes;
\- modify OPC UA values;
\- make assumptions regarding graphical presentation.
The complete AquaCom protocol implementation shall be developed against an authoritative protocol specification and validated using captured communication from actual AquaCom equipment where possible.
\---
\# 7. Station Manager
Each AquaCom station shall have a logical station instance.
The Station Manager shall maintain information including:
| Attribute | Description |
|---|---|
| Station ID | Stable gateway identifier |
| AquaCom address | Protocol address |
| Name | Human-readable station name |
| Enabled | Station communication enabled/disabled |
| Connection state | Current communication status |
| Last successful communication | Gateway timestamp |
| Last device response | Timestamp |
| Consecutive errors | Communication diagnostic |
| History synchronization state | State of historical retrieval |
| Configuration version | Version of station definition |
Station configuration shall be independent of OPC UA NodeIds.
\---
\# 8. Station capability and point definition
The system shall maintain a definition of the information available from each station.
This definition may originate from:
\- AquaCom ATF files;
\- manually supplied configuration;
\- imported engineering data;
\- another machine-readable configuration source.
The point definition shall contain sufficient information to map raw AquaCom information into the canonical gateway model.
A point definition should support at least:
| Field | Purpose |
|---|---|
| PointId | Stable unique identifier |
| StationId | Parent station |
| Name | Human-readable designation |
| Source reference | AquaCom-specific identifier |
| Data type | Boolean, integer, floating point, text etc. |
| Engineering unit | Where applicable |
| Scaling | If required |
| Live enabled | Current value acquisition |
| History enabled | Historical acquisition |
| Historizing | Whether the gateway records the value |
| OPC UA enabled | Whether exposed through OPC UA |
| OPC UA NodeId | Stable configured/generated identifier |
| Storage policy | Storage behavior |
| Description | Engineering description |
Changes to display names shall not automatically change stable identifiers.
\---
\# 9. Canonical data model
AquaCom data shall be converted into a canonical representation before further processing.
\## 9.1 Current value
A current process value shall conceptually contain:
```text
CurrentValue
  StationId
  PointId
  Value
  DataType
  Quality
  SourceTimestamp
  ReceivedTimestamp
  UpdatedTimestamp
  Source
```
\### SourceTimestamp
`SourceTimestamp` represents the time associated with the process value at its source when such information is available.
\### ReceivedTimestamp
`ReceivedTimestamp` represents the time when the gateway received the value.
\### UpdatedTimestamp
`UpdatedTimestamp` represents the time when the current gateway state was updated.
The distinction between these timestamps shall be maintained internally.
OPC UA itself distinguishes source and server timestamps in its `DataValue` model, making this mapping appropriate.
\---
\# 10. Historical sample model
Historical process data shall use a distinct model:
```text
HistoricalSample
  StationId
  PointId
  SourceTimestamp
  ReceivedTimestamp
  Value
  DataType
  Quality
  AcquisitionSource
  AcquisitionId
```
`AcquisitionSource` shall identify how the value entered the gateway, for example:
```text
LIVE
AQUACOM\_HISTORY
AQUACOM\_REPORT
IMPORT
RECOVERY
```
The exact values are implementation-defined.
Historical samples shall never become current values solely because they have just been received.
Example:
```text
Gateway time: 18:31
Sample time: 14:05
Value: 2.31 m
```
The sample shall be stored as a value from 14:05 and shall not cause a normal live OPC UA subscription to report that the current process value is 2.31 m.
\---
\# 11. Live-value processing
The live-value subsystem shall maintain the latest known state of every configured current point.
A live update shall perform the following logical sequence:
```text
AquaCom telegram
  │
  ▼
Protocol decode
  │
  ▼
Point mapping
  │
  ▼
Type/scaling validation
  │
  ▼
Canonical CurrentValue
  │
  ├─────────► Current-state cache
  │
  ├─────────► OPC UA
  │
  └─────────► Historical pipeline
  if configured
```
Acquisition of live values and historization of those values shall be separate functions.
A point may therefore be:
\- exposed live but not stored;
\- stored but not exposed through OPC UA;
\- both exposed and stored;
\- disabled completely.
\---
\# 12. Historical acquisition
The gateway shall contain a History Acquisition Manager responsible for obtaining historical information available in AquaCom field equipment.
The component shall support:
\- normal periodic history retrieval;
\- history retrieval following reconnect;
\- configurable historical synchronization;
\- tracking the last successfully synchronized time;
\- detection of gaps where possible;
\- recovery/backfill;
\- duplicate suppression;
\- partial transfer recovery;
\- rate limitation so history retrieval does not prevent live communication.
A station shall maintain a persistent synchronization watermark where applicable.
Conceptually:
```text
Last complete history:
2026-10-05 12:00
Communication lost:
12:03
Communication restored:
17:24
Gateway determines missing interval:
12:00 → 17:24
Gateway requests AquaCom history.
Recovered historical values
  │
  ▼
Historical pipeline
  │
  ▼
Historian/storage
```
Live polling shall normally take priority over large backfill operations.
\---
\# 13. Duplicate handling
Historical processing shall be idempotent.
Receiving the same historical sample multiple times shall not normally result in multiple logical records.
A logical historical identity should be derivable from information equivalent to:
```text
StationId
PointId
SourceTimestamp
```
Where AquaCom provides additional sequence or sample identifiers, these may form part of the identity.
The implementation shall define behavior for the unusual situation where two different values are supplied for the same logical historical sample.
Supported strategies should include:
\- retain first value;
\- retain latest value;
\- version the sample;
\- flag conflict for diagnostics.
The selected strategy shall be configurable.
\---
\# 14. History repository abstraction
OPC UA Historical Access shall not directly depend on a specific database.
The gateway shall define a logical History Repository interface capable of operations equivalent to:
```text
StoreSample
StoreSamples
ReadRaw
ReadAtTime
GetOldestTimestamp
GetNewestTimestamp
CheckAvailability
```
The implementation technology is intentionally unspecified.
An installation may use:
\- an internal gateway historian;
\- an external relational database;
\- a time-series database;
\- an industrial historian;
\- another storage service capable of fulfilling the required history interface.
One configured history provider shall be designated as the authoritative source for OPC UA Historical Access.
\---
\# 15. Multiple historical storage destinations
The gateway shall permit historical information to be delivered to one or several destinations simultaneously.
Example:
```text
  Historical pipeline
  │
  ┌─────────────┼──────────────┐
  │ │ │
  ▼ ▼ ▼
  Local DB Enterprise Archive
  historian file
```
Storage destinations shall be implemented as independent adapters.
Failure of one destination shall not normally prevent delivery to another destination.
Each storage adapter shall independently maintain:
\- enabled state;
\- connection status;
\- last successful write;
\- error count;
\- pending record count;
\- retry state.
\---
\# 16. Storage adapter interface
A storage adapter shall consume canonical historical records.
The adapter shall not receive raw AquaCom telegrams.
A logical interface shall provide functionality equivalent to:
```text
Initialize
Store
StoreBatch
CheckHealth
Flush
Shutdown
```
Optional storage adapters may support queries, but writing and querying shall be considered separate capabilities.
Possible adapters include, without limiting implementations to:
\- relational database;
\- time-series database;
\- external historian;
\- append-only file;
\- structured CSV;
\- JSON/NDJSON;
\- message broker;
\- data-lake/object storage;
\- another application through an API.
\---
\# 17. Store-and-forward
The gateway shall provide a durable buffering mechanism when a configured storage destination is temporarily unavailable.
Example:
```text
AquaCom
  │
  ▼
History pipeline
  │
  ▼
Durable spool
  │
  ├──► Storage A
  ├──► Storage B
  └──► Storage C
```
Each destination shall maintain its own delivery acknowledgement.
A record shall therefore not be deleted from the spool merely because one of several destinations has accepted it.
The implementation should use at-least-once delivery semantics combined with idempotent storage where practical.
Configuration shall include:
\- maximum spool size;
\- maximum storage duration;
\- disk-space thresholds;
\- retry behavior;
\- overflow policy.
Loss of buffered information shall generate a diagnostic event.
\---
\# 18. OPC UA Server
The gateway shall contain an OPC UA server compliant with applicable OPC UA specifications.
OPC UA shall expose:
1\. current values through normal OPC UA Data Access;
2\. historical values through OPC UA Historical Access;
3\. gateway communication and synchronization diagnostics.
OPC UA Historical Access defines standardized mechanisms for exposing historical information, including `HistoryRead`; it does not require the historical backend itself to be a particular database technology.
\---
\# 19. OPC UA namespace
A logical namespace should use a structure comparable to:
```text
AquaCom
│
├── Stations
│ │
│ ├── Station01
│ │ ├── Process
│ │ │ ├── Level
│ │ │ ├── Pump01Running
│ │ │ └── Pump02Running
│ │ │
│ │ └── Diagnostics
│ │ ├── CommunicationState
│ │ ├── LastCommunication
│ │ ├── ProtocolErrors
│ │ ├── HistoryState
│ │ ├── LastHistorySync
│ │ └── PendingHistory
│ │
│ └── Station02
│
└── Gateway
  ├── Status
  ├── StartTime
  ├── Version
  ├── Storage
  └── Diagnostics
```
The precise hierarchy shall be configurable without changing the AquaCom protocol implementation.
\---
\# 20. Stable OPC UA NodeIds
NodeIds used for engineering data shall remain stable across:
\- gateway restart;
\- OPC UA server restart;
\- database restart;
\- software upgrade;
\- temporary station removal;
\- changes to point display names.
NodeIds shall therefore derive from stable engineering identifiers rather than runtime object allocation.
Changing the human-readable name of:
```text
Level
```
to:
```text
WetWellLevel
```
shall not automatically create a different logical OPC UA point.
\---
\# 21. Current OPC UA values
Each configured point exposed as current data shall support normal OPC UA reads.
Where appropriate it shall also support OPC UA subscriptions.
The OPC UA value shall contain:
\- process value;
\- appropriate StatusCode;
\- source timestamp where available;
\- server timestamp.
The gateway shall translate internal quality into appropriate OPC UA quality/status semantics.
Communication loss shall not silently retain an indefinitely "Good" value.
\---
\# 22. OPC UA Historical Access
Points configured for historical access shall advertise historical capability according to OPC UA.
OPC UA distinguishes whether history is available through the Variable's access attributes and whether the server is actively collecting history through its `Historizing` attribute.
The gateway shall support, at minimum:
\*\*Raw historical reads\*\*
```text
HistoryRead
Point
StartTime
EndTime
MaximumValues
```
The implementation shall support continuation where the requested history exceeds the configured response size.
Historical responses shall maintain:
\- process value;
\- source timestamp;
\- applicable quality/status information.
The gateway shall not require historical data to have originally been received while an OPC UA client was connected.
\---
\# 23. HistoryRead data flow
A Historical Access request shall follow the logical path:
```text
OPC UA Client
  │
  │ HistoryRead
  ▼
OPC UA Server
  │
  ▼
History Provider
  │
  ▼
Configured authoritative repository
  │
  ▼
Canonical HistoricalSample\[]
  │
  ▼
OPC UA DataValue\[]
  │
  ▼
OPC UA Client
```
The OPC UA layer shall not perform AquaCom history polling synchronously in response to a client `HistoryRead`.
Historical retrieval from field equipment and historical access from clients shall therefore be decoupled.
This prevents a long-running AquaCom operation from blocking an OPC UA request.
\---
\# 24. OPC UA HistoryUpdate
Modification of historical records through OPC UA shall be disabled by default.
If later enabled, separate authorization shall be required.
Normal SCADA clients shall not be permitted to alter gateway history solely because they are allowed to read it.
\---
\# 25. Current state versus historical state
The gateway shall maintain a strict separation:
```text
Current State
  │
  └── latest known process value
Historical State
  │
  └── timestamped sequence of previous process values
```
Historical backfill shall never cause an old value to overwrite a newer current value unless a separately defined reconciliation rule determines that the current state itself is invalid.
\---
\# 26. Time handling
All internal timestamps shall have an unambiguous time basis.
UTC shall be preferred internally.
The system shall preserve information necessary to correctly interpret AquaCom timestamps supplied in local time.
Configuration shall include:
\- station timezone;
\- daylight-saving-time handling;
\- assumed timezone for timestamps lacking zone information;
\- permitted clock deviation;
\- invalid-time handling.
The system shall detect or flag where practical:
\- future timestamps;
\- implausibly old timestamps;
\- backward-moving device clocks;
\- duplicate timestamps;
\- ambiguous daylight-saving-time timestamps.
Original source timestamps shall not silently be replaced by gateway receipt time.
\---
\# 27. Quality handling
The canonical data model shall contain protocol-independent data quality.
At minimum the internal model shall distinguish:
```text
GOOD
UNCERTAIN
BAD
UNKNOWN
```
Additional sub-status information may identify:
\- communication failure;
\- stale value;
\- configuration error;
\- conversion error;
\- invalid source value;
\- historical gap;
\- timestamp uncertainty.
The OPC UA layer shall map internal quality to suitable OPC UA `StatusCode` values.
Storage adapters shall retain quality information where the destination format supports it.
\---
\# 28. Configuration
Configuration shall be external to the executable software and shall be machine-readable.
Configuration shall cover at least:
\- gateway identity;
\- AquaCom stations;
\- transports;
\- point definitions;
\- polling;
\- historical acquisition;
\- OPC UA namespace;
\- OPC UA endpoints;
\- certificates;
\- authorization;
\- storage destinations;
\- historian configuration;
\- buffering;
\- logging;
\- diagnostics.
Configuration shall be versionable using normal source-control mechanisms.
Secrets shall not be stored as unprotected ordinary configuration values.
\---
\# 29. Dynamic configuration
Where technically reasonable, non-structural configuration should be reloadable without restarting the entire gateway.
Structural changes that affect point identity or protocol configuration may require controlled restart.
The gateway shall validate configuration before activation.
Invalid configuration shall not replace the last known valid configuration.
\---
\# 30. Security
The OPC UA endpoint shall use OPC UA security mechanisms supporting:
\- server authentication;
\- client/application authentication;
\- confidentiality;
\- integrity;
\- user authorization where required.
The OPC UA security model provides application authentication using certificates as well as user authentication and authorization mechanisms.
Security mode `None` shall be disabled by default. Current OPC UA guidance specifies that the None profile should be disabled by default.
The gateway shall support certificate trust management.
Administrative functions shall be restricted separately from normal OPC UA data access.
\---
\# 31. AquaCom security boundary
AquaCom communication shall be treated as communication with a legacy field protocol.
Security controls around AquaCom shall therefore be provided by the surrounding OT architecture, for example:
```text
Enterprise/SCADA network
  │
  Firewall
  │
  AquaCom Gateway
  │
  OT network
  │
  VPN/router/firewall
  │
  AquaCom RTU
```
The gateway shall not assume that authenticity, confidentiality or authorization are inherently provided by AquaCom.
\---
\# 32. Diagnostics
The system shall expose diagnostic information for the gateway and every station.
Station diagnostics shall include at least:
```text
Enabled
CommunicationState
LastSuccessfulCommunication
LastRequest
LastResponse
CommunicationErrors
ProtocolErrors
LastValidValue
HistorySynchronizationState
LastHistorySynchronization
HistoricalBacklog
```
Gateway diagnostics shall include:
```text
GatewayState
SoftwareVersion
ConfigurationVersion
StartTime
Uptime
ConnectedStations
FailedStations
HistoricalQueueDepth
SpoolUsage
OPCUAState
```
Storage diagnostics shall be available for each configured destination:
```text
State
LastSuccessfulWrite
LastError
PendingRecords
RetryCount
```
\---
\# 33. Logging
Logging shall distinguish at minimum:
\- operational information;
\- communication errors;
\- protocol errors;
\- configuration errors;
\- storage errors;
\- security events;
\- historical synchronization events;
\- software faults.
Raw AquaCom telegram logging shall be separately configurable because it may generate large volumes of information.
Sensitive information shall not be unnecessarily written to normal logs.
\---
\# 34. Audit logging
Security-relevant and administrative changes shall be auditable.
Examples include:
\- configuration changed;
\- station enabled/disabled;
\- certificate trusted/rejected;
\- storage adapter changed;
\- history synchronization manually initiated;
\- historical records administratively modified;
\- software started/stopped.
Future control functionality shall additionally audit all process commands.
\---
\# 35. Failure handling
The gateway shall continue providing unaffected functionality where practical.
Examples:
| Failure | Expected behavior |
|---|---|
| One AquaCom station fails | Other stations continue |
| One storage destination fails | Other destinations continue |
| OPC UA client disconnects | Acquisition continues |
| OPC UA server temporarily unavailable | AquaCom acquisition continues where architecture permits |
| External historian fails | Records buffered |
| Gateway restarts | Persistent synchronization state recovered |
| Invalid telegram received | Telegram rejected and diagnostic generated |
| Historical duplicate received | Deduplication policy applied |
A failure in a secondary data consumer shall not stop AquaCom communication.
\---
\# 36. Startup sequence
A logical startup shall perform:
```text
Load configuration
  ↓
Validate configuration
  ↓
Initialize persistent state
  ↓
Initialize storage adapters
  ↓
Initialize historical subsystem
  ↓
Initialize OPC UA namespace
  ↓
Initialize AquaCom stations
  ↓
Start acquisition
  ↓
Start history synchronization
```
A storage destination that is temporarily unavailable during startup shall not necessarily prevent the complete gateway from entering service.
\---
\# 37. Shutdown
Shutdown shall be controlled.
The gateway shall:
1\. stop accepting new administrative work;
2\. stop initiating new AquaCom transactions;
3\. finish or cancel active transactions safely;
4\. persist synchronization watermarks;
5\. flush historical queues where possible;
6\. close storage adapters;
7\. close OPC UA services;
8\. terminate.
Unclean shutdown shall be detectable at the next startup.
\---
\# 38. Persistence of gateway state
State required for reliable recovery shall survive restart.
This includes, where applicable:
\- history synchronization watermarks;
\- spool contents;
\- delivery acknowledgements;
\- configuration version;
\- station state needed for recovery.
Transient live values need not be permanently persisted unless required by installation policy.
\---
\# 39. Historical retention
Retention shall be configurable independently for each storage destination.
The gateway shall not assume that all historical destinations have the same retention period.
For example:
```text
Local operational cache 30 days
Central historian 10 years
Archive indefinite
```
These values are examples only and are not system defaults.
\---
\# 40. Data export extensibility
The internal historical pipeline shall permit future exporters without modification to the AquaCom protocol implementation.
Examples might later include:
```text
AquaCom
  ↓
Canonical data
  ├── OPC UA
  ├── SQL
  ├── time-series DB
  ├── enterprise historian
  ├── MQTT
  └── data lake
```
This shall be achieved through explicit interfaces rather than direct dependencies between components.
\---
\# 41. Performance requirements
Performance targets shall be installation-specific and configurable.
The gateway architecture shall support measurement of:
\- AquaCom request latency;
\- point update latency;
\- OPC UA response latency;
\- historical ingestion rate;
\- history query time;
\- pending history size;
\- storage write throughput;
\- spool utilization.
Historical backfill shall have configurable throttling.
Large history synchronization jobs shall not starve current-value acquisition.
\---
\# 42. Resource limits
The gateway shall protect itself against unbounded resource consumption.
Configurable limits shall include:
\- maximum AquaCom telegram size;
\- maximum queued requests;
\- maximum OPC UA HistoryRead result size;
\- maximum number of simultaneous historical queries;
\- maximum spool storage;
\- maximum storage batch size;
\- maximum diagnostic-log size.
OPC UA continuation mechanisms shall be used when a historical query exceeds the configured response size.
\---
\# 43. Deployment
The specification shall not assume a particular operating system.
The gateway should be capable of deployment as a long-running service.
The implementation shall allow unattended startup following host restart.
Runtime dependencies shall be documented and minimized.
The gateway should support deployment in either:
```text
Physical/virtual OT server
```
or
```text
Containerized environment
```
provided that the selected deployment method satisfies communication and security requirements.
\---
\# 44. Internal component boundaries
The following logical modules shall remain separable:
```text
AquaCom Transport
  │
AquaCom Protocol
  │
Station/session handling
  │
Canonical Data Model
  │
 ┌──────┴────────┐
 │ │
Live State History Engine
 │ │
 │ ┌─────┴───────┐
 │ │ │
OPC UA Repository Storage adapters
```
A change of OPC UA library shall not require reimplementation of AquaCom.
A change of database shall not require reimplementation of AquaCom.
A new storage adapter shall not require modification to the AquaCom parser.
\---
\# 45. Testing requirements
The system shall support automated testing at multiple levels.
\## 45.1 Protocol unit tests
Tests shall verify:
\- telegram framing;
\- checksum calculation;
\- request encoding;
\- response decoding;
\- invalid telegram detection;
\- timeout behavior;
\- error response handling.
Known production captures should be converted into reusable test vectors where legally and operationally appropriate.
\---
\## 45.2 AquaCom simulator
A simulator or mock endpoint shall be provided for development and testing.
It shall support:
\- normal responses;
\- configurable live values;
\- historical data;
\- delayed responses;
\- malformed telegrams;
\- communication loss;
\- duplicate historical samples;
\- clock anomalies.
Development shall not require connection to operational wastewater infrastructure.
\---
\## 45.3 Historical tests
Tests shall verify:
```text
Historical backfill after outage
Duplicate handling
Timestamp preservation
Quality preservation
Partial synchronization recovery
Gateway restart during backfill
Storage destination outage
Spool replay
Multi-destination delivery
```
\---
\## 45.4 OPC UA tests
Tests shall verify:
\- namespace creation;
\- stable NodeIds;
\- current reads;
\- subscriptions;
\- source timestamps;
\- quality;
\- HistoryRead;
\- continuation;
\- empty historical intervals;
\- large historical intervals;
\- station communication loss;
\- certificate validation;
\- authorization.
\---
\# 46. End-to-end acceptance scenario
A mandatory acceptance scenario shall simulate:
```text
1\. Station communicating normally.
2\. Live values available through OPC UA.
3\. Values stored historically.
4\. AquaCom connection interrupted.
5\. OPC UA indicates communication degradation.
6\. Station continues recording locally.
7\. AquaCom connection restored.
8\. Gateway resumes live acquisition.
9\. Gateway determines missing historical interval.
10\. Gateway retrieves missing samples.
11\. Retrieved samples retain their original timestamps.
12\. Historical samples are persisted.
13\. Old historical samples do not appear as new current values.
14\. OPC UA HistoryRead returns the complete time interval.
15\. Configured secondary historical destinations receive the recovered data.
16\. Duplicate acquisition does not produce unintended duplicate records.
```
Successful execution of this scenario shall be a principal acceptance criterion for the gateway.
\---
\# 47. Recommended initial functional baseline
The first production-capable release should implement:
```text
AquaCom communication
AquaCom live acquisition
AquaCom historical acquisition
Station configuration
Point mapping
Canonical data model
Live-value cache
Historical repository
Backfill manager
Deduplication
Persistent synchronization watermark
Store-and-forward queue
At least one historical storage adapter
Storage adapter framework
OPC UA Data Access
OPC UA Historical Access
OPC UA security
Diagnostics
Logging
AquaCom simulator
Automated protocol tests
Automated history tests
```
This baseline deliberately excludes remote process control.
\---
\# 48. Future extensions
The architecture shall permit later addition of:
```text
OPC UA Alarms \& Conditions
AquaCom alarm/event retrieval
AquaCom machine control
AquaCom setpoint management
OPC UA Methods
OPC UA writable Variables
MQTT
REST API
central configuration management
redundant gateways
high availability
multiple gateway federation
external identity management
historical aggregates
automated station discovery
```
OPC UA Alarms \& Conditions is defined separately in OPC UA Part 9 and can therefore be introduced later without treating alarm events as ordinary process-value history.
\---
\# 49. Key architectural decision
The system shall be considered an:
\*\*AquaCom Integration Gateway\*\*
rather than merely an:
\*\*AquaCom OPC UA Server\*\*.
The distinction is intentional.
The internal architecture shall be:
```text
  AQUACOM
  │
  ▼
  Protocol abstraction
  │
  ▼
  Canonical data
  │
  ┌───────────┼────────────┐
  │ │ │
  ▼ ▼ ▼
  Live state History Diagnostics
  │ │
  │ ┌─────┼───────────────┐
  │ │ │ │
  ▼ ▼ ▼ ▼
  OPC UA DB Historian Archive
  │
  ├── Data Access
  └── Historical Access
```
OPC UA is consequently one standardized northbound interface to the gateway rather than the mechanism upon which acquisition and historical storage depend.
\---
\# 50. Architectural rule for historical information
The following rule shall be treated as fundamental:
> \*\*A historical sample represents the state of the process at its SourceTimestamp, not the state of the process at the time the gateway received the sample.\*\*
Therefore:
```text
Historical recovery
  ≠
replay of live values
```
and:
```text
AquaCom historical timestamp
  │
  ▼
Canonical SourceTimestamp
  │
  ├──► Historical repository
  ├──► External storage
  └──► OPC UA Historical Access
```
This rule shall apply consistently throughout implementation, testing and validation.
\---
\# 51. Architectural rule for storage
Historical acquisition and historical storage shall be decoupled.
The gateway shall be capable of configurations conceptually equivalent to:
```text
Configuration A
AquaCom
  ↓
Gateway
  ↓
OPC UA live only
```
```text
Configuration B
AquaCom
  ↓
Gateway
  ├── OPC UA live
  └── Internal history
  ↓
  OPC UA HA
```
```text
Configuration C
AquaCom
  ↓
Gateway
  ├── OPC UA
  ├── SQL
  └── Historian
```
```text
Configuration D
AquaCom
  ↓
Gateway
  ├── OPC UA
  ├── Time-series DB
  ├── Enterprise historian
  ├── Archive
  └── Future integration adapter
```
The protocol implementation shall be identical in all cases.
\---
\# 52. Requirement summary
| ID | Requirement |
|---|---|
| AQG-001 | AquaCom shall be isolated behind a protocol abstraction. |
| AQG-002 | Current and historical data shall use a canonical internal model. |
| AQG-003 | Current and historical processing shall be separated. |
| AQG-004 | Original source timestamps shall be preserved. |
| AQG-005 | Historical backfill shall not modify current state with obsolete values. |
| AQG-006 | Historical acquisition shall recover after communication interruption where supported by the RTU. |
| AQG-007 | Historical ingestion shall support duplicate suppression. |
| AQG-008 | Synchronization progress shall survive gateway restart. |
| AQG-009 | Historical storage shall use replaceable adapters. |
| AQG-010 | Multiple historical storage destinations shall be supported. |
| AQG-011 | Failure of one destination shall not normally block others. |
| AQG-012 | Store-and-forward shall protect data during destination failure. |
| AQG-013 | OPC UA shall expose current process values. |
| AQG-014 | OPC UA shall support subscriptions for configured current values. |
| AQG-015 | OPC UA Historical Access shall expose configured historical information. |
| AQG-016 | OPC UA NodeIds shall be stable. |
| AQG-017 | OPC UA history shall be retrieved through an abstract History Provider. |
| AQG-018 | OPC UA HistoryRead shall not directly initiate synchronous AquaCom retrieval. |
| AQG-019 | Data quality shall be maintained through acquisition, storage and OPC UA. |
| AQG-020 | Historical SourceTimestamp and gateway ReceivedTimestamp shall remain distinguishable. |
| AQG-021 | OPC UA security shall be enabled by default. |
| AQG-022 | Configuration shall be machine-readable and versionable. |
| AQG-023 | Gateway diagnostics shall be available independently of process values. |
| AQG-024 | AquaCom communication shall be testable without operational field equipment. |
| AQG-025 | A simulator or equivalent mock environment shall be available. |
| AQG-026 | The software shall not depend upon a particular historical database implementation. |
| AQG-027 | The software architecture shall not depend upon a particular programming language. |
| AQG-028 | Live acquisition shall take precedence over bulk history recovery where necessary. |
| AQG-029 | HistoryWrite through OPC UA shall be disabled by default. |
| AQG-030 | Administrative and security-sensitive operations shall be auditable. |
\---
\# 53. Final target architecture
```text
  FIELD LAYER
  │
  AquaCom-compatible
  RTU / PLC
  │
  ▼
  ┌───────────────────┐
  │ AquaCom Transport │
  └─────────┬─────────┘
  │
  ┌─────────▼─────────┐
  │ AquaCom Protocol │
  │ Engine │
  └─────────┬─────────┘
  │
  ┌─────────▼─────────┐
  │ Station Manager │
  └─────────┬─────────┘
  │
  ┌─────────▼─────────┐
  │ Canonical Model │
  └────┬─────────┬────┘
  │ │
  LIVE │ │ HISTORY
  │ │
  ┌──────────▼───┐ ┌───▼────────────────┐
  │ Current State│ │ History Acquisition │
  │ Cache │ │ / Backfill Manager │
  └──────┬───────┘ └─────────┬──────────┘
  │ │
  │ ┌─────▼─────┐
  │ │ Historical│
  │ │ Pipeline │
  │ └─────┬─────┘
  │ │
  │ ┌───────────┼───────────┐
  │ │ │ │
  │ ▼ ▼ ▼
  │ Repository Storage A Storage B
  │ │
  │ │
  ┌──────▼───────▼──────┐
  │ OPC UA Server │
  │ │
  │ Data Access │
  │ Historical Access │
  └──────────┬──────────┘
  │
  ▼
  SCADA / historian /
  analytics clients
```
This architecture shall be the baseline for detailed design and implementation.
Reference in New Issue View Git Blame Copy Permalink