jobe/aquacom-gateway-suite

Fork 0

Files

T

Jonas Bengtsson 08d44babbb 📝 Update documents

2026-10-05 21:27:47 +02:00

47 KiB

Raw Blame History

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

Requirement keywords

The key words in this document are to be interpreted as follows:

shall / must — an absolute requirement of this specification;
shall not — an absolute prohibition;
should — a strong recommendation; deviations require a documented reason (an ExecPlan entry is sufficient);
may / can — truly optional behavior.

Hedged wording such as "where practical" or "where applicable" does not weaken a shall; it delegates the boundary decision to the implementation, which must then document where the requirement applies and where it does not.

The system shall be designed around the following principles:

Protocol isolation

AquaCom telegram handling shall be isolated from OPC UA, persistence and application logic.
Canonical data model

AquaCom information shall be transformed into an internal protocol-independent representation before being exposed or stored.
Separation of live and historical processing

Historical samples retrieved from an RTU shall not be replayed as current values.
Source timestamp preservation

Timestamps originating from the field device shall be retained throughout the system.
Storage independence

Historical information shall not be coupled to a specific database technology.
Multiple storage targets

The gateway shall support simultaneous writing to zero, one or several configured historical destinations.
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.
Recoverability

Temporary failure of a communication channel, storage destination or OPC UA client shall not result in unnecessary loss of recoverable historical data.
Deterministic and testable protocol implementation

AquaCom encoding, decoding and state handling shall be independently testable.
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:


                     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.

A transport may be shared by several stations (for example a serial multi-drop bus or a modem pool serving multiple RTUs). The transport abstraction shall therefore support arbitration between station sessions using the same physical medium, and the Station Manager shall not assume exclusive one-to-one ownership between a station and a transport instance. For point-to-point transports such as TCP, one transport per station remains the normal case.

Whether AquaCom stations may share one physical medium is a protocol question and shall be answered from verified protocol documentation before multi-drop operation is enabled (see docs/protocol/).

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:


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:


HistoricalSample

    StationId

    PointId

    SourceTimestamp

    ReceivedTimestamp

    Value

    DataType

    Quality

    AcquisitionSource

    AcquisitionId

AcquisitionSource shall identify how the value entered the gateway, for example:


LIVE

AQUACOM_HISTORY

AQUACOM_REPORT

IMPORT

RECOVERY

SIMULATOR

The exact values are implementation-defined.

Historical samples shall never become current values solely because they have just been received.

A record that arrives through a historical acquisition path but carries no usable SourceTimestamp shall be quarantined with diagnostics: rejected from normal process history, recorded distinctly for investigation, and never silently stored with a fabricated or gateway-generated timestamp. Rejected history acquisition may then be retried once the timestamp problem is resolved. Fabricating a SourceTimestamp solely to make storage convenient is prohibited.

Example:


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:


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:


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:


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, and the default shall be flag conflict for diagnostics (REJECT_CONFLICT). The default deliberately favors explicit conflict detection over silent overwrite: a conflicting historical value usually indicates an equipment, clock, or retrieval problem, and overwriting would hide it.

Historical processing shall remain idempotent across restart. A gateway restart during backfill or spool replay shall not create duplicate logical records for samples received before the restart (see §12 and §17).

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:


StoreSample

StoreSamples

ReadRaw

ReadAtTime

GetOldestTimestamp

GetNewestTimestamp

CheckAvailability

Note: this specification uses requirement-style names (StoreSample, ReadRaw, ...). The concrete method signatures — store(sample), storeBatch(samples), readRaw(...), readAtTime(...), getBounds(...) — are defined in ARCHITECTURE.md §25 and shall be used consistently by all implementations.

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:


                     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:


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:


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:

current values through normal OPC UA Data Access;
historical values through OPC UA Historical Access;
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:


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:


Level

to:


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


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:


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:


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:


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:


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:


Enabled

CommunicationState

LastSuccessfulCommunication

LastRequest

LastResponse

CommunicationErrors

ProtocolErrors

LastValidValue

HistorySynchronizationState

LastHistorySynchronization

HistoricalBacklog

Gateway diagnostics shall include:


GatewayState

SoftwareVersion

ConfigurationVersion

StartTime

Uptime

ConnectedStations

FailedStations

HistoricalQueueDepth

SpoolUsage

OPCUAState

Storage diagnostics shall be available for each configured destination:


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:


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:

stop accepting new administrative work;
stop initiating new AquaCom transactions;
finish or cancel active transactions safely;
persist synchronization watermarks;
flush historical queues where possible;
close storage adapters;
close OPC UA services;
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:


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:


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:


Physical/virtual OT server


Containerized environment

provided that the selected deployment method satisfies communication and security requirements.

44. Internal component boundaries

The following logical modules shall remain separable:


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:


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

Out-of-order arrival (backfill delivered after newer live samples)

Queries return results ordered by SourceTimestamp, not arrival order

Records rejected or quarantined when the source timestamp is missing or unusable

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:


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:


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:


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:


                   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:


Historical recovery

        ≠

replay of live values

and:


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:


Configuration A

AquaCom

   ↓

Gateway

   ↓

OPC UA live only


Configuration B

AquaCom

   ↓

Gateway

   ├── OPC UA live

   └── Internal history

          ↓

       OPC UA HA


Configuration C

AquaCom

   ↓

Gateway

   ├── OPC UA

   ├── SQL

   └── Historian


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


                          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.

47 KiB Raw Blame History Unescape Escape

Software Specification – AquaCom Integration Gateway

1. Purpose

2. Design objectives

Requirement keywords

3. Scope

3.1 Included

3.2 Not mandatory in the initial implementation

4. System context

5. Logical components

5.1 AquaCom Transport Layer

6. AquaCom Protocol Engine

7. Station Manager

8. Station capability and point definition

9. Canonical data model

9.1 Current value

SourceTimestamp

ReceivedTimestamp

UpdatedTimestamp

10. Historical sample model

11. Live-value processing

12. Historical acquisition

13. Duplicate handling

14. History repository abstraction

15. Multiple historical storage destinations

16. Storage adapter interface

17. Store-and-forward

18. OPC UA Server

19. OPC UA namespace

20. Stable OPC UA NodeIds

21. Current OPC UA values

22. OPC UA Historical Access

23. HistoryRead data flow

24. OPC UA HistoryUpdate

25. Current state versus historical state

26. Time handling

27. Quality handling

28. Configuration

29. Dynamic configuration

30. Security

31. AquaCom security boundary

32. Diagnostics

33. Logging

34. Audit logging

35. Failure handling

36. Startup sequence

37. Shutdown

38. Persistence of gateway state

39. Historical retention

40. Data export extensibility

41. Performance requirements

42. Resource limits

43. Deployment

44. Internal component boundaries

45. Testing requirements

45.1 Protocol unit tests

45.2 AquaCom simulator

45.3 Historical tests

45.4 OPC UA tests

46. End-to-end acceptance scenario

47. Recommended initial functional baseline

48. Future extensions

49. Key architectural decision

50. Architectural rule for historical information

51. Architectural rule for storage

52. Requirement summary

53. Final target architecture

47 KiB

Raw Blame History