# mz-automation/lib60870 architecture

> Architecture diagram of the GitHub repository mz-automation/lib60870, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mz-automation/lib60870
- Repository: https://github.com/mz-automation/lib60870

## Overview

This repository is a portable C library that implements IEC 60870-5-101 and IEC 60870-5-104 communication stacks, plus examples and tests. The architecture is layered around a protocol core, a platform abstraction layer, and transport-specific adapters.

High-level structure

- Public API surface: `lib60870-C/src/inc/api`
- Internal protocol implementation: `lib60870-C/src/iec60870`
- Platform abstraction layer (HAL): `lib60870-C/src/hal`
- Shared utility code: `lib60870-C/src/common`
- File transfer support: `lib60870-C/src/file-service`
- Examples: `lib60870-C/examples`
- Tests and certificates: `lib60870-C/tests`
- Build/configuration: `Makefile`, `CMakeLists.txt`, `config/lib60870_config.h`

Main architectural layers

1. Application-facing API layer
- The headers in `src/inc/api` define the public library entry points.
- This is the boundary consumed by application code in the examples and by external users of the library.
- The API exposes CS101 master/slave and CS104 client/server functionality, plus common IEC 60870 types and link-layer parameters.

2. Protocol core
- `src/iec60870` contains the implementation of IEC 60870 protocol behavior.
- It is split into:
  - `cs101`: application layer and serial link-layer-oriented behavior for IEC 60870-5-101.
  - `cs104`: TCP/IP-based IEC 60870-5-104 client/server behavior.
  - `link_layer`: link-layer frame handling and serial transceiver support for FT 1.2 style serial communications.
  - `frame.c` and `lib60870_common.c`: shared framing/common logic.
  - `apl/cpXXtime2a.c`: application-layer time encoding support.
- Internal headers in `src/inc/internal` define the private data structures used across these modules.

3. Transport and platform abstraction layer
- `src/hal` isolates platform-specific services so the protocol core can run on Linux, BSD, macOS, and Windows.
- The HAL provides:
  - sockets: `hal_socket.h` plus OS-specific implementations
  - serial ports: `hal_serial.h` plus OS-specific implementations
  - threading: `hal_thread.h`
  - time handling: `hal_time.h`
  - memory wrappers: `lib_memory.h`
  - TLS socket/cipher/config interfaces: `tls_socket.h`, `tls_ciphers.h`, `tls_config.h`
- This is the main portability boundary in the library.

4. TLS integration layer
- TLS support is implemented under `src/hal/tls`.
- There are two integration paths:
  - `mbedtls`
  - `mbedtls3`
- These are adapters around Mbed TLS, used when building with TLS support.
- TLS is relevant primarily for IEC 60870-5-104 secure communication / IEC 62351-3-related requirements.
- The `dependencies` folder and README indicate the third-party Mbed TLS source is expected externally and may be patched for compatibility.

Protocol-specific subsystem details

IEC 60870-5-101 path
- This is the serial-based stack.
- Data enters via the serial HAL and moves into the link layer.
- The link layer handles framing and transmission over serial.
- Above that, the CS101 application layer handles ASDUs, information objects, queues, and master/slave behavior.
- Key modules:
  - `cs101_asdu.c`
  - `cs101_information_objects.c`
  - `cs101_master.c`
  - `cs101_master_connection.c`
  - `cs101_slave.c`
  - `cs101_queue.c`
  - `cs101_bcr.c`
- The link-layer code in `src/iec60870/link_layer` is the bridge between serial transport and protocol payloads.

IEC 60870-5-104 path
- This is the TCP/IP-based stack.
- Data flows through the socket HAL into CS104 connection logic.
- The CS104 layer builds and parses protocol frames and coordinates client/server session state.
- Key modules:
  - `cs104_connection.c`
  - `cs104_frame.c`
  - `cs104_slave.c`
- CS104 has support for:
  - client/server operation
  - redundancy group support for server-side deployment
  - threadless and threaded usage patterns, as reflected by the examples

File service subsystem
- The file service in `src/file-service` supports CS101 slave and CS104 server scenarios.
- This is an auxiliary application-layer feature, not a separate transport.
- It is wired into server-side protocol handling so remote peers can read/write files through the IEC 60870 mechanisms.
- The README explicitly calls out file service support for CS101 slave and CS104 server.

