IOT-LINK: Debian Linux: How-To Guide

Overview

The default run-time Linux filesystem image for the CompuLab IOT-LINK Internet of Things Gateway is based on Debian GNU/Linux BookWorm. The default Debian Linux image includes the following packages:

• Core system
• Debian package management system
• SSH server and client
• NetworkManager
• ModemManager
• Bluez5 Bluetooth tools and daemons
• Docker

Serial Console

IOT-LINK provides a serial console on the front panel micro-USB DBG connector.

Connecting to a host PC

1. Use a micro-USB cable to connect the Console connector to a USB port on your host PC.
2. Make sure the CP2104 driver is available with your operating system, otherwise install it from https://www.silabs.com/documents/public/software/CP210x_Windows_Drivers_with_Serial_Enumeration.zip
3. Identify the host PC interface and port number that will be used for communication with the device:
   • In most Linux PCs, the serial port will be denoted as one of the following: /dev/ttyUSB0, /dev/ttyUSB1 ... /dev/ttyUSBn (where n is a positive integer)
   • In Windows PCs, the serial port usually will be denoted as one of the following: COM1, COM2 ... COMn (where n is a positive integer)
4. Start a terminal emulation program (such as PuTTY on Windows or minicom on Linux).
5. In the port configuration section of the program select the previous identified port and set the following serial port parameters:

Baud Rate	Data Bits	Stop Bits	Parity	Flow Control
115200	8	1	none	none

Connection and Login

This Debian rootfs comes with a default sudo user compulab. User password has to be set at the very first login.

Compulab Release iot-link 1.0 25.05 based on
Debian GNU/Linux 12 iot-link ttyLP0

iot-link login: compulab
You are required to change your password immediately (administrator enforced).
New password: 
Retype new password: 

To login into the Linux system, use a terminal emulator as described here, or connect through the network (ssh).

Package Management

The IOT-LINK Debian Linux image includes everything required to use the Debian package management utilities.
Use apt and dpkg for managing software packages.

Device Serial Number and Configuration

Product information is stored in on-board EEPROM.

• To read the product serial number, issue the following command:

cat /proc/device-tree/baseboard-sn

Note "-" sign which appears on the label is intentionally replaced by "0"

• To read the product configuration part number, issue the following command:

cat /proc/device-tree/baseboard-options

Docker

The Docker Engine is preinstalled.

• The following command downloads a test image and runs it in a container. The container sample prints a message and exits.

 sudo docker run -it ubuntu
latest: Pulling from library/ubuntu
aa21f24e1940: Pull complete
...
Digest: sha256:e3f92abc0967a6c19d0dfa2d55838833e947b9d74edbcb0113e48535ad4be12a
Status: Downloaded newer image for ubuntu:latest
root@0d6b133a7a93:/# cat /etc/issue
Ubuntu 24.04 LTS \n \l

Cellular Modem

IOT-LINK cellular interface is implemented with a mini-PCIe cellular modem and a micro-SIM socket.

• Cellular module is an option that can be pre-installed into the gateway. Verify your gateway is assembled with the modem module
• To set up IOT-LINK for cellular functionality, install an active SIM card into SIM socket located behind the back panel. Please refer to IOT-LINK reference guide for details.
  
• Cellular antenna should be connected to SMA connector A on the front panel.

Cellular Connection

Get IP:

sudo dhclient wwan0

Test the interface:

sudo ping -c 5 dns.google -I wwan0

Modem Reset

The modem module can be forced into hardware reset with the command:

sudo gpioset 0 22=1 ; sleep 0.3 ; sudo gpioset 0 22=0

WiFi

IOT-LINK optionally includes module with 802.11ax WiFi (6) and Bluetooth 5.3 BLE.
The NetworkManager can be used to manage WiFi interface.

Enable/Disable WiFi Interface

• To enable WiFi interface:

sudo nmcli radio wifi on

• To disable WiFi interface:

sudo nmcli radio wifi off

Network Scanning

• Sample WiFi scanning:

sudo nmcli dev wifi list ifname wlan0

The output will show the list of Access Points and Ad-Hoc cells in range.

Connecting to Wireless Network

In the following example:

• Replace <SSID> and <PASSWORD> with the actual access point parameters:

sudo nmcli device wifi connect <SSID> password <PASSWORD> name WifiCon ifname wlan0

• Disconnect wireless network:

sudo nmcli connection down WifiCon

• Connect wireless network again:

sudo nmcli connection up WifiCon

Creating Access Point

Debian 12 ipv4 forwarding must be turned on manually

• Enable port forwarding to ethernet:

internet_gateway=eth0
sudo iptables -t nat -A POSTROUTING -o $internet_gateway -j MASQUERADE
systemctl stop dnsmasq.service
sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
sudo iptables -A FORWARD -i uap0 -o $internet_gateway -j ACCEPT
sudo iptables-save > /etc/iptables/iptables.rules
sudo sed -i 's/^#\(net.ipv[4,6].*forward\)/\1/' /etc/sysctl.conf

