How to Use UART on TorizonCore
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
RS-485 is a communication protocol running on top of the UART stack. The same steps provided in the more generic article UART (Linux): RS-485 apply to TorizonCore.
- TorizonCore installed on a Toradex module.
- Have completed the Torizon Quickstart Guide lessons.
- Discover which UART device you want to use.
Add the UART Device From the Host to the container
In Linux, UART devices can be accessed through files on
/dev/verdin-uart*. Take a look to UART (Linux) article to understand the standard names across the Toradex's module families.
Once you identify the exact name for your UART device, you can add it to your container using
docker run or
Using docker run Command
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/verdin-uart1 device inside a container based on the Torizon Debian base container:
# docker run --rm -it --device /dev/verdin-uart1 torizon/debian:$CT_TAG_DEBIAN
To check if the device was added, run this on the container's terminal:
## ls /dev/verdin-uart1
Using Docker Compose
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.
The serial port can be used with several programming languages and libraries, same as with any Linux distribution. For demonstration purposes, we provide Python and .NET Core samples.
Documented use cases are provided in the following subsections.
.NET Core: Connect to a Serial GPS Using the VS Code Extension
If you want to use .NET Core to access the UART with the Torizon Visual Studio Code Extension, please read the following article for more information:
Python: Connect to a Serial GPS Using the VS Code Extension
The source code from the example Python: Connect to a Serial GPS Using Command-line Interface is also used to explain how to use UART with the Torizon Visual Studio Code Extension. Please read the following article for more information:
Python: Connect to a Serial GPS Using Command-line Interface
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.
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.
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.
Building the Example
In your development PC, clone the samples repository:
$ git clone https://github.com/toradex/torizon-samples.git
gps/python directory from your PC to your Torizon module (change
X.X.X.X to your module’s IP-address):
$ scp -r ./samples/gps/python/ torizon@X.X.X.X:/home/torizon/
In your module's terminal, change the current directory to the
# cd /home/torizon/gps/python
Build the container. Choose from the tabs below to see the example for 32 or 64 bit Arm:
Please remember that if you once built your image for one architecture, you need to pass the
--pull argument to build for another architecture. According to the Docker documentation, the
pull argument will always attempt to pull a newer version of the image.
$ docker build --pull .
Running the Example
On the Apalis iMX6 with an Apalis Evaluation Board, UART2 is accessible through
/dev/apalis-uart2. Hence, run the container using the following command:
# docker run -it --rm --device=/dev/apalis-uart2 gps
--device parameter allows the UART to be accessible from within the container. Adjust the 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
Example Explained: The Project's Dockerfile
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:
Sets the serial device that is connected to the GPS:
ser = serial.Serial("/dev/apalis-uart2",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