Data flow overview

CS101 serial communication flow
- Application code uses the CS101 master or slave public API.
- The API enters protocol-core CS101 modules.
- ASDUs and information objects are encoded/decoded.
- The link layer frames data for serial transfer.
- The serial HAL sends/receives bytes through OS-specific serial drivers.
- Received data flows back up through the same layers for parsing and event handling.

CS104 TCP/IP communication flow
- Application code uses the CS104 client or server API.
- The protocol core creates and manages CS104 connection state.
- Frames are serialized/deserialized by CS104 frame logic.
- The socket HAL performs network I/O on the underlying OS.
- If TLS is enabled, the TLS layer sits between the socket transport and the CS104 session logic.
- On the server side, multiple peers and redundancy configurations are managed in the CS104 server module.

TLS-enabled flow
- For TLS builds, the transport path is wrapped by Mbed TLS adapters.
- The code uses certificate/key material, seen in the examples and tests.
- The security boundary here is between the protocol stack and the network transport, with TLS handling confidentiality and authentication at the transport layer.

Public vs private boundaries

- Public boundary: `src/inc/api`
  - Stable headers intended for application use
- Private boundary: `src/inc/internal`
  - Internal structs and helpers shared inside the library only
- Platform boundary: `src/hal`
  - OS-specific code hidden behind HAL interfaces
- External dependency boundary: Mbed TLS
  - Not vendored as a core part of the repo, but integrated when present

Examples as architectural usage models

The `examples` directory is a strong guide to how the library is intended to be composed:
- `cs101_master_balanced` and `cs101_master_unbalanced`
- `cs101_slave`
- `cs101_slave_files`
- `cs104_client`, `cs104_client_async`, `cs104_client_no_threads`
- `cs104_server`, `cs104_server_no_threads`
- `cs104_redundancy_server`
- `multi_client_server`
- `tls_client`, `tls_server`

These examples demonstrate the major operational modes:
- serial master/slave
- TCP client/server
- threaded and threadless operation
- file service
- TLS-secured endpoints
- redundancy handling

Tests and validation architecture
- `tests` contains unit/integration-style coverage using Unity.
- Certificate material and CRLs are included for TLS and authentication scenarios.
- The tests are important because they validate both protocol correctness and security-related behavior.
- This indicates the repository is not just a pure protocol library; it also includes security-sensitive interoperability checks.

Build and configuration architecture
- The project supports both Make and CMake.
- Configuration is partly compile-time:
  - `config/lib60870_config.h` controls footprint and feature inclusion.
- The build can exclude common/HAL components when integrating with related MZ Automation stacks.
- TLS support is optional and enabled by providing Mbed TLS and using the relevant build flags.
- The repo is designed to build on multiple operating systems, which is why the HAL and OS-specific implementations are explicit parts of the tree.

How to draw the architecture

A correct diagram should show:
- Application or example code at the top
- Public API as the boundary into the library
- Separate protocol branches for CS101 and CS104
- A shared protocol/common core beneath the APIs
- A HAL layer beneath that, split into serial, socket, thread, time, memory, and TLS adapters
- Optional TLS wrapping around network communication
- External Mbed TLS dependency outside the repo boundary
- File service as an auxiliary module attached to server-side CS101/CS104 flows
- Tests and examples as consumers of the public API, not part of the core runtime

In short, this is a layered protocol stack library: application API at the top, IEC 60870 protocol logic in the middle, OS-specific transport abstraction underneath, and optional TLS as a transport security extension.

Main entry points: [`lib60870-C/src/iec60870/cs101`](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/iec60870/cs101) (CS101 stack), [`lib60870-C/src/iec60870/cs104`](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/iec60870/cs104) (CS104 stack), [`lib60870-C/src/hal`](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal) (HAL), [`lib60870-C/src/inc/api`](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/inc/api) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Protocol stack"
  api["Public API<br/>headers"]
  internal["Internal API<br/>private headers"]
  common["Common code<br/>shared utilities"]
  core_common["Core common<br/>framing/common<br/>[lib60870_common.c]"]
  frame["Frame logic<br/>protocol framing<br/>[frame.c]"]
  apl_time["Time encode<br/>APL support<br/>[cpXXtime2a.c]"]
  cs101["CS101 stack<br/>serial protocol"]
  link_layer["Link layer<br/>serial link"]
  file_service["File service<br/>server feature"]
  cs104["CS104 stack<br/>tcp protocol"]