In the following example:

• Replace <SSID> and <PASSWORD> with desired access point parameters:

sudo nmcli device wifi hotspot ssid <SSID> password <PASSWORD> con-name HotspotCon ifname uap0

• Disable wireless AP:

nmcli connection down HotspotCon

• Enable wireless AP again:

nmcli connection up HotspotCon

Ethernet

• IOT-LINK optionally features one Gigabit Ethernet port implemented with RTL8211FDI PHY
• One can manage an ethernet interface via NetworkManager or `ip`:

ip help

Bandwidth test example

Start iperf3 server on host:

iperf3 -s -i 60

Straight (client sends, server receives) 1 min. test with report each 10 sec.

iperf3 -t 60 -i 10 -c <serverIP>

Reverse (server sends, client receives) test

iperf3 -t 60 -i 10 -R -c <serverIP>

Industrial Interfaces

IOT-LINK optionally has the following interfaces on the 10-pin industrial terminal block:

• up to two RS485 (half-duplex)
• up to two CAN 2.0B
• three digital inputs/outputs.

For additional details, please refer to IOT-LINK reference guide.

CAN bus

IOT-LINK features up-to two optional CAN-FD ports implemented with i.MX93 CAN controller.

CAN bus ports are only present in gateways ordered with the “FACAN” or “FBCAN” ordering options. CAN ports are mutually exclusive with RS485 ports.

CAN signals are routed to industrial I/O connector. Please refer to IOT-LINK reference guide for Industrial I/O Connector pin-out.
Use an interface depending on the Configuration Options of your unit:

config option	Linux network interface
FACAN	can0
FBCAN	can1

Example for can0

interface configuration

• Enable the CAN interface with bit-rate 1 Mb/sec:

sudo ip link set can0 up type can bitrate 1000000

Send/Receive packets

Use cansend and candump utilities to send and receive packets via CAN interface.

• Dump received data frames and error frames:

candump any,0:0,#FFFFFFFF

• Send:

• Standard frame:

cansend can0 111#1122334455667788

• Extended frame:

cansend can0 11111111#1122334455667788

• Generate 50 random extended frames with 50 msec interval between each:

cangen -g 50 -e -D r -v can0 -n 50

• Disable the interfaces:

ip link set can0 down

RS485

IOT-LINK features up-to two optional RS485 ports implemented with MAX13488 transceivers interfaced with i.MX93 UART ports.

RS485 ports are only present in gateways ordered with the “FARS4” or “FBRS4” ordering options. RS485 ports are mutually exclusive with CAN bus ports.

RS485 signals are routed to the industrial I/O connector. Please refer to IOT-LINK reference guide for Industrial I/O Connector pin-out.

Configuration and Access

• Set a tty variable depending on the Configuration Options of your unit

config option	set Linux tty interface
FARS4	RS485_A=/dev/ttyLP6
FBRS4	RS485_B=/dev/ttyLP4

• Access the RS485 interface can be accessed in Linux via the tty device in ttyRS485 variable:

sudo stty -F ${RS485_B}

RS485 has an optional hardware-enabled termination. Please consult with the reference guide for enabling instructions.

Modbus RS485

The following example demonstrates how to use RS485 in a Modbus RS485 Network where IOT-LINK performs as a Master device and queries XY-MD02 temperature and humidity sensor.

Software installation

Download and install modpoll - a command line based Modbus master simulator and test utility.

wget https://www.modbusdriver.com/downloads/modpoll.tgz -P /tmp/
sudo tar -xvf /tmp/modpoll.tgz -C /opt/

Device connection - example for port B

• Connect XY-MD02 sensor to appropriate Industrial I/O connector pins as below:

-------------------                            --------------------
|                 *--(+)---< <------- 5V-30V   |     IOT-LINK     |
|                 *--(-)---< <-------- GND     |                  |
| XY-MD02 (RS485) |                            |------ Industrial |
|                 *--(A+)--< <--...--> >-(7)-*-|     | I/O        |
|                 *--(B-)--< <--...--> >-(8)-*-|     | Connector  |
-------------------                            --------------------

Read data

• Read temperature once:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 2 -1 ${RS485_B}
...
-- Polling slave...
[2]: 250

• Poll temperature:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 2 ${RS485_B}
...
-- Polling slave... (Ctrl-C to stop)
[2]: 254
-- Polling slave... (Ctrl-C to stop)
[2]: 254
-- Polling slave... (Ctrl-C to stop)
[2]: 254
...

• Read humidity once:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 3 -1 ${RS485_B}
...
-- Polling slave...
[3]: 515

• Poll humidity:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 3 ${RS485_B}
...
-- Polling slave... (Ctrl-C to stop)
[3]: 894
-- Polling slave... (Ctrl-C to stop)
[3]: 895
-- Polling slave... (Ctrl-C to stop)
[3]: 896
...

• Read temperature & humidity once:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 2 -r 2 -1 ${RS485_B}
...
-- Polling slave...
[2]: 263
[3]: 606

