Skip to main content
Version: Torizon OS 6.x.y

How to Use UART on Torizon OS

Introduction​

In this article, we will show how to add a UART device to be accessed in a containerized application in Torizon OS.

This article complies with the Typographic Conventions for Torizon Documentation

RS-485​

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 Torizon OS.

Prerequisites​

Add the UART Device From the Host to the container​

In Linux, UART devices can be accessed through files on /dev/apalis-uart*, /dev/colibri-uart* and /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 docker-compose.

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
/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.

docker-compose.yaml
devices:
  - "/dev/verdin-uart1:/dev/verdin-uart1"

Examples​

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.

caution

there may be other Python libraries with similar functionality, we've chosen pyserial and pynmea2 because they are well-known libraries.

The goal of this sample is to demonstrate how UART can be accessed from within a container.

Hardware connection​

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.

Building the Example​

In your development PC, clone the samples repository:

$ git clone https://github.com/toradex/torizon-samples.git

Copy the 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 gps/python directory:

# cd /home/torizon/gps/python

Build the container. Choose from the tabs below to see the example for 32 or 64 bit Arm:

# docker build -t gps .

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.

Example: 

$ 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

The --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 Serial() function.

Sample Output​
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 pyserial and 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/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 stdout.

You can learn more about pySerial's API on their developer's website.



Send Feedback!