end

subgraph "Platform layer"
  hal["HAL<br/>portability layer"]
  serial_hal["Serial HAL<br/>os serial"]
  socket_hal["Socket HAL<br/>os network"]
  thread_hal["Thread HAL<br/>os threads"]
  time_hal["Time HAL<br/>os time"]
  memory_hal["Memory HAL<br/>memory wrapper"]
  tls_hal["TLS adapters<br/>tls integration"]
end

subgraph "Usage and validation"
  examples["Examples<br/>applications"]
  tests["Tests<br/>validation"]
end

mbedtls["Mbed TLS<br/>external dependency"]

api -->|"uses"| cs101
api -->|"uses"| cs104
api -->|"exposes"| file_service
cs101 -->|"shares"| internal
cs104 -->|"shares"| internal
cs101 -->|"depends on"| core_common
cs104 -->|"depends on"| core_common
cs101 -->|"depends on"| frame
cs104 -->|"depends on"| frame
cs101 -->|"uses"| apl_time
cs101 -->|"uses"| link_layer
link_layer -->|"runs on"| serial_hal
cs104 -->|"runs on"| socket_hal
cs104 -.->|"optional TLS"| tls_hal
tls_hal -->|"adapts"| mbedtls
hal -->|"contains"| serial_hal
hal -->|"contains"| socket_hal
hal -->|"contains"| thread_hal
hal -->|"contains"| time_hal
hal -->|"contains"| memory_hal
hal -->|"contains"| tls_hal
examples -->|"consumes"| api
tests -->|"consumes"| api
tests -.->|"validates"| tls_hal
file_service -->|"extends"| cs101
file_service -->|"extends"| cs104

