Search by Tags

How to Use UART on TorizonCore

 

Article updated at 06 May 2020
Compare with Revision

Subscribe for this article updates

Introduction

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

Prerequisites

Add the UART Device From the Host to the container

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

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/tty0:/dev/tty0"

Examples

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.

Python: Connect to a Serial GPS Using the VS Code Extension

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:

Python: Connect to a Serial GPS

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 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 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 gps directory:

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

Running the Example

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

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

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