netX programming examples
Made for netPI RTE 3, the Open Edge Connectivity Ecosystem with Real-Time Ethernet
netX sample applications for PROFINET, EtherNet/IP and EtherCAT
Additionally the image provides netX programming examples in source code (and as precompiled executables) for
- PROFINET IO-device
- EtherNet/IP adapter
- EtherCAT slave
For enabling remote login to the container across SSH the container's SSH port 22 needs to be exposed to the host.
To grant access to the netX from inside the container the
/dev/spidev0.0 host device needs to be added to the container.
STEP 1. Open netPI's landing page under
https://<netpi's ip address>.
STEP 2. Click the Docker tile to open the Portainer.io Docker management user interface.
STEP 3. Enter the following parameters under Containers > Add Container
Host "22" (any unused one) -> Container "22"
Restart policy" :
Runtime > Devices > add device:
Host "/dev/spidev0.0" -> Container "/dev/spidev0.0"
STEP 4. Press the button Actions > Start container
Pulling the image from Docker Hub may take up to 5 minutes.
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
Files and folders
The login directs you to the pi user home directory /home/pi with following structure
/home/pi/ | +--/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
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
The cifX API function library needed for linking will be installed into folder
Basic include files needed for the compilation process will be installed into folder
netX firmware installation
To install a firmware package move to the folder
firmwares and call
dpkg -i netx-docker-pi-pns-184.108.40.206.debfor PROFINET IO device firmware or
dpkg -i netx-docker-pi-eis-220.127.116.11.debfor EtherNet/IP adapter firmware or
dpkg -i netx-docker-pi-ecs-18.104.22.168.debfor EtherCAT slave firmware
Any firmware package extracts its firmware into the folder
The firmware will be loaded by the driver into netX network controller the first time the driver is accessed using the
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_simpleConfigas PROFINET IO device demo
EIS_simpleConfigas EtherNet/IP adapter demo
ECS_simpleConfigas EtherCAT slave 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_simpleConfigfor the PROFINET IO device example
sudo ./EIS_simpleConfigfor the EtherNet/IP adapter example
sudo ./ECS_simpleConfigfor the EtherCAT slave 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
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.
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.pdffor PROFINET IO device
EtherNetIP_Adapter_Protocol_API_19_EN.pdffor EtherNet/IP adapter
EtherCAT Slave V4 Protocol API 09 EN.pdffor EtherCAT slave
located in the
- hilscher/netPI-net-programming-examples:latest - non-versioned latest development output of the master branch. Can run on any netPI RTE 3 system software version.
View the license information for the software in the Github 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.
Hilscher Gesellschaft fuer Systemautomation mbH www.hilscher.com