c104 2.0.0

A Python module to simulate SCADA and RTU communication over protocol 60870-5-104 to research ICT behavior in power grids.

iec104-python

Table of contents

1. Introduction
2. Licensing
3. System requirements
4. Installation
5. Wiki
6. Contribution

---

Introduction

This software provides an object-oriented high-level python module to simulate scada systems and remote terminal units communicating via 60870-5-104 protocol.

The python module c104 combines the use of lib60870-C with state structures and python callback handlers.

Example remote terminal unit

import c104

# server and station preparation
server = c104.Server(ip="0.0.0.0", port=2404)

# add local station and points
station = server.add_station(common_address=47)
measurement_point = station.add_point(io_address=11, type=c104.Type.M_ME_NC_1, report_ms=1000)
command_point = station.add_point(io_address=12, type=c104.Type.C_RC_TA_1)

server.start()

Example scada unit

import c104

client = c104.Client(tick_rate_ms=1000, command_timeout_ms=5000)

# add RTU with station and points
connection = client.add_connection(ip="127.0.0.1", port=2404, init=c104.Init.INTERROGATION)
station = connection.add_station(common_address=47)
measurement_point = station.add_point(io_address=11, type=c104.Type.M_ME_NC_1, report_ms=1000)
command_point = station.add_point(io_address=12, type=c104.Type.C_RC_TA_1)

client.start()

See examples folder for more detailed examples.

Licensing

This software is licensed under the GPLv3 (https://www.gnu.org/licenses/gpl-3.0.en.html).

See LICENSE file for the complete license text.

Dependencies

lib60870-C

This project is build on top of lib60870-C v2 from MZ Automation GmbH, which is licensed under GPLv3.

The library is used for 60870-5-104 protocol based communication.

» Source code

» Documentation

mbedtls

This project is build on top of mbedtls from the Mbed TLS Contributors, which is licensed under Apache-2.0.

The library is used to add transport layer security to the 60870-5-104 protocol based communication.

» Source code

» Documentation

pybind11

This project is build on top of pybind11 from Wenzel Jakob, which is licensed under a BSD-style license.

The library is used to wrap c++ code into a python module and allow seamless operability between python and c++.

» Source code

» Documentation

catch2

This project is build on top of catch2 from the Catch2 Authors, which is licensed under BSL-1.0.

The library is used as testing framework for test-automation.

» Source code

» Documentation

System requirements

Operating systems

• Manylinux (x86_64): YES
• Manylinux (aarch64): YES
• Raspbian (armv7l): YES
• Windows (x64): YES

Python versions

• python >= 3.7, < 3.13

Installation

Please adjust the version number to the latest version or use a specific version according to your needs.

Install from pypi.org

python3 -m pip install c104

Install from git with tag

python3 -m pip install c104@git+https://github.com/fraunhofer-fit-dien/iec104-python.git

You need the build requirements, listed under "How to build".

Documentation

Read more about the Classes and their Properties in our read the docs documentation.

Contribution

How to contribute

1. Add feature requests and report bugs using GitHub's issues

2. Create pull requests

How to build (linux)

1. Install dependencies

   sudo apt-get install build-essential python3-pip python3-dev python3-dbg
   python3 -m pip install --upgrade pip
   

2. Clone repository

   git clone --depth=1 --branch=main https://github.com/Fraunhofer-FIT-DIEN/iec104-python.git
   cd iec104-python
   git submodule update --init
   

3. Build wheel

   python3 -m pip wheel .
   

How to build for multiple python versions (linux with docker)

1. Build wheels via docker (linux)

   /bin/bash ./bin/linux-build.sh
   

How to analyze performance (linux)

1. Install dependencies

   sudo apt-get install google-perftools valgrind
   sudo pip3 install yep
   

2. Copy pprof binary

   cd /usr/bin
   sudo wget https://raw.githubusercontent.com/gperftools/gperftools/master/src/pprof
   sudo chmod +x pprof
   

3. Execute profiler script

   ./bin/profiler.sh
   

How to build (windows)

1. Install dependencies

   • Python 3
   • Buildtools für Visual Studio 2022 (Scroll down » All Downloads » Tools for Visual Studio 2022)

2. Option 1: Build as wheel

   python3 -m pip wheel .
   

3. Option 2: Build pyd via Powershell

   cmake -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 17 2022" -B cmake-build-release -A x64 -DPython_EXECUTABLE=C:\PATH_TO_PYTHON\python.exe
   &"C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe" /m /p:Platform=x64 /p:Configuration=Release c104.sln /t:Rebuild
   

   Set a valid PATH_TO_PYTHON, if you have multiple python versions.
   Set a valid path to MSBuild.exe unless msbuild is already in path.

Generate documentation

1. Build c104 module

2. Install dependencies

   • python3 -m pip install -r ./docs/requirements.txt
   • doxygen
   • graphviz

3. Build doxygen xml

   doxygen Doxyfile
   

4. Build sphinx html

   python3 bin/build-docs.py
   

Change log

Track all changes in our CHANGELOG documentation.