click api "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/inc/api"
click internal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/inc/internal"
click common "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/common"
click core_common "https://github.com/mz-automation/lib60870/blob/master/lib60870-C/src/iec60870/lib60870_common.c"
click frame "https://github.com/mz-automation/lib60870/blob/master/lib60870-C/src/iec60870/frame.c"
click apl_time "https://github.com/mz-automation/lib60870/blob/master/lib60870-C/src/iec60870/apl/cpXXtime2a.c"
click cs101 "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/iec60870/cs101"
click link_layer "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/iec60870/link_layer"
click file_service "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/file-service"
click cs104 "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/iec60870/cs104"
click hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal"
click serial_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/serial"
click socket_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/socket"
click thread_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/thread"
click time_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/time"
click memory_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/memory"
click tls_hal "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/src/hal/tls"
click examples "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/examples"
click tests "https://github.com/mz-automation/lib60870/tree/master/lib60870-C/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class api,internal,common,core_common,frame,apl_time,cs101,link_layer,file_service,cs104 toneBlue
class hal,serial_hal,socket_hal,thread_hal,time_hal,memory_hal,tls_hal toneAmber
class examples,tests toneMint
class mbedtls toneNeutral
```

## Components

### Protocol stack

Public API, protocol core, and shared runtime layers.

- [Public API](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/inc/api): headers · Stable application-facing entry points for CS101 and CS104. · `lib60870-C/src/inc/api`
- [Internal API](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/inc/internal): private headers · Private shared types and helpers used within the library. · `lib60870-C/src/inc/internal`
- [Common code](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/common): shared utilities · Reusable utility code shared across protocol modules. · `lib60870-C/src/common`
- [Core common](https://github.com/mz-automation/lib60870/blob/HEAD/lib60870-C/src/iec60870/lib60870_common.c): framing/common · Shared framing and protocol support code. · `lib60870-C/src/iec60870/lib60870_common.c`
- [Frame logic](https://github.com/mz-automation/lib60870/blob/HEAD/lib60870-C/src/iec60870/frame.c): protocol framing · Low-level frame encode/decode support. · `lib60870-C/src/iec60870/frame.c`
- [Time encode](https://github.com/mz-automation/lib60870/blob/HEAD/lib60870-C/src/iec60870/apl/cpXXtime2a.c): APL support · Application-layer CP56Time2a time encoding support. · `lib60870-C/src/iec60870/apl/cpXXtime2a.c`
- [CS101 stack](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/iec60870/cs101): serial protocol · IEC 60870-5-101 master/slave behavior and ASDU handling. · `lib60870-C/src/iec60870/cs101`
- [Link layer](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/iec60870/link_layer): serial link · Serial link-layer framing and FT 1.2 transceiver support. · `lib60870-C/src/iec60870/link_layer`
- [File service](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/file-service): server feature · Auxiliary file transfer support for CS101 slave and CS104 server. · `lib60870-C/src/file-service`
- [CS104 stack](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/iec60870/cs104): tcp protocol · IEC 60870-5-104 client/server connection and frame logic. · `lib60870-C/src/iec60870/cs104`

### Platform layer

OS-specific transport, threading, timing, and TLS adapters.

- [HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal): portability layer · Platform abstraction layer for sockets, serial, threading, time, memory, and TLS. · `lib60870-C/src/hal`
- [Serial HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/serial): os serial · Platform-specific serial port implementations. · `lib60870-C/src/hal/serial`
- [Socket HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/socket): os network · Platform-specific socket implementations. · `lib60870-C/src/hal/socket`
- [Thread HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/thread): os threads · Platform-specific threading implementations. · `lib60870-C/src/hal/thread`
- [Time HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/time): os time · Platform-specific time handling implementations. · `lib60870-C/src/hal/time`
- [Memory HAL](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/memory): memory wrapper · Portable memory allocation wrappers. · `lib60870-C/src/hal/memory`
- [TLS adapters](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/src/hal/tls): tls integration · Mbed TLS-based socket/security adapters for secure builds. · `lib60870-C/src/hal/tls`

### Usage and validation

Examples and tests that exercise the public library surface.

- [Examples](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/examples): applications · Reference programs showing CS101, CS104, TLS, and redundancy usage. · `lib60870-C/examples`
- [Tests](https://github.com/mz-automation/lib60870/tree/HEAD/lib60870-C/tests): validation · Unity-based tests and certificate fixtures validating protocol and TLS behavior. · `lib60870-C/tests`

### Other components

- **Mbed TLS**: external dependency · External TLS library integrated through HAL adapters.

## Connections

- Public API → CS101 stack: uses · Public CS101 API enters the serial protocol stack.
- Public API → CS104 stack: uses · Public CS104 API enters the TCP protocol stack.
- Public API → File service: exposes · Public API includes file service support for server-side scenarios.
- CS101 stack → Internal API: shares · CS101 implementation uses private internal types and helpers.
- CS104 stack → Internal API: shares · CS104 implementation uses private internal types and helpers.
- CS101 stack → Core common: depends on · CS101 reuses shared protocol framing and common logic.
- CS104 stack → Core common: depends on · CS104 reuses shared protocol framing and common logic.
- CS101 stack → Frame logic: depends on · CS101 uses low-level frame handling.
- CS104 stack → Frame logic: depends on · CS104 uses low-level frame handling.
- CS101 stack → Time encode: uses · CS101 uses application-layer time encoding support.
- CS101 stack → Link layer: uses · CS101 serial flows pass through the link layer.
- Link layer → Serial HAL: runs on · Link-layer serial traffic is carried by the serial HAL.
- CS104 stack → Socket HAL: runs on · CS104 network traffic is carried by the socket HAL.
- CS104 stack → TLS adapters: optional TLS · Secure CS104 builds wrap network transport with TLS adapters.
- TLS adapters → Mbed TLS: adapts · TLS adapters wrap the external Mbed TLS implementation.
- HAL → Serial HAL: contains · HAL includes serial platform bindings.
- HAL → Socket HAL: contains · HAL includes socket platform bindings.
- HAL → Thread HAL: contains · HAL includes thread platform bindings.
- HAL → Time HAL: contains · HAL includes time platform bindings.
- HAL → Memory HAL: contains · HAL includes memory wrappers.
- HAL → TLS adapters: contains · HAL includes TLS integration adapters.
- Examples → Public API: consumes · Examples are application-level consumers of the public API.
- Tests → Public API: consumes · Tests exercise the public API surface.
- Tests → TLS adapters: validates · Tests cover TLS and certificate-related behavior.
- File service → CS101 stack: extends · File service augments CS101 slave behavior.
- File service → CS104 stack: extends · File service augments CS104 server behavior.
