IOT-LINK: 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.

Product serial number, configuration and other information is stored on the boards' EEPROMs.

Device Serial Number and Configuration

Product information is stored in on-board EEPROM.

• To read from SoM run:

eeprom-util read 0 0x50

• To read from base board run:

eeprom-util read 2 0x50

Camera

Example of using 2 lane CSI camera module: e-con e-CAM131_CURB 13MP 4K with real time streaming host.

• Connect the camera to connector P9 on the back panel (by default enclosed under cover)
• Stop booting at u-boot and run

setenv fdtfile iot-link-cam.dtb
boot

on the host and DUT's linux run:

sudo -i 
apt install gstreamer1.0-tools \
            gstreamer1.0-plugins-base \
            gstreamer1.0-plugins-good \
            gstreamer1.0-plugins-bad \
            gstreamer1.0-plugins-ugly \
            gstreamer1.0-rtsp

on the DUT

• Download the mediamtx server for the platform from this page https://github.com/bluenviron/mediamtx/releases

wget --quiet -O - https://github.com/bluenviron/mediamtx/releases/download/v1.14.0/mediamtx_v1.14.0_linux_arm64.tar.gz | sudo tar -C /usr/local/bin -xzf -

• run:

/usr/local/bin/mediamtx /usr/local/bin/mediamtx.yml &>/dev/null &
gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=640,height=480 ! textoverlay text="CLAB IOT-LINK" ! x264enc speed-preset=veryfast tune=zerolatency bitrate=800 ! rtspclientsink location=rtsp://localhost:8554/test

on the host

replace the server IP address and run:

gst-launch-1.0 rtspsrc location=rtsp://server.ip.addr:8554/test latency=0 ! rtph264depay ! avdec_h264 ! videoconvert ! autovideosink

• To learn more please refer to:

https://linuxtv.org/wiki/index.php/V4L_capturing

https://en.wikipedia.org/wiki/GStreamer

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

SIMCOM SIM7672: LTE cat 1 bis

Manual Configuration

• Start minicom at interface:

minicom -D /dev/ttyACM2

• Enable USBNET network:

AT+DIALMODE=0

• Change Operation mode to ECM:

AT$MYCONFIG="USBNETMODE",1

• Set Modem interface to use Public IP:

AT+USBNETIP=1

• Configure APN (replace APN with your provider’s actual APN):

AT+CGDCONT=1,"IP","APN"

• Request an IP (using the renamed interface):

sudo dhclient eth1

If DNS resolution fails, ensure `/etc/resolv.conf` contains valid nameservers:

nameserver 8.8.8.8
nameserver 8.8.4.4

• Device info reported by ModemManager:

mmcli -m 3
  --------------------------------
  General  |                 path: /org/freedesktop/ModemManager1/Modem/3
           |            device id: 62dc27fb3c157a2108ff6cc51e0769f4eb7b126e
  --------------------------------
  Hardware |         manufacturer: SIMCOM INCORPORATED
           |                model: SIM7672G-MNGV
           |    firmware revision: 2374B03SIM767XM5A_M
           |            supported: gsm-umts
           |              current: gsm-umts
           |         equipment id: 865031062591499
  --------------------------------
  System   |               device: /sys/devices/platform/soc@0/4c100000.usb/ci_hdrc.0/usb1/1-1
           |              drivers: cdc_acm, cdc_ether
           |               plugin: generic
           |         primary port: ttyACM2
           |                ports: eth1 (net), ttyACM0 (at), ttyACM1 (ignored), ttyACM2 (at), 
           |                       ttyACM3 (ignored)
  --------------------------------
  Status   |                state: registered
           |          power state: on
           |          access tech: lte
           |       signal quality: 80% (recent)
  --------------------------------
  Modes    |            supported: allowed: any; preferred: none
           |              current: allowed: any; preferred: none
  --------------------------------
  IP       |            supported: ipv4, ipv6, ipv4v6, non-ip
  --------------------------------
  3GPP     |                 imei: 865031062591499
           |          operator id: 42503
           |         registration: home
           | packet service state: attached
  --------------------------------
  3GPP EPS | ue mode of operation: csps-2
  --------------------------------
  SIM      |     primary sim path: /org/freedesktop/ModemManager1/SIM/3
root@iot-link:~# 

Network Interface Naming & Routing

In newer images, the modem uses ECM mode for improved stability, which causes it to appear as `eth1`. This can create a default route that blocks external traffic. To rename the interface to `wwan0` and ensure correct routing, follow these steps:

1. Edit the udev configuration

vi /etc/udev/rules.d/50-net.rules

2. Add the ECM case

SUBSYSTEM=="net", ACTION=="add", DRIVERS=="cdc_ether", NAME="wwan0"

3. Apply changes and reset the modem

sudo udevadm control --reload-rules
sudo udevadm trigger
sudo gpioset 0 22=1 ; sleep 0.3 ; sudo gpioset 0 22=0

