Skip to content

Commit

Permalink
configureable SSH port added
Browse files Browse the repository at this point in the history
  • Loading branch information
@hilschernetpi
hilschernetpi committed May 7, 2020
1 parent 7a2d395 commit 909dfb1
Show file tree
Hide file tree
Showing 3 changed files with 91 additions and 39 deletions.
2 changes: 1 addition & 1 deletion Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ LABEL org.label-schema.build-date=$BUILD_DATE \
org.label-schema.vcs-ref=$VCS_REF

#version
ENV HILSCHERNETPI_CODESYS_BASIS_VERSION 1.3.3
ENV HILSCHERNETPI_CODESYS_BASIS_VERSION 1.3.4

#execute all commands as root
USER root
Expand Down
118 changes: 81 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,38 @@
## CODESYS Control

[![](https://images.microbadger.com/badges/image/hilschernetpi/netpi-codesys-basis.svg)](https://microbadger.com/images/hilschernetpi/netpi-codesys-basis "CODESYS Control")
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![](https://images.microbadger.com/badges/commit/hilschernetpi/netpi-codesys-basis.svg)](https://microbadger.com/images/hilschernetpi/netpi-codesys-basis "CODESYS Control")
[![Docker Registry](https://img.shields.io/docker/pulls/hilschernetpi/netpi-codesys-basis.svg)](https://registry.hub.docker.com/r/hilschernetpi/netpi-codesys-basis/) 
[![Image last updated](https://img.shields.io/badge/dynamic/json.svg?url=https://api.microbadger.com/v1/images/hilschernetpi/netpi-codesys-basis&label=Image%20last%20updated&query=$.LastUpdated&colorB=007ec6)](http://microbadger.com/images/hilschernetpi/netpi-codesys-basis "Image last updated") 

Made for [netPI](https://www.netiot.com/netpi/), the Raspberry Pi 3B Architecture based industrial suited Open Edge Connectivity Ecosystem

### Secured netPI Docker

netPI features a restricted Docker protecting the system software's integrity by maximum. The restrictions are

* privileged mode is not automatically adding all host devices `/dev/` to a container
* volume bind mounts to rootfs is not supported
* the devices `/dev`,`/dev/mem`,`/dev/sd*`,`/dev/dm*`,`/dev/mapper`,`/dev/mmcblk*` cannot be added to a container
Made for Raspberry Pi 3B architecture based devices and compatibles

### Container features

The image provided hereunder deploys a container with a basic setup of Linux tools, utilities and default user needed for a flawless installation of the CODESYS Control for Raspberry Pi (SL and MC SL) packages with the Windows® based [CODESYS Development System V3](https://store.codesys.com/codesys.html)(free).
The image provided hereunder deploys a container with a basic setup of Linux tools, utilities and default user `pi` as needed for a flawless installation of the CODESYS Control for Raspberry Pi (SL and MC SL) packages with the Windows® based [CODESYS Development System V3](https://store.codesys.com/codesys.html)(free).

Base of this image builds [debian](https://www.balena.io/docs/reference/base-images/base-images/) with enabled [SSH](https://en.wikipedia.org/wiki/Secure_Shell) and created default user 'pi'(sudo). This setup is equivalent to a stripped down Raspbian OS with least capabilities.

Once the container is deployed it needs an upgrade with the following packages you can download from the CODESYS store

* [CODESYS Control for Raspberry Pi SL](https://store.codesys.com/codesys-control-for-raspberry-pi-sl.html) or [CODESYS Control for Raspberry Pi MC SL](https://store.codesys.com/codesys-control-for-raspberry-pi-mc-sl.html)
* [CODESYS Edge Gateway](https://store.codesys.com/codesys-edge-gateway.html) (needed since version V3.5.15.x)
* [CODESYS Edge Gateway](https://store.codesys.com/codesys-edge-gateway.html) (needed at later versions of CODESYS runtime)

### Container hosts

The container has been successfully tested on the following Docker hosts

* netPI, model RTE 3, product name NIOT-E-NPI3-51-EN-RE
* netPI, model CORE 3, product name NIOT-E-NPI3-EN
* netIOT Connect, product name NIOT-E-TPI51-EN-RE
* netFIELD Connect, product name NIOT-E-TPI51-EN-RE/NFLD
* Raspberry Pi, model 3B

netPI devices specifically feature a restricted Docker protecting the Docker host system software's integrity by maximum. The restrictions are

* privileged mode is not automatically adding all host devices `/dev/` to a container
* volume bind mounts to rootfs is not supported
* the devices `/dev`,`/dev/mem`,`/dev/sd*`,`/dev/dm*`,`/dev/mapper`,`/dev/mmcblk*` cannot be added to a container

### Container licensing

Expand All @@ -34,13 +42,19 @@ A license purchase follows an email with a ticket number (e.g A78HY-TBVMD-8SVC7-

It is possible to deploy a license to either a CODESYS Runtime Key (USB dongle) or to a software container.

**IMPORTANT NOTE**: A software container needs special care since the license is stored on the device itself in the Docker container. If this container is lost or destroyed by any reason or is deleted your license copy is **gone forever!!!**. This is why a license backup is obligatory in this case.
**IMPORTANT NOTE**: A software container needs special care cause the license is stored in container. If this container is lost or destroyed by any reason or is deleted your license copy is **gone forever!!!**. This is why a license backup is obligatory in this case.

To backup the license file "3SLicenseInfo.tar" follow this [FAQ information](https://forum.codesys.com/viewtopic.php?f=22&t=5641&start=15#p10689).
To restore the license file "3SLicenseInfo.tar" follow this [FAQ information](https://forum.codesys.com/viewtopic.php?f=22&t=5641&p=10690#p10690).

### Container setup

#### Environment variable (optional)

The container binds the SSH server port to `22` by default.

For an alternative port use the variable **SSHPORT** with the desired port number as value.

#### Host network

The container needs to run in `host` network mode.
Expand All @@ -53,22 +67,22 @@ The privileged mode option needs to be activated to lift the standard Docker enf

#### Host devices

The CODESYS runtime perfoms a license versus serial number check across the device VideoCore GPU when started. To grant access to the GPU chip the `/dev/vcio` host device is mandatory to add to the container.
The CODESYS runtime perfoms a license check across the Docker host VideoCore GPU when started. To grant access to the GPU chip the `/dev/vcio` Docker host device is mandatory to add to the container.

In case a CODESYS Runtime Key Dongle is used for licensing the host device `/dev/hidraw0` needs to be added to the container.
In case an external USB CODESYS Runtime Key Dongle is used for licensing the Docker host device `/dev/hidraw0` needs to be added to the container. The device `/dev/hidraw0` is only available on the Docker host if such a USB dongle physically has been connected to one of the USB sockets.

##### Additional Ethernet LAN Interface on netPI RTE 3 (optional)
##### Additional Ethernet ports on netPI RTE 3 or netFIELD/netIOT connect (optional)

The container configures the two RJ45 Industrial Ethernet ports (RTE) as standard LAN interface (single MAC address, but switched) named `cifx0` automatically if the following devices found added to the container
The container configures the double RJ45 socket driven by netX controller to operate as standard LAN interface (single MAC address, switched always) with a device name `cifx0` if the following devices found added to the container

* host device `/dev/spidev0.0` granting access to the network controller netX driving the RTE ports
* host device `/dev/net/tun` granting access to network interface registering logic
* Docker host device `/dev/spidev0.0` granting access to the network controller netX driving the RTE ports
* Docker host device `/dev/net/tun` granting access to network interface registering logic

Since the container runs in "Host network" mode the container host treats the `cifx0` as a standard LAN interface. This is why the `cifx0` IP settings are configured in the netPI's network/LAN settings dialog (like "eth0" interface). Any change on the IP settings needs a container restart to accept the new IP parameters.
Cause the container runs in `host` network mode the interface is instantiated on the Docker host as a standard LAN interface. This is why the `cifx0` IP settings have to be configured in the Docker host's web UI network setup dialog (as "eth0" interface) and not in the container. Any change on the IP settings needs a container restart to accept the new IP parameters.

netPI RTE 3's Industrial network controller netX was designed to support all kind of Industrial Networks as device in the first place. Its performance is high when exchanging IO data from and to a master PLC and any Host application via IO buffers periodically. The controller was not designed to support high performance message oriented exchange of data as used with Ethernet communications. This is why the provided `cifx0` interface is a low to mid-range performer but is still a good compromise to add another Ethernet interface to netPI RTE 3 on demand.
The netX controller was designed to support all kind of Industrial Networks as device in the first place. Its performance is high when exchanging IO data with a network master across IO buffers. It was not designed to support high performance message oriented exchange of data as used in Ethernet communications. This is why the provided `cifx0` interface is a low to mid-range performer but is still a good compromise if another Ethernet interface is needed.

Measurements have shown that around 700 to 800KByte/s throughput can be reached across `cifx0` only whereas with netPI's primary Ethernet port `eth0` 10MByte/s can be reached. Reasons are :
Measurements have shown that around 700 to 800KByte/s throughput can be reached across `cifx0` only whereas with netPI's primary Ethernet port `eth0` 10MByte/s can be reached. The reasons are:

* 25MHz SPI clock frequency between netX and Raspberry Pi CPU only
* User space driver instead of a kernel driver
Expand All @@ -81,17 +95,22 @@ The `cifx0` LAN interface DOES NOT support Ethernet package reception of type mu

### Container deployment

STEP 1. Open netPI's website in your browser (https).
Pulling the image may take 10 minutes.

#### netPI example

STEP 1. Open netPI's web UI in your browser (https).

STEP 2. Click the Docker tile to open the [Portainer.io](http://portainer.io/) Docker management user interface.

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

Parameter | Value | Remark
:---------|:------ |:------
*Image* | **hilschernetpi/netpi-codesys-basis**
*Image* | **hilschernetpi/netpi-codesys-basis** | a :tag may be added as well
*Network > Network* | **host** |
*Restart policy* | **always** |
*Runtime > Env* | *name* **SSHPORT** -> *value* **any number value** | optional for different SSH port
*Runtime > Devices > +add device* | *Host path* **/dev/vcio** -> *Container path* **/dev/vcio** |
*Runtime > Devices > +add device* | *Host path* **/dev/hidraw0** -> *Container path* **/dev/hidraw0** | for CODESYS Runtime Key Dongle
*Runtime > Devices > +add device* | *Host path* **/dev/spidev0.0** -> *Container path* **/dev/spidev0.0** | for `cifx0` LAN
Expand All @@ -100,37 +119,62 @@ Parameter | Value | Remark

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

Pulling the image may take a while (5-10mins). Sometimes it may take too long and a time out is indicated. In this case repeat STEP 4.
#### Docker command line example

`docker run -d --privileged --network=host --restart=always -e SSHPORT=22 --device=/dev/vcio0:/dev/vcio --device=/dev/hidraw0:/dev/hidraw0 --device=/dev/spidev0.0:/dev/spidev0.0 --device=/dev/net/tun:/dev/net-tun -p 22:22/tcp hilschernetpi/netpi-codesys-basis`

#### Docker compose example

A `docker-compose.yml` file could look like this

version: "2"

services:
nodered:
image: hilschernetpi/netpi-codesys-basis
restart: always
privileged: true
network_mode: host
ports:
- 22:22
devices:
- "/dev/vcio:/dev/vcio"
- "/dev/hidraw0:/dev/hidraw0"
- "/dev/spidev0.0:/dev/spidev0.0"
- "/dev/net/tun:/dev/net/tun"
environment:
- SSHPORT=22

### Container access

The container starts the SSH server automatically when deployed.

For an SSH terminal session as used by the CODESYS development system to communicate with a target hardware use the Docker host IP address with the port number `22` or the configured **SSHPORT**.

A fresh container can immediately be upgraded with your downloaded packages from the CODESYS store. Here is how to proceed

STEP 1: Upgrade your CODESYS development system first with support for Raspberry Pi/Linux compatible platforms using the function `Tools->Package Manager->Install`. Choose your packages "CODESYS Control for Raspberry Pi 3.5.xx.xx.package" and "CODESYS Edge Gateway for Linux 3.5.x.x.package" and click `Install`.
STEP 1: Upgrade your Windows CODESYS development system first with support for Raspberry Pi/Linux compatible platforms using the function `Tools->Package Manager->Install`. Choose your packages "CODESYS Control for Raspberry Pi 3.5.xx.xx.package" and "CODESYS Edge Gateway for Linux 3.5.x.x.package" and click `Install`.

STEP 2: Restart the development system to activate the installed packages extending the top menu bar `Tools` by two new functions.

STEP 3: Use the new function `Tools->Update Raspberry Pi` to deploy your "CODESYS Control for Raspberry Pi" package to the container. Enter the user `pi` and the password `raspberry` as `Login credentials`. Enter your netPI's IP address in `Select target->IP address` , choose the version under `Package` you want to install and press `Install`. The installation may take up to 1 minute. Choose `Standard` or `Multicore` runtime mode during installation.
STEP 3: Use the new function `Tools->Update Raspberry Pi` to deploy your "CODESYS Control for Raspberry Pi" package to the container. Enter the user `pi` and the password `raspberry` as `Login credentials`. Enter your Docker host IP address in `Select target->IP address` with the :port as extension , choose the version under `Package` you want to install and press `Install`. The installation may take up to 1 minute. Choose `Standard` or `Multicore` runtime mode during installation.

STEP 4: Use the new function `Tools->Update Edge Gateway` to deploy your "CODESYS Edge Gateway for Linux" package to the container. Enter the user `pi` and the password `raspberry` as `Login credentials`. Enter your netPI's IP address in `Select target->IP address` , choose the version `V3.5.x.x.(armhf)` under `Package` you want to install and press `Install`. The installation may take up to 1 minute. The container is now well prepared and ready to receive a project.
STEP 4: Use the new function `Tools->Update Edge Gateway` to deploy your "CODESYS Edge Gateway for Linux" package to the container. Enter the user `pi` and the password `raspberry` as `Login credentials`. Enter your Dcoker host IP address in `Select target->IP address` with the :port as extension, choose the version `V3.5.x.x.(armhf)` under `Package` you want to install and press `Install`. The installation may take up to 1 minute. The container is now well prepared and ready to receive a project.

STEP 5: Create a CODESYS new project. Choose `Standard Project` and as `Device` "CODESYS Control for Raspberry Pi xx" and then `ok`. After project creation double click the topmost `Device(CODESYS Control for Raspberry Pi)` in the project tree.

STEP 6: Setup a communication from the CODESYS development system to the container Edge Gateway. Use the function `Gateway->Add New Gateway` in the dialog `Device`. As gateway `IP-address` use the netPI IP address at port 1217 and click `ok`. Use the option `Device->Scan Network...` option and click the found device found. e.g. NTB827EBEA02D0 [0000.0539] and `ok`.
STEP 6: Setup a communication from the CODESYS development system to the container Edge Gateway. Use the function `Gateway->Add New Gateway` in the dialog `Device`. As gateway `IP-address` use the Docker host IP address at port 1217 and click `ok`. Use the option `Device->Scan Network...` option and click the found device found. e.g. NTB827EBEA02D0 [0000.0539] and `ok`.

### Container test

The container has been successfully tested against the [CODESYS Development System V3](https://store.codesys.com/codesys.html) in the version V3.5.15.10 and the [CODESYS Control for Raspberry Pi SL](https://store.codesys.com/codesys-control-for-raspberry-pi-sl.html) and [CODESYS Control for Raspberry Pi MC SL](https://store.codesys.com/codesys-control-for-raspberry-pi-mc-sl.html) both in the version V3.5.15.10

### Container Youtube

HINT: The software version shown in the video may differ from yours and screens/options/windows may look different meanwhile. The video also doesn't show the mapping of the `/dev/vcio` and `/dev/spidev0.0` host devices when the container is deployed and no installation of the Edge Gateway package.

[![Tutorial](https://img.youtube.com/vi/cXIHu3-4-eg/0.jpg)](https://youtu.be/cXIHu3-4-eg)
The container has been successfully tested against the [CODESYS Development System V3](https://store.codesys.com/codesys.html) in the version V3.5.15.40(64Bit) and the [CODESYS Control for Raspberry Pi SL](https://store.codesys.com/codesys-control-for-raspberry-pi-sl.html) and [CODESYS Control for Raspberry Pi MC SL](https://store.codesys.com/codesys-control-for-raspberry-pi-mc-sl.html) both in the version V3.5.16.0

### License

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).
Copyright (c) Hilscher Gesellschaft fuer Systemautomation mbH. All rights reserved.
Licensed under the LISENSE.txt file information stored in the project's source code repository.

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](http://www.hilscher.com/fileadmin/templates/doctima_2013/resources/Images/logo_hilscher.png)](http://www.hilscher.com) Hilscher Gesellschaft fuer Systemautomation mbH www.hilscher.com
10 changes: 9 additions & 1 deletion init.d/entrypoint.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,16 @@ else
echo "cifx0 hardware support (TCP/IP over RTE LAN ports) not configured."
fi


# run applications in the background
echo "starting ssh ..."
echo "starting SSH server ..."
if [ "SSHPORT" ]; then
#there is an alternative SSH port configured
echo "the container binds the SSH server port to the configured port $SSHPORT"
sed -i -e "s;#Port 22;Port $SSHPORT;" /etc/ssh/sshd_config
else
echo "the container binds the SSH server port to the default port 22"
fi
/etc/init.d/ssh start &

if [ -f /etc/init.d/codesyscontrol ]
Expand Down

0 comments on commit 909dfb1

Please sign in to comment.