How mz-automation/lib60870 works
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: cs101 CS101 stack · cs104 CS104 stack · hal HAL · api Public API
Components 20
Protocol stack
Public API, protocol core, and shared runtime layers.
- Public API · Stable application-facing entry points for CS101 and CS104.
lib60870-C/src/inc/api - Internal API · Private shared types and helpers used within the library.
lib60870-C/src/inc/internal - Common code · Reusable utility code shared across protocol modules.
lib60870-C/src/common - Core common · Shared framing and protocol support code.
lib60870-C/src/iec60870/lib60870_common.c - Frame logic · Low-level frame encode/decode support.
lib60870-C/src/iec60870/frame.c - Time encode · Application-layer CP56Time2a time encoding support.
lib60870-C/src/iec60870/apl/cpXXtime2a.c - CS101 stack · IEC 60870-5-101 master/slave behavior and ASDU handling.
lib60870-C/src/iec60870/cs101 - Link layer · Serial link-layer framing and FT 1.2 transceiver support.
lib60870-C/src/iec60870/link_layer - File service · Auxiliary file transfer support for CS101 slave and CS104 server.
lib60870-C/src/file-service - CS104 stack · 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 · Platform abstraction layer for sockets, serial, threading, time, memory, and TLS.
lib60870-C/src/hal - Serial HAL · Platform-specific serial port implementations.
lib60870-C/src/hal/serial - Socket HAL · Platform-specific socket implementations.
lib60870-C/src/hal/socket - Thread HAL · Platform-specific threading implementations.
lib60870-C/src/hal/thread - Time HAL · Platform-specific time handling implementations.
lib60870-C/src/hal/time - Memory HAL · Portable memory allocation wrappers.
lib60870-C/src/hal/memory - TLS adapters · 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.
Other components
- Mbed TLS · External TLS library integrated through HAL adapters.
Connections 26
- 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.