After these steps, the interface will appear as `wwan0`, and its configuration in `/etc/network/interfaces.d/wwan0` will handle automatic DHCP.

SIM7672 automation with socat

SET_APN value uses "internet.rl" as an APN name; change it with the one provided by your ISP.

MODEM_NET_IFACE=$(find /sys/devices/platform/soc@0/4c100000.usb/ | awk -F "/" '(/link_mode/)&&($0=$(NF-1))')
SET_APN="AT+CGDCONT=1,\"IP\",\"internet.rl\""
SET_DIALMODE0="AT+DIALMODE=0"
SET_ECM_MODE="AT\$MYCONFIG=\"USBNETMODE\",1"
SET_EXT_IP_MODE="AT+USBNETIP=1"
for AT_COMMAND in ${SET_DIALMODE0} ${SET_ECM_MODE} ${SET_EXT_IP_MODE} ${SET_APN};do
    echo ${AT_COMMAND} | socat - /dev/ttyACM2,crnl
    sleep 1
done
dhclient -i ${MODEM_NET_IFACE}

Telit LE910C4: LTE CAT4

replace APN with your provider’s actual APN

nmcli connection add type gsm ifname '*' con-name CellularCon apn APN

Verify connectivity

sudo ping -c 5 dns.google -I wwan0

Modem Reset

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

• Debian:

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

• Poky:

gpioset -c 0 --toggle 0 22=1; sleep 0.3 ; gpioset -c 0 --toggle 0 22=0

After reset, before configuring, allow about a minute for modem to initialize

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

• Test connection:

sudo ping -c 5 dns.google -I wlan0

• Disconnect wireless network:

sudo nmcli connection down 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

Bluetooth

Before working with Bluetooth, please ensure that Bluetooth antenna is connected to the WiFi / Bluetooth.

Host Controller Interface (HCI) Initialization

• HCI requires no user interaction for being configured. The driver should load automatically unless black listed
  
• Make sure that the Bluetooth driver is loaded:

lsmod | grep btnxpuart

It can be loaded manually:

modprobe btnxpuart

To retrieve information about the Bluetooth interfaces run:

hciconfig hci0 -a

If the HCI device is not running, enable it:

hciconfig hci0 up

HCI Inquire remote devices.

hcitool scan

Bluez5 pairing

Use the command line utility :

bluetoothctl

In its internal command prompt enter:

 power on
 default-agent
 scan on

Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,

[NEW] Device 00:07:A4:F2:B3:CB Motorola HT820

shows a device called "Motorola HT820" and has MAC address 00:07:A4:F2:B3:CB. We will now use that MAC address to initiate the pairing:

 pair 00:07:A4:F2:B3:CB
 trust 00:07:A4:F2:B3:CB
 connect 00:07:A4:F2:B3:CB

If everything works correctly, you now have a separate output device in PulseAudio.
You can now disable scanning again and exit the program:

 scan off
 exit

Playback using PulseAudio

Next example assumes that the device MAC address is 00_07_A4_F2_B3_CB

• Show the PulseAudio device

pactl list cards

• Make sure the active card profile is a2dp_sink. Otherwise switch to it:

pactl set-card-profile 1 a2dp_sink

• Show the PulseAudio sink

pactl list sinks

• Play sound using paplay. Example:

paplay -d bluez_sink.00_07_A4_F2_B3_CB.a2dp_sink /path/to/<audio-file.wav>

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

set command by OS:

• Debian:

DIOSET="sudo gpioset 0"
DIOGET="sudo gpioget 0"

• Yocto:

DIOSET="sudo gpioset -c 0 --toggle 0"
DIOGET="sudo gpioget -c 0"

pin # on terminal block	Drive pin high	Read pin
2	$DIOSET 4=1	$DIOSET 4=0; $DIOGET 16
3	$DIOSET 5=1	$DIOSET 5=0; $DIOGET 17
4	$DIOSET 12=1	$DIOSET 12=0; $DIOGET 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

LEDs control can be accessed via sysfs interface.

Example

• Choose a LED:

LED=green # bi color LED#1
LED=red # bi color LED#1
LED=amber # bi color LED#2
LED="power-blue" # bi color LED#2 , used by default to indicate system state

• 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

• In Debian only, 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

Detect Devices

ls /dev/watchdog? # Expected: watchdog0, watchdog1.

Configure systemd Watchdog

vi /etc/systemd/system.conf # and set (and uncomment), for example:

RuntimeWatchdogSec=3
ShutdownWatchdogSec=10
WatchdogDevice=/dev/watchdog0 

RuntimeWatchdogSec - timeout for runtime services. The value is in seconds (a positive integer).

ShutdownWatchdogSec - timeout for the shutdown process, ensuring the system doesn't hang indefinitely during shutdown. The value is in seconds (a positive integer).

Reload config:

systemctl daemon-reexec

Verify

systemctl show | grep Watchdog

Test

Trigger panic:

echo c > /proc/sysrq-trigger

System should reboot after configured timeout.

Repeat test with each watchdog device.

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