Samples
Introduction
This article provides a comprehensive explanation of the Torizon samples available for different use cases. It presents the torizon-samples repository and gives some details about the samples contained there. It also explains how to use them and provides recommended guidelines on how to contribute by adding or improving a sample.
Prerequisites
As most samples are made on top of Torizon IDE Extension templates, the prerequisites are:
- Having understood the basics of Torizon IDE Extension.
- Toradex System on Module (SoM) with Torizon OS installed.
- Having Set up the extension environment.
The torizon-samples Repository
The torizon-samples repository contains the source code of the available samples for Torizon. Most of the samples are made on top of Torizon IDE Extension templates and therefore are meant to be used with the Torizon IDE Extension, in the way described in the Torizon IDE Extension documentation.
The source code of the base templates is available in the vscode-torizon-templates GitHub repository.
The metadata containing information like the folder structure, the base template and the Supported by of each sample is present on the samples.json file.
These samples have the following commit structure:
- First commit: Contains a unmodified Torizon IDE Extension base template for the language of the sample
- Second commit: Modifications made on top of the base template in order to implement the desired functionality of the sample
- Third commit: Add the README.md of the sample, the metadata on samples.json and update the list of samples in the README.md of the repository
- Following commits: Updates on the sample
Understand the Samples
Here is an example to help you understand a sample for using GPIO in C language through the commit history:
Go to the root directory of the sample, in this case present in /gpio/C/gpioC and click on History:
There, as described, you will have (initially) these commits:
Open the second commit ( gpio: C: Add GPIO Example
) and you will be able to see the modifications made on top of the C++ console template in order to implement the GPIO functionality on C language.
In this case they were:
Change the compiler to
gcc
and include thegpiod
linking flag on theMakefile
Add the device interface (file path) of the GPIO that you want to access on the
docker-compose.yml
fileChange the file from
main.cpp
tomain.c
and change it's contentAdd the
libgpiod2
andlibgpiod-dev
packages on thetorizonPackages.json
file
Available Samples
The Torizon samples available are the following:
bluetooth: Samples showing how to interact with
libbluetooth
on Torizon OS. Examples available in C.i2c: Samples showing how to interact with a sensor through the I2C interface on Torizon OS. Examples available in Python (interacting with the MPU6050 sensor). Related article: How to Use I2C on Torizon OS
gpio: Samples showing how to interact with GPIOs on Torizon OS. Examples available for C, Python and .NET. Related article How to Use GPIO on Torizon OS
pwm: Samples showing how to interact with pwm interface exposed through sysfs. Examples available for C. Related article How to Use PWM on Torizon OS
spi: Samples using the SPI communication protocol, through the
spidev
interface, on the User-Space. Examples available in C. Related article How to Use SPI on Torizon OStflite: Sample using Tensorflow Lite with hardware acceleration on the IMX8 SoCs with Vivante GPU. Examples available in Python.
vpu: Sample demonstrating the use of VPU on i.MX8 for encoding and decoding. Example available as a generic Dockerfile (bash script executing
gstreamer
commands).
How to Contribute
You can contribute with this repository in many way such as sending commits with samples or fixes and improvements in existing samples, providing feedback, reporting bugs, and giving suggestions. And you are very welcome to do so.
You can use the issues section from this Github repository to report bugs, discuss issues, provide feedback, ask for new features, and ask for help.
If you want to send a commit with a fix or improvement. The following conventions are also valid for adding a new sample:
- Modify one template in each commit. For example, if you have fixes on GPIO C template and PWM C template make separated commits for each one.
- Start the commit message title with
<directory name>: <language subdirectory name>: <message title>
Also, if you want to add a new sample the recommended way is by using a Torizon IDE Extension template as base. To do it, first:
Create a directory with a name that describes what it is supposed to do, or choose an existing one if it makes sense. Example: The GPIO samples are inside the
gpio
directory, the TensorFlow Lite sample is inside thetensorflow-lite
directory.Create a subdirectory with a name of the language, or a characteristic that differentiates it from the others. Example: If you want to add a C sample name it
C
. If there is already a C template there (using Makefile for example) and you want to add a CMake one, you can for example name yoursCCMake
.
Valid for the following commits. Remove the default device on the extension before committing it:
Get the appropriate template from the vscode-torizon-templates GitHub repository and use it as base, committing it unmodified on the first commit.
Add one commit (or more if it makes sense in your case) with the modifications made on top of the base template in order to implement the desired functionality of the sample
Add one commit with the README.md of the sample, the metadata on samples.json and the updates on the list of samples in the README.md of the repository