Skip to content
Sources of Dockerfile generated Docker image "Raspbian + netX programming examples" for Hilscher’s netPI
Branch: master
Clone or download

netX programming examples

Made for netPI RTE 3, the Raspberry Pi 3B Architecture based industrial suited Open Edge Connectivity Ecosystem

netX programming example applications for PROFINET, EtherNet/IP, EtherCAT, POWERLINK and Modbus/TCP

Base of this image builds debian with enabled SSH and created user 'pi'.

Additionally the image provides netX programming examples in source code (and as precompiled executables) for

  • PROFINET IO-device
  • EtherNet/IP adapter
  • EtherCAT slave
  • POWERLINK slave
  • Modbus/TCP server

Container prerequisites

Port mapping

For enabling remote login to the container across SSH the container's SSH port 22 needs to be exposed to the host.

Host device

To grant access to the netX from inside the container the /dev/spidev0.0 host device needs to be added to the container.

Getting started

STEP 1. Open netPI's landing page under https://<netpi's ip address>.

STEP 2. Click the Docker tile to open the Docker management user interface.

STEP 3. Enter the following parameters under Containers > Add Container

  • Image: hilschernetpi/netpi-netx-programming-examples

  • Port mapping: Host "22" (any unused one) -> Container "22"

  • Restart policy" : always

  • Runtime > Devices > add device: Host "/dev/spidev0.0" -> Container "/dev/spidev0.0"

STEP 4. Press the button Actions > Start/Deploy container

Pulling the image may take a while (5-10mins). Sometimes it takes so long that a time out is indicated. In this case repeat the Actions > Start/Deploy container action.


The container starts the SSH service automatically.

Login to it with an SSH client such as putty using netPI's IP address at your mapped port. Use the credentials pi as user and raspberry as password when asked and you are logged in as non-root user pi.

Files and folders

The login directs you to the pi user home directory /home/pi with following structure

       +--/devicedescriptions   - device description files such as EDS, GSDML, ESI needed for master engineering
       +--/driver               - netX driver installation package
       +--/firmwares            - netX firmware installation packages
       +--/includes             - protocol specific include files for compilation
       +--/manuals              - common cifX API manual and protocol specific API manuals
       +--/objs                 - folder where the object files of the compilation process are stored to
       +--/sources              - protocol specific source codes of the demos
       | Makefile               - Makefile to compile all example applications using 'make' command
       | PNS_simpleConfig       - precompiled and executable PROFINET IO device example 
       | EIS_simpleConfig       - precompiled and executable EtherNet/IP adapter example
       | ECS_simpleConfig       - precompiled and executable EtherCAT slave example
       | PLS_simpleConfig       - precompiled and executable POWERLINK slave example
       | OMB_simpleConfig       - precompiled and executable Modbus/TCP server example
netX driver installation

To install the netX SPI driver package move to the driver folder and call

dpkg -i netx-docker-pi-drv-1.1.3.deb

The driver will be installed into the folder /opt/cifx.

The cifX API function library needed for linking will be installed into folder /usr/lib.

Basic include files needed for the compilation process will be installed into folder /usr/include.

netX firmware installation

To install a firmware package move to the folder firmwares and call

  • dpkg -i netx-docker-pi-pns- for PROFINET IO device firmware or
  • dpkg -i netx-docker-pi-eis- for EtherNet/IP adapter firmware or
  • dpkg -i netx-docker-pi-ecs- for EtherCAT slave firmware
  • dpkg -i netx-docker-pi-pls- for POWERLINK slave firmware
  • dpkg -i netx-docker-pi-omb- for Modbus/TCP server firmware

Any firmware package extracts its firmware into the folder /opt/cifx/deviceconfig/FW/channel0.

The firmware will be loaded by the driver into netX network controller the first time the driver is accessed using the cifXDriverInit() command.

There can be only one installed netX firmware package at a time. An existing package will be automatically uninstalled during the installation procedure.

Compiling the programming examples

To compile the programming examples simply call make in the pi home directory. The command will locate the Makefile which initiates the compilation process.

