Getting Started
Getting started section covers usage tips for TDC-X, how to set up development environment, how to create and deploy applications and where to find useful services and information.
Structure for getting started:
- Installing, Accessing and Removing Applications
- Docker Authorization Policy Scope
- Working With Portainer
- gRPC Usage
- Networking
- IO-Link
This section discusses the setup of applications on the TDC-X device. The TDC-X device has some predefined applications that can be downloaded and used in simple steps. Those applications include:
GrafanaInfluxdbMariadbMosquittoNoderedPortainerPostgresqlRedis
An example of installing Portainer will be provided.
This section describes how to install, access and uninstall an application using the Portainer service as an example.
To set up Portainer, go to the TDC-X Home Page, then select the System tab on the left panel. Select Applications.
The Applications page lists services that can be installed to the TDC-X device by simply clicking on the Install button. To install Portainer, find the service in the given list and click Install.
NOTE: To install the listed applications, make sure the TDC-X device is connected to a network.
The chosen service will be installed shortly. Once the download and installation is complete, the service will automatically be running.
To access the newly installed service, select the Open button. This will take you to the home page of the installed service. For example, Portainer is located on https://192.168.0.100:9443/.
NOTE: Some services, like Portainer, require setting up a username and password before proceeding to the application itself.
To uninstall an application from your device, select the System tab on the left panel. Select Applications. Select Uninstall for the application you want to remove and wait for the process to finish. This will remove the application and all user data on it from the device.
In this section, the Docker Authz authorization plugin is introduced, and policy restrictions are listed.
To secure the TDC-X device's Docker engine, an authorization plugin is developed according to a security and compliance policy. This policy restricts certain operations like elevating privileges, accessing sensitive devices or writing risky configurations. The plugin is implemented as an OPA (Open Policy Agent) policy for Docker.
The policy is implemented as a set of rules Docker commands need to adhere to, and blocks any commands that would violate the device's security.
If any of the commands match the deny rules of the plugin, the request is denied and the plugin returns an error message. Otherwise, the Docker API processes the command.
In the following sections, Docker policy restrictions are listed.
NOTE: When developing a custom Docker container and image, make sure to adhere to the policy.
Running containers in privileged mode is denied.
Example:
"HostConfig": { "Privileged": false } // Allowed
"HostConfig": { "Privileged": true } // Denied
Mounting sensitive paths is denied. Make sure to use only allowed bind mounts!
Allowed Bind Paths:
/datafs/operator-
/var/run/cc,/run/cc -
/var/run/hal,/run/hal /var/run/docker.sock/var/volatile/tdcx/etc/tdcx/etc/os-release/media/datafs/tdc-engine/etc/machine-id/run/log/journal/usr/lib/os-release-
/dev/mmcblk1,/dev/mmcblk1p*
Allowed Read-Only Bind Paths:
/etc/tdcx/etc/os-release/etc/machine-id/run/log/journal/usr/lib/os-release
NOTE: All other bind mounts are denied!
Example:
"BindMounts": [
{ "Source": "/etc/tdcx", "ReadOnly": true } // Allowed
{ "Source": "/etc/tdcx", "ReadOnly": false } // Denied
{ "Source": "/root", "ReadOnly": true } // Denied
]
Volume creation is subjected to the same bind mount restrictions as containers.
Denied volumes:
- Bind mounts to non-whitelisted or non-read-only sensitive paths
Adding dangerous Linux capabilities is denied.
Denied capabilities:
allaudit_controlsys_adminsys_modulesys_ptracesyslogdac_read_search
Other capabilities are considered non-dangerous and allowed.
Example:
"HostConfig": { "CapAdd": ["NET_ADMIN"] } // Allowed
"HostConfig": { "CapAdd": ["SYS_ADMIN"] } // Denied
Using host namespaces is denied.
Therefore, the following are denied:
UsernsMode: "host"PidMode: "host"UTSMode: "host"CgroupnsMode: "host"IPCMode: "host"
Example:
"HostConfig": { "UsernsMode": "host" } // Denied
"HostConfig": { "PidMode": "host" } // Denied
Publishing all ports is denied.
Example:
"HostConfig": { "PublishAllPorts": true } // Denied
Unconfined Seccomp, AppArmor, or disabled SELinux labeling is denied.
Denied options:
seccomp=unconfinedapparmor=unconfinedlabel:disable
Example:
"HostConfig": { "SecurityOpt": ["seccomp=unconfined"] } // Denied
Sensitive sysctls are denied.
The following are denied:
kernel.core_pattern- any sysctl starting with
net.
Example:
"HostConfig": { "Sysctls": { "kernel.core_pattern": "..." } } // Denied
"HostConfig": { "Sysctls": { "net.ipv4.ip_forward": "1" } } // Denied
Access to host devices is restricted.
Only the following devices are allowed:
/dev/serial/by-id/tdcx-serial-
/dev/mmcblk1,/dev/mmcblk1p*
NOTE: All other devices are denied!
NOTE: DeviceCgroupRules and DeviceRequests usage is denied!
Examples:
"HostConfig": {
"Devices": [{ "PathOnHost": "/dev/serial/by-id/tdcx-serial" }] // Allowed
"Devices": [{ "PathOnHost": "/dev/sda" }] // Denied
"DeviceCgroupRules": ["c 42:* rmw"] // Denied
"DeviceRequests": [{ ... }] // Denied
}
Copying content from the host into containers using the archive API is denied.
Denied PUT requests:
- PUT requests to
/containers/{id}/archive
If any deny rule listed above matches, the Docker command will fail.
Q | In some cases my docker container does not start. Looking at logs following error messages can be seen: 'Failed to allocate and map portaddress already in useError starting userland proxy'.
A | Ensure that no other Docker containers are using the same port.
If no conflicts are found, the issue may be related to a known Docker Engine issue. Restarting the device should resolve the problem and allow the container to start normally.
Q | I've made changes to TDC-X SSH work environment and now I have troubles working with it.
A | To reset SSH workspace issue the following operation: container-reset-userworkspace via REST API /api/v1/system/administration/operation.
Make sure to confirm the operation with /api/v1/system/administration/operation/confirm. Access the Control Center API UI via the page Resources → Documentation → Control Center.
Q | I've made changes to AppEngine either by deploying apps or manipulating its variables and now I have troubles working with it.
A | To reset AppEngine issue an operation container-reset-appengine via REST API /api/v1/system/administration/operation.
Make sure to confirm the operation with /api/v1/system/administration/operation/confirm. Access the Control Center API UI via the page Resources → Documentation → Control Center.
Q | After updating to TDC-X FW 1.4.0 it's no longer possible to reach IO-Link REST API on host port 9000 from inside of container.
A | From version 1.4.0 IO-Link API is available on localhost endpoint 127.0.0.1:19005. If your container is using network=host then this API is reachable via 127.0.0.1:19005.
If your container is using a bridge network, then add a parameter --add-host ("extra_host" in docker compose) "host.docker.internal:host-gateway". This way, IO-Link API will be reachable on endpoint host.docker.internal:19005.
Q | After updating to TDC-X FW 1.4.0 I cannot deploy my docker applications anymore. Error mentions 'authorization denied by plugin'.
A | From version 1.4.0 Docker API authorization is activated which enforces a policy for every Docker API operation.
In this section, working with Portainer is discussed. The section provides an insight into accessing the Portainer service after application installation, deploying images, and building a container for an image.
Provided you have installed Portainer on the TDC-X device, it can be accessed on this page.
For help installing Portainer on your device, refer to Installing, Accessing and Removing Applications.
To be able to deploy an application on the TDC-X device, the application needs an environment it can run in. This environment is called an image.
To upload an image, an image file is needed. There are multiple ways of obtaining an image. In this example, we build an application using the docker build command, and the image is saved using docker save.
docker build -t img-tag /path/to/dockerfile
docker save -o output.tar img-tag:latestReplace the tag, path/to/dockerfile and output parameters accordingly.
After building the image, go to the Portainer Dashboard and select the Images option, or find the Images option on the left panel.
The .tar file can be uploaded by selecting the Import option.
Select a valid .tar file and give the image a fitting name. In this example, a dio-grpc-app.tar file was selected, and the image was named dio-grpc.
Select Upload and wait for the image to be uploaded to your device. Once it is on the device, Portainer will show the image and Dockerfile details which specify the ID, size, creation date, build, environment, command and layers of the image.
A container is needed for an image to run in. To provide a container to an imported image, go to the Containers tab on Portainer, where all current containers are listed.
To add a container, select the option Add container. Provide a name for you container, and the image uploaded to Portainer in the last step.
One can also set the following parameters:
- Registry
- Always pull the image
- Create a container webhook
- Publish all exposed ports to random host ports
- Port Mapping
- Access control
- Auto Remove
You can also set Advanced container settings, which allows the user to set additional environment parameters like:
- Commands and logging
- Volumes
- Network
- Env
- Labels
- Restart policy
- Runtime and resources
- Capabilities
Once all options are set, select Deploy the container. The container will now start running.
This section provides insight into how to use the HAL Service gRPC API. Setting up grpcurl, server authorization, gRPC Clicker and accessing HAL services is discussed.
The grpcurl utility provides a means to access gRPC services via shell command. It is used to send a request to the TDC-X device with the specified HAL service port. To get the latest version of the grpcurl utility, run the following line in the terminal:
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
To be able to access the utility, the bin path needs to be exported.
export PATH="$PATH:$(go env GOPATH)/bin"
To test grpcurl availability, use the following line:
grpcurl --version
To access TDC-X' HAL Services, user authentication is needed. This is done by fetching an authentication token from the device. Use the curl command to authenticate the TDC-X user. See an example below.
curl -s -X POST http://{DEVICE_IP}/auth/login -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username":"{USERNAME}","password":"{PASSWORD}","realm":"{REALM}"}'
Replace the {DEVICE_IP}, {USERNAME}, {PASSWORD} and {REALM} with your actual values. For example, if the values of the listed variables are the following:
-
{DEVICE_IP}:192.168.0.100 -
{USERNAME}:admin -
{PASSWORD}:password123 -
{REALM}:admin,
The curl command will be the following:
curl -s -X POST http://192.168.0.100/auth/login -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username":"admin","password":"password123","realm":"admin"}'
This will return a token response from the server which will be used for further authentication.
NOTE: To export the value of your token, you can install a service like jq. See the example of exporting a token with jq below.
export CC_TOKEN=$(curl -s -X POST http://{DEVICE_IP}/auth/login -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username":"{USERNAME}","password":"{PASSWORD}","realm":"{REALM}"}' | jq -r '.token')
NOTE: The token is reset after its expiration time is out, and after each reboot of the device.
Below you can find a Node-RED application that fetches the authentication token from your TDC-X. Replace the inject values with your own username and password, and change the send-request URL server if necessary.
To send gRPC requests to the TDC-X device, an authentication token is needed which is added to the gRPC curl. In other words, each call to the server needs to be authenticated. This is done by adding a header to the grpcurl command.
In the following examples, the {DEVICE_IP} and {GRPC_SERVER_PORT} will be set to 192.168.0.100 and 8081 respectively. The HAL Service port is set to 8081 by default, but can be configured in the System Server Settings.
To list all HAL services via the server reflection, use the following command:
grpcurl -H 'Authorization: Bearer {token}' -plaintext {DEVICE_IP}:{GRPC_SERVER_PORT} list
See the example below:
grpcurl -H 'Authorization: Bearer {token}' -plaintext 192.168.0.100:8081 list
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection
hal.analogin.AnalogIN
hal.boardsupport.BoardSupport
hal.can.Can
hal.digitalio.DigitalIO
hal.gnss.Gnss
hal.imu.Imu
hal.ledcontrol.LedControl
hal.serial.Serial
hal.temperaturesensor.TemperatureSensor
hal.wpan.WPAN
To list all functionalities of a single service, the following command is used:
grpcurl -H 'Authorization: Bearer {token}' -plaintext {DEVICE_IP}:{GRPC_SERVER_PORT} list {PACKAGE}.{SERVICE}
For example, we want to list all functionalities of the AnalogIN service from the hal.analogin package. This is done the following way:
grpcurl -H 'Authorization: Bearer {token}' -plaintext 192.168.0.100:8081 list hal.analogin.AnalogIN
hal.analogin.AnalogIN.Attach
hal.analogin.AnalogIN.ListDevices
hal.analogin.AnalogIN.Read
hal.analogin.AnalogIN.SetMeasureMode
The utility can also be used to access the listed services. For example, one can list all Analog Input devices using the following command:
grpcurl -emit-defaults -H 'Authorization: Bearer {token}' -plaintext 192.168.0.100:8081 hal.analogin.AnalogIN.ListDevices
{
"devices": [
{
"name": "AI_A",
"mode": "Voltage"
},
{
"name": "AI_C",
"mode": "Voltage"
},
{
"name": "AI_B",
"mode": "Voltage"
}
]
}
To read a specific value, the following command can be used:
grpcurl -emit-defaults -H 'Authorization: Bearer {token}' -plaintext -d '{"name":"AIN_A"}' 192.168.0.100:8081 hal.analogin.AnalogIN.Read
{
"adcRaw": 3,
"converted": 0.007561375,
"unit": "V"
}
To write to an Analog Input, use the following command:
grpcurl -emit-defaults -H 'Authorization: Bearer {token}' -plaintext -d '{"name":"AIN_A","mode":"Current"}' 192.168.0.100:8081 hal.analogin.AnalogIN.SetMeasureMode
{}
Reading the state of AIN_A now will yield the following result:
{
"adcRaw": 3,
"converted": 0.037806872,
"unit": "mA"
}
The gRPC Clicker extension is a VSCode extension which can be installed via the Extensions Marketplace. It is used to connect to a gRPC server and to request services from it. It has a Graphical User Interface to make it easier for the user to interact with the server.
To install gRPC Clicker, open VSCode and go to the Extensions tab. Search for gRPC Clicker. Click Install.
After installation, the tool should create a new tab which can be accessed. To add a new gRPC server, select the plus icon in the Proto Groups section. A Proto schema assistant will open.
The following parameters should be set up:
-
Name- Name of your Proto Group -
Address- Device IP and gRPC server port -
Custom flags- Authorization header
For example, set the name to grpc-tdc-x, and the address and port to 192.168.0.100:8081. Custom flags need to be set as authentication is needed to request services from the gRPC TDC-X server. The custom flag has the following strucure:
-H 'Authorization: Bearer TOKEN'
NOTE: Make sure to generate an authentication token and paste it instead of the TOKEN value!
The group is now set and can list all gRPC services currently available on your TDC-X device.
The gRPC Clicker extension fundamentally works the same way as the grpcurl utility does, but provides a GUI to the user for better service visualization and easier access. To list all AIN devices, for example, click on the hal.analogin.AnalogIn subgroup and expand it. The left panel is used for setting parameters that are needed for the request, like when reading or writing a value. The right panel returns the server result.
Select ListDevices, which doesn't require any input parameters. You can send the request by selecting the Send button, and a response will be generated on the right side of the screen, listing all available AIN devices.
To read the value from a device, select the Read subgroup and insert the name of the Analog Input to read on the left panel.
To write a value to a device, select SetMeasureMode. Set the name and mode variables to set the measure mode of the Analog Input device.
This sets the AnalogIN measure mode, and reading the device's value now will show that the measure mode has been set to Current.
For internal usage, the TDC-X has a Unix socket which allows accessing available HAL Services. The HAL socket on the TDC-X device works with a TCP endpoint like grpcurl, so the command is generally used in the same way.
NOTE: Install grpcurl in your workspace to access socket content or use the examples provided in the Code Samples section.
For example, listing all HAL service commands is done using the following line:
grpcurl -emit-defaults -plaintext -unix -authority "localhost" "unix:///var/run/hal/hal.sock" listInstead of a server address, grpcurl now uses the -unix flag and the path to the HAL socket. Since the HAL socket is run locally on the TDC-X device, no authentication form is required
For Node-RED examples used in this documentation, a custom version of the node-red-contrib-grpc node was implemented. Using the Palette's version in Node-RED will not allow TDC-X user identification and/or accessing the UNIX socket!
Make sure to import the following node into your Node-RED project:
node-red-contrib-grpc v1.2.6Most industrial computers come with predefined networking settings.
TDC-X comes with two predefined interfaces, eth1 and eth2. While eth2 and WLAN have their default settings set as DHCP,
the eth1 interface is set up as Static with default network settings:
IP address: 192.168.0.100
Subnet mask: 255.255.255.0
Default gateway: 0.0.0.0Network consists of three default interfaces labeled as:
- Ethernet 1 -
eth1 - Ethernet 2 -
eth2 - WLAN -
wlan0
Interfaces mode can be Static or DHCP.
Every inteface has fallback modes that can be set.
See: DHCP section
To change the IP address of a device, change the corresponding values in the shown fields and click apply:
For example, if the IP pool of your router’s DHCP server is 192.168.0.2 - 192.168.0.254, you should enter an IP address within this range, like 192.168.0.75.
Note: The IP address of a device is now changed, and the adapter settings on your local PC must be changed accordingly.
To change default static mode to DHCP, click in the field Addressing mode and change option from static to DHCP.
When DHCP is selected, every interface has a fallback mode that can be a static IP address or repeated DHCP.
The device will try to get interface networking data from the available DHCP server.
In case DHCP data is not available, the device will set its interface networking data to a statically defined IP address.
Note: The IP address of a device is now changed, and the adapter settings on your local PC must be changed accordingly.
In this section, wireless network interface is discussed.
Note: In order to enable wireless network interface country code must be set.
Make sure WLAN interface is enabled, then click on a plus button to add a new network connection.
Enter network credentials and confirm.
When new network is connected, status will be "Connected".
Gateway priority card shows list of available interfaces and current gateway priority order.
To change the priority, select only one interface item and reorder the selected item.
When order is set, confirm by clicking apply.
Note: When no gateway is set for the current interface in the Interfaces menu, the defined order for this interface is not taken into account.
The currently used DNS servers list shows a combination of user-defined DNS servers and all DHCP predefined server lists.
The user-defined DNS server list takes precedence.
Creation order of user defined DNS servers defines the priority of used DNS servers.
Modem and modem connection must be enabled. When modem connection is disabled, modem can be used for sending and receiving SMS data.
To establish a modem internet connection, APN profile data must be set.
APN (Access Point Name of your current provider) is a mandatory value and must be set.
Depending on your provider, username and/or password are not required.
The dial string field is used in some special cases where modem initialization is required by the carrier.
Note: In case where multiple interfaces are utilized and the modem interface has internet access, DNS priority must be set accordingly.
Firewall section enables you to set all interfaces as private or public.
Public interfaces can be accessed from the Internet.
IO-Link, a short distance, bi-directional, digital, point-to-point, wired, industrial communications networking standard used for connecting digital sensors and actuators to either a type of industrial fieldbus or a type of industrial Ethernet.
IO-Link is a standard (IEC 61131-9) that can be used to connect intelligent devices at the sensor and actuator level to an automation system.
TDC-X has a built in 4-Port IO-Link Master for connecting IO-Link devices. The data from IO-Link devices can be transmitted to a network via the integrated network interfaces using the built-in MQTT client.
TDC-X has a web user interface that is used to parameterize the device and the connected IO-Link sensors.
- NOTE: At least one IO-Link device needs to be connected for IO-Link interface to be used
By default TDC-X Device has 4 IO-Link ports.
Each port can be configured separately.
All Ports have 4 main modes that can be selected:
- IO-Link
- Digital in
- Digital out
- Deactivated port
When the IO-Link option is selected for a specific port, the port will assume all default characteristics necessary to work with IO-Link sensor or controller.
Port status section will display the status of a device if connected.
IO-Link Port can be configured as Digital in or Digital out mode which depends of the type of the sensor.
Device alias value is important value that operator can set, and afterwards use this value when using API to get or send data to the sensor connected to specific port.s
URL : http://192.168.1.100/iolink/v1/devices/master1port1/processdata/value
Method : GET
Body : [json-response]
Using an API, operator can allways check defined alias for a specific port.
URL : http://192.168.1.100/iolink/v1/masters/1/ports/1/configuration
Method : POST
Body : "deviceAlias": "master1port1"
When an IO-Link device is connected to a specific port, its information and data are automatically displayed.
Device identification card displays main sensor information. Sensor informations are automaticaly detected.
Manual view enables basic sensor data read and write.
Operator must know all sensor device specification to use this simple interface.
For example, primary value for this specific sensor can be read at buffer at index: 109.
All documetation for every sensor is available at SICK's Products web page: https://www.sick.com/us/en/products/c/g568268
Every IO-Link sensor produced by SICK a.g. is accompanied by an appropriate IODD file that can be found and download from an official https://www.sick.com/ site.
Specifically Products page: https://www.sick.com/us/en/products/c/g568268
To enable IODD view for a specific port, and for a specific sensor, the IODD file must be added to the TDC-X IODD File Management module.
IODD File Management module enables operator to add or delete added IODD file.
IODD View is enabled when the correct IODD file is added to the IODD file management module.
The TDC-X Device will recognize and use the correct IODD file for every sensor based on the sensor's Device ID and corresponding Vendor ID.
The IODD viewer enables the operator to set and read all available sensor parameters and data in a human-readable format.
Configure and use MQTT with TDC-Next IO-Link.
This section enables configuring MQTT topics and status overview.
For the device to be able to broadcast messages, a broadcast server must be installed.
The TDC-X device under Applications offers the application "Mosquitto" which is an MQTT server.
The Mosquitto server broadcasts all topics at port 1883 by default.
TDC-X can serve as a client and broadcast all messages to an existing MQTT server.
In that case, the operator must fill all required data as shown in the example below.
IODD File Management is described in the context of IODD Viewer in section : 3.4. IODD View and management