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
- Working With Portainer
- gRPC Usage
- Networking
- Docker Authorization Limitations
- FAQ
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, 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:
Most 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.
This policy enforces security and compliance for Docker containers by restricting privileged operations, sensitive mounts, device access, and other risky configurations. It is implemented as an OPA (Open Policy Agent) policy for Docker authorization.
Description:
Running containers in privileged mode is denied.
Allowed:
-
HostConfig.Privileged: false(or omitted)
Denied:
HostConfig.Privileged: true
Example:
"HostConfig": { "Privileged": false } // Allowed
"HostConfig": { "Privileged": true } // Denied
Description:
Adding dangerous Linux capabilities is denied.
Denied Capabilities:
-
all,audit_control,sys_admin,sys_module,sys_ptrace,syslog,dac_read_search,dac_override
Allowed:
- Only non-dangerous capabilities.
Example:
"HostConfig": { "CapAdd": ["NET_ADMIN"] } // Allowed
"HostConfig": { "CapAdd": ["SYS_ADMIN"] } // Denied
Description:
Using host namespaces is denied.
Denied:
UsernsMode: "host"PidMode: "host"UTSMode: "host"CgroupnsMode: "host"IPCMode: "host"
Example:
"HostConfig": { "UsernsMode": "host" } // Denied
"HostConfig": { "PidMode": "host" } // Denied
Description:
Publishing all ports is denied.
Denied:
PublishAllPorts: true
Example:
"HostConfig": { "PublishAllPorts": true } // Denied
Description:
Unconfined seccomp, AppArmor, or disabled SELinux labeling is denied.
Denied:
seccomp=unconfinedapparmor=unconfinedlabel:disable
Example:
"HostConfig": { "SecurityOpt": ["seccomp=unconfined"] } // Denied
Description:
Setting sensitive sysctls is denied.
Denied:
kernel.core_pattern- Any sysctl starting with
net.
Example:
"HostConfig": { "Sysctls": { "kernel.core_pattern": "..." } } // Denied
"HostConfig": { "Sysctls": { "net.ipv4.ip_forward": "1" } } // Denied
Description:
Mounting sensitive host paths is restricted. Only specific paths are allowed, and some only as read-only.
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
Denied:
- Bind mounts outside the above paths.
- Bind mounts to allowed read-only paths as writable.
Example:
"BindMounts": [
{ "Source": "/etc/tdcx", "ReadOnly": true } // Allowed
{ "Source": "/etc/tdcx", "ReadOnly": false } // Denied
{ "Source": "/root", "ReadOnly": true } // Denied
]
Description:
Access to host devices is restricted.
Allowed Devices:
/dev/serial/by-id/tdcx-serial-
/dev/mmcblk1,/dev/mmcblk1p*
Denied:
- Any device not matching the above.
- Any use of
DeviceCgroupRulesorDeviceRequests.
Example:
"HostConfig": {
"Devices": [{ "PathOnHost": "/dev/serial/by-id/tdcx-serial" }] // Allowed
"Devices": [{ "PathOnHost": "/dev/sda" }] // Denied
"DeviceCgroupRules": ["c 42:* rmw"] // Denied
"DeviceRequests": [{ ... }] // Denied
}
Description:
Copying content from the host into containers using the archive API is denied.
Denied:
- PUT requests to
/containers/{id}/archive
Description:
Volume creation is subject to the same bind mount restrictions as containers.
Denied:
- Bind mounts into non-whitelisted or non-read-only sensitive paths.
- If any deny rule matches, the request is denied and a reason is logged.
- If no deny rules match, the request is allowed.
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 an operation 'container-reset-userworkspace' via REST API /api/v1/system/administration/operationMake sure to confirm the operation with /api/v1/system/administration/operation/confirm.Access the Control Center API UI via 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/operationMake sure to confirm the operation with /api/v1/system/administration/operation/confirm.Access the Control Center API UI via page Resources → Documentation → Control Center
Q | After updating to TDC-X FW 1.4.0 its 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. For more info about that policy see this.