Skip to content

[Tutorials] Development Documentation

Jump to bottom
tkrzielSICKAG edited this page Feb 6, 2024 · 29 revisions

This section describes how to start the tutorial applications step by step. The following tutorials are made:

For ease of use of the following tutorial examples, .bat and .sh files have been created so that they automatically use predefined docker commands to build and save an image. Their usage is also described in detail in the end section.

A prerequisite to be able to run the presented files is installing Docker.

1. Application Tutorials

In this section, application tutorials are discussed. Environment setup, application implementation and running of the application is described for a Python, C# and Go application. Links to application files are provided for each example given.

1.1. Python Application Tutorial

1.2. C# Application Tutorial

1.3. Go Application Tutorial

Link to Application Files

The LED DIO application is a simple application that can read and writes sensor status via TDC-E which runs on ARM 32 v7. To do so, it does not use web sockets nor https, but a direct interface. The program randomly chooses whether to set the specified LED output on or off in an infinite loop.

1.3.1. Environment Setup

Since the application works with a LED and the DIO interface, a requirement for the application to work is to set up the DIO interface. For help with the setup, refer to TDC‐E Interface Configuration's Digital Input Output section.

1.3.2. Application Implementation

This application is implemented relatively simply. It starts an infinite for loop which executes a function to change the LED value, then sleeps for 5 seconds before once again setting the LED to a different value.

The function is implemented so that it randomly chooses whether to start or stop the glow of the LED, then executes a shell command used to turn the LED on or off. If the value is 0, the LED is off. Otherwise, the LED is on.

It is also important to note the GPIO of the LED, since each digital input and digital output has a different values for their GPIO. The GPIO used for the program is 496, mapped to the A connector, and it is a digital output. If another configuration is needed, make sure to use the correct mapping.

The command is executed with the following Golang code:

out, err := exec.Command("sh", "-c", cmd).Output()

This code executes a shell command using the os/exec Go package. The cmd parameter is the parameter for changing the LED state. The LED is set to ON using the following command:

echo 1 > /sys/class/gpio/gpio496/value

This sets the value in the path /sys/class/gpio/gpio496/value to 1, turning the LED on. To turn it off, the following command is used:

echo 0 > /sys/class/gpio/gpio496/value

1.3.3. Running the Application

Step 1. Building, Pushing, Saving

The files for this tutorial contain two ways to build, push or save the application developed for the TDC-E. These files have the extensions .bat and .sh respectively. Below is a list of the files available for building, pushing and saving the application:

  • build-registry.bat - builds the image and pushes it to a registry, for Windows OS
  • build-registry.sh - builds the image and pushes it to a registry, for Linux OS
  • build-tar.bat - builds the image and saves it as .tar file, for Windows OS
  • build-tar.sh - builds the image and saves it as .tar file, for Linux OS

**NOTE: **The registry files need to be modified with text or code editing software, as the registry name should be modified to match the name of the available registry. See details below.

NOTE: On Linux, changing file permissions may be needed if by starting the file a permission denied message is printed. To change file permission, use chmod [options] permissions file-name. E.g. chmod 777 build-tar.sh.

1.3.3.1. Creating Image with a Registry

If there is an available registry that will store the images, click on the build-registry.bat if you're running Windows OS, or build-registry.sh if you're running Linux OS. The image will be built automatically and sent to your registry with the annotated name. Now, the image is in your registry, and can be pulled from any other device with access to it. Now it needs to be downloaded to the device that is going to run it, namely your TDC-E device.

Then log onto your TDC-E device. See this short section for pulling the image to your device. Now proceed to Step 2.

1.3.3.2. Creating Image with a .tar File

To create an image without a registry, click on the build-tar.bat file if using the operating system Windows, or build-tar.sh if using the operating system Linux. This should automatically build the image and save it to an archive called directdioled.tar. This archive can then be uploaded to the TDC-E by using Portainer. For help with the uploading process, refer to this section. Now proceed to Step 2.

Step 2. Creating a Container

Containers are needed to provide a runtime environment for the images you've created. The images are now safely stored on your TDC-E device and will need to be bound to a container next. Find the docker-compose.yml file in the linked application files which is used to create a suitable environment for your application. Use this file and follow the steps described here. Choose one of the two described ways to create a container.

The container should now start running automatically if all is correct, and the application should be running on your device.

2. .sh and .bat Files Breakdown

In this section, code inside the provided .sh and .bat file is discussed.

2.1. Building and Pushing Registry Files with .sh and .bat

In this section, building and pushing the image to a registry for the TDC-E device is discussed. In the files, there is a .sh and .bat file for that matter with their file structure and usage being very similar.

The structure of the .sh file, used for the Linux operating system, is the following:

#!/bin/bash

docker build --no-cache -t registry-name:1.0.0 .
docker push registry-name:1.0.0

sleep 30

First, the file specifies that the file is a bash script. It does so with the #!/bin/bash annotation. The docker image is built with the next statement. No cache is specified so that cached layers that were already built are ignored. This means that the build process will always be reset, which is useful for building when significant changed often occur in the Dockerfile (e.g. debugging or adding services). Keep in mind that the Dockerfile is run from top to bottom, issuing the commands in order, so top commands get executed first.

You can remove this --no-cache flag, which will speed up the process of building the image on the next iteration of the run, as Docker cashes successful actions.

The build is tagged with the -t flag. since a registry is used, replace the registry-name:1.0.0 with the name of your registry. This will be the tag for your image. Make sure to also replace the tag in the second line, as these names need to match. With the second command, the image is pushed to your specified registry under the same tag name.

In the end, sleep 30 is used so that results are displayed for 30 seconds before exiting the program.

The .bat file works in the same way. The only difference is no specification of the file usage on top, and sleep 30 is replaced by timeout /t 30, which serves the same function.

docker build --no-cache -t registry-name:1.0.0 .
docker push registry-name:1.0.0

timeout /t 30

2.2. Building and Saving .tar Files with .sh and .bat

The .tar file building files are called build-tar.sh for the Linux operating system and build-tar.bat for the Windows operating system respectively. Both files have the serve the same function and are very similar. The structure of the build-tar.sh file is the following:

#!/bin/bash

docker build --no-cache -t myapp:1.0.0 .
docker save -o myapp.tar myapp:1.0.0
sleep 30

The first line annotates that the written script is a bash shell script. The docker image is built with the next statement. No cache is specified so that cached layers that were already built are ignored. This means that the build process will always be reset, which is useful for building when significant changed often occur in the Dockerfile (e.g. debugging or adding services). Keep in mind that the Dockerfile is run from top to bottom, issuing the commands in order, so top commands get executed first.

You can remove this --no-cache flag, which will speed up the process of building the image on the next iteration of the run, as Docker saves successful actions.

Then the command docker save is used. This command specifies that the myapp:1.0.0 is being saved to the output myapp.tar, which will contain all necessary items for running the image once transferred to Portainer. Then the program sleeps for 30 seconds, allowing any messages to show upon completing the script.

The Windows .bat file functions in the same way. The only difference is no specification of the script at the start of the file, and instead of the sleep command, timeout /t 30 is used, which also stops the application for 30 seconds before exiting.

docker build --no-cache -t myapp:1.0.0 .
docker save -o myapp.tar myapp:1.0.0
timeout /t 30
Clone this wiki locally