The following executables will be compiled

  • PNS_simpleConfig as PROFINET IO device demo
  • EIS_simpleConfig as EtherNet/IP adapter demo
  • ECS_simpleConfig as EtherCAT slave demo
  • PLS_simpleConfig as POWERLINK slave demo
  • OMB_simpleConfig as Modbus/TCP server demo

You may be faced with the following warning during compilation process

make: warning: Clock skew detected. Your build may be incomplete.

There is a discrepancy between netPI's system clock and the time the executeables/object files have been generated. Call make clean and remove the executeable. Then start the compilation process again. Make also sure you have set netPI's system clock correctly.

Changing the default IO size of 10 bytes input and 4 bytes output

All three examples configure a process data input length of 10 bytes and an output length 4 bytes. The provided electronic data sheets for the master/controller engineering software match exactly to this example size.

If a different IO length is required you have to adjust the length in the file /includes/App.h in the structures APP_INPUT_DATA_T and APP_OUTPUT_DATA_T accordingly. Please take into account that there is a limit of maximum allowed IO length. This limit can be found in each of the three programming manuals provided in the folder ./manuals.

Afterwards recompile and start the new examples to become effective. Make sure you also modify the device description files and reload them into the master/contoller engineering software to sychronize the project with the new physical setup.

Starting the executables

To start the compiled examples call the following executeables in the pi home directory

  • sudo ./PNS_simpleConfig for the PROFINET IO device example
  • sudo ./EIS_simpleConfig for the EtherNet/IP adapter example
  • sudo ./ECS_simpleConfig for the EtherCAT slave example
  • sudo ./PLS_simpleConfig for the POWERLINK slave example
  • sudo ./OMB_simpleConfig for the Modbus/TCP server example

Each example checks if its corresponding firmware package has been installed properly and loaded into netX, else it will install and load it automatically.

Electronic Data Sheets

Any master/controller engineering software needs device descriptions, socalled electronic data sheets, of all IO devices it shall communicate to. They inform about device parameters such as vendor-ID, product-ID, name, IO length etc. For all three examples the devices description files can be found in the github project under /electronic-data-sheets.

By default the provided files are preconfigured to an IO length of 10 bytes input and 4 bytes output. In case you modified an example to configure a different IO length you have to modify the electronic data sheet accordingly and reconfigure your master/controller with it.

Protocol specifics

In case of PROFINET please keep in mind that a virgin netX needs a PROFINET device name setup over the network as described here. Use your master engineering software to assign a corresponding name ("netx51repns" which is default in the electronic data sheet).

Linking the cifX library to applications

To link the cifX driver library to own applications just add the option -lcifx to your GCC compilation command.

The cifX API funtions reference (netX driver API)

The cifX driver's function application interfaace (API) is described in the manual


located in the manuals folder. These call functions provide you a simple interface between your application and netX network controller.

The protocol specific APIs (PROFINET, EtherNet/IP ... APIs)

A netX firmware has a common part that is behaving the same for all firmwares and a protocol dependent specific part. Particularly the configuration varies from protocol to protocol and shows different characteristics.

The protocol specific dependencies are described in the manuals

  • PROFINET_IO-Device_V3.12_Protocol_API_17_EN.pdf for PROFINET IO device
  • EtherNetIP_Adapter_Protocol_API_19_EN.pdf for EtherNet/IP adapter
  • EtherCAT Slave V4 Protocol API 09 EN.pdf for EtherCAT slave
  • POWERLINK Slave V4 Protocol API 09 EN.pdf for POWERLINK slave
  • OpenModbusTCP Protocol API 10 EN.pdf for Modbus TCP server

located in the manuals folder.

Automated build

The project complies with the scripting based Dockerfile method to build the image output file. Using this method is a precondition for an automated web based build process on DockerHub platform.

DockerHub web platform is x86 CPU based, but an ARM CPU coded output file is needed for Raspberry systems. This is why the Dockerfile includes the balena steps.


View the license information for the software in the project. As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained). As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

N|Solid Hilscher Gesellschaft fuer Systemautomation mbH

You can’t perform that action at this time.