Reads JSON-encoded process values from a NATS JetStream consumer and forwards them to connected IEC-104 clients as spontaneous data using lib60870.

Optional Mutual TLS (IEC 62351-3) mode secures the IEC-104 transport layer with client-certificate authentication.

flowchart LR
    nats["NATS JetStream"]
    bridge["Bridge\nparse + dispatch\ndata cache"]
    clients["lib60870 server\nTCP :2404\nIEC-104 master(s)"]

    nats -->|"JSON (ack after dispatch)"| bridge
    bridge -->|"IEC-104 ASDUs\n(spontaneous + GI)"| clients

When TLS_ENABLED=true the lib60870 server binds on loopback only. A separate TLS listener (default port 19998) handles mTLS handshakes and proxies plaintext bytes to lib60870.

flowchart LR
    nats["NATS JetStream"]
    bridge["Bridge\nparse + dispatch\ndata cache"]
    tls["TLS proxy\nmTLS :19998\nIEC 62351-3"]
    iec["lib60870 server\n127.0.0.1:2404\n(loopback only)"]
    master["IEC-104 master\n(SCADA)"]

    nats -->|"JSON"| bridge
    bridge --> iec
    master -->|"mTLS"| tls
    tls -->|"plaintext"| iec

The bridge maintains a data cache keyed by (ca, ioa). When a client sends a General Interrogation command the bridge replays the most recent value for every cached IOA.

