In this article, we will show how to add a UART device to be accessed in a containerized application in TorizonCore.
This article complies to the Typographic Conventions for Torizon Documentation
In Linux, UART devices can be accessed through
/dev/tty*. Depending on the UART hardware implementation, those devices can have different names. Take a look to UART (Linux) article to understand the different
/dev/tty* names across the Toradex's Modules.
Once you identify the exact name for your UART device, you can add it to your container using
docker run or
To add a host device to the container, use the
--device flag with the
docker run command.
For example, let's assume we want to access the
/dev/tty0 device inside a container based on the Torizon Debian base container. Choose from the tabs below to see the example command for 32 and 64 bit Arm:
# docker run --rm -it --device /dev/tty0 torizon/arm32v7-debian-base
# docker run --rm -it --device /dev/tty0 torizon/arm64v8-debian-base
To check if the device was added, run this on the container's terminal:
## ls /dev/tty* /dev/tty /dev/tty0
If you are using Docker Compose, set the
devices configuration in your YAML file for device mappings. Uses the same format as the
--device docker client create option.
devices: - "/dev/tty0:/dev/tty0"
The serial port can be used with several programming languages and libraries, same as with any Linux distribution. For demonstration purposes we will be using Python.
Documented use cases are provided in the following subsections.
The example from the below section Python: Connect to a Serial GPS is also used to explain how to use UART with the Torizon Visual Studio Extension. Please read the following article for more information:
The GPS example project is available at Torizon Samples Github Page
This example uses the Python's
pyserial module to read the data from UART. The application then uses
pynmea2 module to parse the GPGGA string and get the values for time, latitude and longitude. The parsed data than is printed on stdout.
Warning: there may be other Python libraries with similar functionality, we've chosen
pynmea2 because they are well-known libraries.
The goal of this sample is to demonstrate how UART can be accessed from within a container.
Connect a GPS Module to an available UART on your board.
In our case, the example was tested on Apalis iMX6 Evaluation Board and the GPS is connected to UART2. However, you can easily adapt the example for any Toradex's module.
Any GPS module with NMEA output should work. In this example, we are connecting to a Adafruit Ultimate GPS Breakout board module.
Board GPS VCC <--------> VCC RX <--------> TX TX <--------> RX GND <--------> GND
Make sure the power supply and logic levels match between the board and GPS or be prepared for some magic smoke.
In your development PC, clone the samples repository:
$ git clone https://github.com/toradex/torizon-samples.git
gps directory from your PC to your Torizon module (change
X.X.X.X to your module’s IP-address):
$ scp -r ./samples/gps/ torizon@X.X.X.X:/home/torizon/
In your module's terminal, change the current directory to the
# cd /home/torizon/gps
Build the container. Choose from the tabs below to see the example for 32 or 64 bit Arm:
# docker build -t gps .
# docker build --build-arg IMAGE_ARCH=arm64v8 -t gps .
On the Apalis iMX6 with an Apalis Evaluation Board, UART2 is accessible through
/dev/ttymxc1. Hence, run the container using the following command:
# docker run -it --rm --device=/dev/ttymxc1 gps
--device parameter allows the UART to be accessible from within the container. Adjust the
/dev/tty* value according to your needs. For UART and pinout information on other boards, please refer to UART (Linux) article.
Please, note that the same needs to be reflected in
readgps.py file when calling the
Time = 07:53:31 Latitude = 3340.18707, N Longitude = 07259.43225, E . .
The Dockerfile of this project is available on Torizon Samples Github Page.
It starts from a
<arch>-debian-base image and installs python3 along with utilities for package management. The requirements.txt file defines the modules
pynmea2, required for running the sample. These dependencies are installed with
pip install. Finally the sample application
readgps.py is copied to the container’s filesystem and set as the default command.
The readgps.py Python script imports the required libs:
import sys import pynmea2 import serial
Sets the serial device that is connected to the GPS:
ser = serial.Serial("/dev/ttymxc1",9600, 8, 'N', 1, timeout=1)
Reads the data from the GPS over the UART line by line:
data = ser.readline()
After that, it checks for the
GPGGA string. Geographic coordinates and time are extracted from this line and printed on