• Poll temperature & humidity:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 2 -r 2 ${RS485_B}
...
-- Polling slave... (Ctrl-C to stop)
[2]: 263
[3]: 545
-- Polling slave... (Ctrl-C to stop)
[2]: 263
[3]: 543
-- Polling slave... (Ctrl-C to stop)
[2]: 263
[3]: 542
...

• Read slave address, baudrate, temperature & humidity corrections:

 sudo /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 4 -c 4 -r 258 -1 ${RS485_B}
...
-- Polling slave...
[258]: 1
[259]: 9600
[260]: 0
[261]: 0

Digital I/O

IOT-LINK provides three signals which can be used as either digital inputs or outputs.
Please refer to IOT-LINK reference guide for Industrial I/O Connector pin-out.

External voltage supply in the range 6-24VDC must be supplied via DIO_VIN pin for correct operation of digital outputs.

Access

pin # on terminal block	Command to drive pin high	Command to read pin
2	sudo gpioset 0 4=1	sudo gpioget 0 4 > /dev/null; sudo gpioget 0 16
3	sudo gpioset 0 5=1	sudo gpioget 0 5 > /dev/null; sudo gpioget 0 17
4	sudo gpioset 0 12=1	sudo gpioget 0 12 > /dev/null; sudo gpioget 0 21

Read logical value is opposite to voltage level, i.e. if positive voltage is applied on a pin, its read value will be 0 and vice versa

LEDs

• IOT-LINK features:

• user bi color LED: green and red.
• bi color LED: amber and "power-blue" which is used by default to indicate system state

• LEDs are controlled via GPIO pins and can be accessed via sysfs interface.

Example

• Choose a LED:

 LED=green

• Turn ON

 echo "1" | sudo tee -a /sys/class/leds/${LED}/brightness

• Turn OFF

 echo "0" | sudo tee -a /sys/class/leds/${LED}/brightness

• Set trigger

 echo "heartbeat" | sudo tee -a /sys/class/leds/${LED}/trigger

TPM

IOT-LINK is assembled with TPM 2.0 implemented with Infineon SLB9673.

TPM Basic Functionality

• Install the tpm2-tools package:

sudo apt-get update && sudo apt-get install tpm2-tools

• Validate basic functionality

sudo tpm2_getrandom --hex 32

The correct result will be returned generated 32-symbol key.

RTC

IOT-LINK features two real time clock (RTC) devices:

• AM1805 (default rtc0) - for low current, battery backed time keeping whenever the main power supply is not present.
• i.MX93 internal RTC (rtc1) - can be used as wake-up source for low power modes

Access

• To read time and date run:

sudo hwclock

• To set the date run:

sudo systemctl stop systemd-timesyncd
sudo systemctl disable systemd-timesyncd
sudo timedatectl set-local-rtc yes # do not write system time to the RTC
sudo hwclock --set --date="2020-01-01 12:00:00"

Watchdog

By default watchdog is not configured.

systemctl show | grep RuntimeWatchdog

RuntimeWatchdogUSec=0

The value RuntimeWatchdogUSec=0 means that no watchdog device is opened, configured, or pinged

Watchdog configuration

• Edit /etc/systemd/system.conf file to configure watchdog related parameters, in particular RuntimeWatchdogSec and ShutdownWatchdogSec.

the `#` comment sign should be removed from the relevant line in the file.

RuntimeWatchdogSec - specifies the watchdog timeout for runtime services that are actively running during normal system operation. The value is in seconds and should be set to a positive integer.

ShutdownWatchdogSec - specifies the watchdog timeout for the shutdown process, insuring the system doesn't hang indefinitely during shutdown. The value is in seconds and should be set to a positive integer.

• run:

systemctl daemon-reexec

• Verify watchdog configuration. e.g. if you have set RuntimeWatchdogSec=10:

 systemctl show | grep RuntimeWatchdog

RuntimeWatchdogUSec=10s

Watchdog testing

• Run the following command to simulate kernel panic:

echo "c" | sudo tee -a /proc/sysrq-trigger

• As a result, the watchdog is not fed and the system reboots after the value of RuntimeWatchdogSec

Low Power Modes

IOT-LINK supports the following low-power modes:

• Sleep mode - RAM content is preserved, and the system will quickly wake up into the operating system.
• Power-off mode - The system will restart into a clean boot.

Wake-up source:

• Timer alarm set in internal RTC (rtc1)

Only the internal RTC (rtc1) can be used for the wake-up alarm. Main DC power must be present to preserve alarm settings.

Low power mode examples

• Sleep mode with exit by RTC wake-up call:

sudo rtcwake --device /dev/rtc1 -s 5 -m mem

• Power-off mode with boot on RTC wake-up call:

sudo rtcwake --device /dev/rtc1 -s 60 -m off # system reboots after 60 seconds.

CPU temperature

• i.MX93 SoC features an internal temperature sensor.
• To read the current CPU temperature, run:

cat /sys/class/thermal/thermal_zone0/temp