NATS JetStream messages are acknowledged after bridge::dispatch() returns (i.e. after the ASDU has been enqueued in lib60870's outbound buffer). This means a crash between message receipt and dispatch causes the broker to redeliver the message rather than silently dropping it. Unparseable (invalid JSON) messages are acknowledged immediately to prevent infinite redelivery.

IEC 60870-5-104 (IEC-104) is a telecontrol protocol used in power-system automation to exchange process data — breaker states, voltages, currents, temperatures — between a controlling station (master) and one or more controlled stations (outstations / RTUs). It runs over TCP/IP, typically on port 2404.

This bridge acts as a server. It accepts any number of simultaneous IEC-104 client connections and pushes data updates to all of them.

sequenceDiagram
    participant C as Client
    participant S as Server (bridge)

    C->>S: TCP SYN
    S->>C: TCP SYN-ACK
    C->>S: STARTDT act
    S->>C: STARTDT con
    note over C,S: data transfer active
    S-->>C: spontaneous ASDUs (live updates)
    C->>S: C_IC_NA_1 — General Interrogation
    S->>C: C_IC_NA_1 + ACT_CON
    loop one ASDU per cached IOA
        S->>C: data ASDU
    end
    S->>C: C_IC_NA_1 + ACT_TERM

Every TCP payload is an APDU (Application Protocol Data Unit):

packet-beta
title APDU / ASDU Frame Structure
0-7: "Start (0x68)"
8-15: "Length"
16-47: "Control field (4 bytes)"
48-55: "Type ID"
56-63: "VSQ"
64-71: "COT"
72-79: "OA"
80-95: "CA (2 bytes)"
96-127: "Information objects (variable)"

The Type ID through Information objects fields form the ASDU and are only present in I-frames. S-frames and U-frames carry only the 6-byte APDU header (Start + Length + Control field).

Key APDU types:

Key ASDU fields:

The QDS byte accompanies every measurement value. The bridge maps the JSON "quality" field to these bits:

Every message must be a valid JSON object on a single line. The bridge parses it, looks up the right IEC-104 type and quality flags, and dispatches the corresponding ASDU to all connected clients.

Required fields (the bridge will reject messages that omit either of these):

Optional fields:

Selects the IEC-104 Type ID and wire encoding. The bridge maps each string to a specific ASDU type (see the Type IDs table in the protocol primer above):

When "type" is omitted the type is inferred from the JSON value:

Maps directly to the Quality Descriptor (QDS) byte sent in each ASDU (see the QDS table in the protocol primer above).

"good" (default), "invalid", "not_topical", "substituted", "blocked", "overflow"

The Cause of Transmission field (COT) appears in every ASDU header and tells the client why this value is being sent. Most consumers log or filter on it.

"spontaneous" (default), "periodic", "background_scan", "interrogated", "return_info_remote", "return_info_local"

All configuration is via environment variables.

When TLS_ENABLED=true:

• The IEC-104 server binds on 127.0.0.1:IEC104_PORT (loopback only — not directly reachable from the network).
• A TLS proxy listens on IEC104_BIND_ADDR:TLS_PORT, performs the mTLS handshake, and forwards plaintext to lib60870.
• All three certificate paths are required — the bridge refuses to start if any is missing.
• rustls's default cipher suite list is used: TLS 1.3 (preferred) + TLS 1.2. No unsafe ciphers are enabled.

cargo build --release
# binary: target/release/iec104bridge

export NATS_URL="nats://localhost:4222"
export NATS_STREAM="sensors"
export NATS_CONSUMER="iec104bridge"
export NATS_SUBJECT_FILTER="plant.a.>"   # optional
export IEC104_PORT=2404
export IEC104_CA=1
cargo run

Publish a test message:

nats pub plant.a.breaker '{"ioa":1001,"value":true,"type":"single_point"}'
nats pub plant.a.voltage '{"ioa":2001,"value":132.4,"type":"float"}'

Generate test certificates (replace with your CA-issued certificates in production):

# Root CA
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -days 3650 \
    -keyout ca.key -out ca.crt -nodes -subj "/CN=IEC62351-CA"

# Server key + CSR + sign
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
    -keyout server.key -out server.csr -nodes -subj "/CN=iec104bridge"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out server.crt -days 365

# Client key + CSR + sign (for the SCADA master)
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
    -keyout client.key -out client.csr -nodes -subj "/CN=scada-master"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out client.crt -days 365

Run the bridge in TLS mode:

export NATS_URL="nats://localhost:4222"
export NATS_STREAM="sensors"
export NATS_CONSUMER="iec104bridge"
export TLS_ENABLED=true
export TLS_CERT_PATH=/etc/iec104/server.crt
export TLS_KEY_PATH=/etc/iec104/server.key
export TLS_CA_CERT_PATH=/etc/iec104/ca.crt
# TLS_PORT defaults to 19998; IEC104_PORT stays 2404 (loopback only)
cargo run

The bridge will:

1. Bind lib60870 on 127.0.0.1:2404 (not externally reachable).
2. Start a TLS listener on 0.0.0.0:19998.
3. Reject any client that does not present a certificate signed by ca.crt.
4. Log a warning with the failure reason for any failed handshake.

examples/messages.jsonl contains a static DLR snapshot matching the IOA scheme used by the demo publisher. It is intended as a reference for IOA layout and message format; the live demo uses NATS.

New sources can be added by implementing the MessageSource trait in src/source.rs. A FileSource (JSONL replay) or a Unix-socket source are natural future additions.

This section describes what information must be gathered before deploying the bridge at a client site, and what decisions must be made jointly between the client and the integrator.

These are facts about the client's existing infrastructure that the bridge must be configured to match. The bridge cannot operate correctly without them.

These items have no single correct answer — they depend on the client's operational conventions and the upstream data model. They should be agreed and documented before any configuration is written.

The most important shared design decision. Every measurement that the bridge publishes needs a unique IOA within its CA. A consistent numbering convention makes maintenance and troubleshooting much easier.

Suggested starting questions:

• Is there an existing IOA scheme already in use in the site's SCADA? If so, the bridge must match it.
• If starting fresh: organise by signal type (all temperatures in one block, all currents in another) or by physical asset (all signals for span 1 together)?
• Do multiple CAs share the same IOA namespace, or is each CA independent?

Example scheme (DLR deployment, 2 lines × 10 spans):

Deliverable: an IOA register spreadsheet listing every (ca, ioa) pair, its engineering description, unit, Type ID, and the NATS subject/key that produces the value.

For scaled signals, agree on the scaling factor: the bridge sends the raw integer value as-is (clamped to int16), so the upstream publisher and the SCADA master must agree on what one LSB represents (e.g. 1 A, 0.1 A).

Define how upstream systems name their subjects so the bridge's subject filter is unambiguous:

<site>.<asset-class>.<asset-id>.<signal>
plant.line.1.span.3.temperature
plant.line.1.span.3.ampacity
plant.line.1.line_ampacity

Decide what happens when the upstream publisher reports degraded quality:

• What is the expected publish interval from the upstream data source?
• Should the SCADA master poll GI on connect only, or also periodically?
• If periodically: what interval is acceptable given the number of cached IOAs?

• IEC-104 bind address and port confirmed, firewall rule open
• Common Address(es) agreed and match SCADA configuration
• IOA register complete and reviewed by SCADA team
• Type IDs and scaling factors agreed for all scaled signals
• NATS cluster URLs, stream name, and consumer name supplied; credentials file provided if authentication is required
• NATS subject naming convention agreed and applied to publisher
• Quality propagation policy documented
• Bridge environment variables written and reviewed (see Configuration table)
• End-to-end test: publish one message per Type ID, confirm SCADA receives it
• GI test: trigger General Interrogation, confirm all cached points returned
• Failover test: disconnect and reconnect NATS; confirm bridge recovers

• Root CA certificate obtained and trusted by both bridge and SCADA master
• Server certificate and private key issued, signed by Root CA
• Client certificate(s) issued for each SCADA master, signed by Root CA
• TLS_ENABLED=true and all three TLS_*_PATH vars set in bridge config
• Firewall permits TCP on TLS_PORT (default 19998) from master IP(s)
• Handshake test: connect a test client with the client cert, confirm bridge logs.
• Rejection test: connect without a client cert, confirm bridge logs
• Certificate expiry dates recorded; renewal procedure agreed