IOT-GATE-RPI4: Raspberry Pi OS: How-To Guide

Overview

IOT-GATE-RPI4 runs standard Raspberry Pi OS with an additional IOT-GATE-RPI4 OS Configuration Layer that sets-up the gateway peripheral devices and provides useful tools for device configuration and management.

Raspberry Pi Setup Wizard

The Raspberry Pi setup wizard runs on the first boot, and asks user to:

• Configure regional settings including keyboard type
• Setup WiFI connection
• Create a user account
• Install software updates

Working through the wizard is no longer optional. A user account must be created to allow logging in to the desktop.

Connection and Login

Create a user account as described above and use its username and password to login into the Raspberry Pi system via serial console or ssh.

Cellular Modem

IOT-GATE-RPI4 cellular interface is implemented with a mini-PCIe cellular modem module and a nano-SIM socket. To set up IOT-GATE-RPI4 for cellular functionality, install an active SIM card into the front panel nano-SIM socket U20. The cellular module should be installed into mini-PCIe socket P9.

ModemManager

The ModemManager can be used to log into almost any Internet Service Provider with simple configuration setup.

In the following example:

• Replace ISP-APN with the APN name of the cellular provider.

pi@raspberrypi:~$ sudo nmcli connection add type gsm ifname '*' con-name CellularCon apn ISP-APN

• Connect cellular network

pi@raspberrypi:~$ sudo nmcli connection up CellularCon

• Disconnect cellular network

pi@raspberrypi:~$ sudo nmcli connection down CellularCon

GPS

IOT-GATE-RPI4 features an optional GPS interface implemented with the cellular modem module.

GPS antenna

GPS antenna is required for GPS operation. GPS antenna is not included with IOT-GATE-RPI4. Any active GPS antenna with a male SMA connector can be used with IOT-GATE-RPI4.
GPS antenna should be attached to the AUX SMA connector on the gateway.

GPS antenna should be positioned at least 1m away from the gateway

Using GPS

The cgps client can be used to display the GPS information.
The ModemManager can be used to check the modem status. For example, the following command shows the presence of the modem and the id of its interfaces.

root@raspberrypi:~# mmcli -m 0

The cgps client utility depends on the gpsd daemon (starts automatically after the initialization command is performed).

• Initialization of the GPS interface:

root@raspberrypi:~# sed -i "/^DEVICES=.*/c\DEVICES=\"/dev/ttyUSB1\"" /etc/default/gpsd

• Enable the GPS with the following AT commands:

root@raspberrypi:~# echo AT+QGPS= 1 | socat - /dev/ttyUSB2,crnl

• Full power cycle is required before using GPS. Shut down the gateway, remove main DC power for at least 20 sec and restart.
• Start the cgps client to display GPS information.

The synchronization process might take a few minutes.

root@raspberrypi:~# cgps
┌───────────────────────────────────────────┐┌─────────────────────────────────┐
│    Time:       2022-05-04T14:13:30.000Z   ││PRN:   Elev:  Azim:  SNR:  Used: │
│    Latitude:    32.65985123 N             ││  71    29    123    22      Y   │
│    Longitude:   35.10027205 E             ││  85    27    047    22      Y   │
│    Altitude:   102.700 m                  ││                                 │
│    Speed:      0.00 kph                   ││                                 │
│    Heading:    128.7 deg (true)           ││                                 │
│    Climb:      6.00 m/min                 ││                                 │
│    Status:     3D FIX (53 secs)           ││                                 │
│    Longitude Err:   n/a                   ││                                 │
│    Latitude Err:    n/a                   ││                                 │
│    Altitude Err:    +/- 18 m              ││                                 │
│    Course Err:      n/a                   ││                                 │
│    Speed Err:       n/a                   ││                                 │
│    Time offset:     -3.682                ││                                 │
│    Grid Square:     KM72np                ││                                 │
└───────────────────────────────────────────┘└─────────────────────────────────┘

• GPS can be disabled with the following AT commands:

root@raspberrypi:~# echo AT+QGPS= 0 | socat - /dev/ttyUSB2,crnl

WiFi

Please refer to the Raspberry Pi OS documentation for detailed instruction about configuring WiFi and connecting to Access Point.

Please note, IOT-GATE-RPI4 is pre-configured in the config.txt to use the IOT-GATE-RPI4 external antenna with the WiFi module.

dtparam=ant2

Industrial Interfaces

IOT-GATE-RPI4 implements industrial interfaces with four I/O slots (IE) that can be fitted with up-to four different I/O modules. Slots are referred to as A, B, C and D.

Available I/O modules types:

• CAN bus
• RS232 (2-wire)
• RS485 (half duplex)
• Digital I/O (4x DI + 4x DO)

IOT-GATE-RPI4 industrial I/O signals are routed to Industrial I/O Connector (P17)

Please refer to Industrial I/O Connector pin-out for more details.

CAN

CAN function is implemented with MCP2518FD controller interfaced with Raspberry Pi CM4 SPI ports. CAN modules can be installed in any I/O slot: A, B, C and D. Up to four CAN modules can be installed simultaneously.

Enable/Disable CAN module

To enable/disable CAN module on a specific industrial I/O slot please use iotg-rpi4-config utility.

Configuration and Access

Once properly enabled on a specific I/O slot, CAN interface can be accessed in Linux via canX network interface, where X is a slot name: A, B, C, D

The following example demonstrates how to configure and use CAN module installed into industrial I/O slot B.

CAN interface configuration

• Configure the CAN interface bit-rate to 1 Mbits/sec:

pi@raspberrypi:~$ sudo ip link set canB type can bitrate 1000000

• Enable the CAN interface:

pi@raspberrypi:~$ sudo ip link set canB up

Software installation

Use the following command to install can-utils if not installed:

pi@raspberrypi:~$ sudo apt-get install --no-install-recommends can-utils

Send/Receive packets

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

• Send standard CAN frame (on the first device):

pi@raspberrypi:~$ sudo cansend canB 111#1122334455667788

• Send extended CAN frame (on the first device):

pi@raspberrypi:~$ sudo cansend canB 11111111#1122334455667788

• CAN frames (extended mode) generator, random payload, interval between two successive flames 50 msec:

pi@raspberrypi:~$ sudo cangen -g 50 -e -D r -v canB
...
  canB  1E5137F4#0F.4D.8B.7A.25.4D.DB.21
  canB  1B6C965C#8C.DE.96.58.69.5F.D5.26
  canB  1BD23086#8D.DB.C4.3E.81.57.BA.34
  canB  127B2322#F4.16.31.2E.34.04.62
  canB  1A6366DB#A8.73.C0.37.D8
  canB  03620EE4#
  canB  023AC34D#C6.08.BD.2A.04.B3.BF.43
  canB  1C19AD2E#09.C1.B3.26.23.E5.6A.5A
  canB  02BCA994#48.32.46.7C.F0.3F.29.1E
  canB  08104C67#59.9F.FE.44
  canB  1C280582#6F.D4.9C.38.A5.28.A3
  canB  0BC219EE#D9.2C.05
  canB  04AA80B8#A1.93
  canB  1A3E2392#AD.98
  canB  0025950E#E3.99.38
...

• Dump all received data frames as well as error frames (on the second device):

pi@raspberrypi:~ $ sudo candump any,0:0,#FFFFFFFF
...
  canB  0CC89C1A   [1]  51
  canB  0A097EFB   [0] 
  canB  02B59BD5   [5]  68 6F 47 64 D9
  canB  03743A1E   [7]  FA BF E4 38 3E BF C8
  canB  13C9B644   [8]  30 FB 60 6F E1 FC 55 65
  canB  018A8975   [0] 
  canB  0C9C8179   [0] 
  canB  011F5D90   [6]  65 DB DD 5A AA F9
  canB  07B7FD18   [6]  CC 96 26 1D 13 7C
  canB  1FBD7177   [8]  69 BF 8D 1E 4C 0D 73 02
  canB  107A7E2D   [2]  25 D3
  canB  12B9E279   [8]  89 77 B7 54 BD 98 83 06
  canB  112A44EA   [8]  9E 95 D9 6B 60 CE B4 52
  canB  0ADF9869   [3]  C8 A0 27
  canB  1580C274   [5]  B2 7A F7 43 04
  canB  06DDDBCC   [7]  AF 19 88 04 E4 D8 95
  canB  127FA5CE   [8]  F7 54 57 20 45 17 3D 12
  canB  09A37893   [0] 
  canB  01BA4332   [6]  0B AF 0C 2E AB 25
  canB  180A8AD5   [5]  68 BE F7 5A C0
  canB  06DC994E   [7]  20 9E E9 7B B8 31 BC
...

RS232

RS232 function is implemented with MAX3221 (or compatible) transceiver interfaced with Raspberry Pi CM4 UART ports.

RS232 modules can be installed in any I/O slot: A, B, C and D. Up to four RS232 modules can be installed simultaneously.

Enable/Disable RS232 module

To enable/disable RS232 module on a specific industrial I/O slot please use iotg-rpi4-config utility.

Configuration and Access

Once properly enabled on a specific I/O slot, RS232 interface can be accessed in Linux via ttyRS232_X tty device, where X is a slot name: A, B, C, D.

RS485

RS485 function is implemented with MAX13488 (or compatible) transceiver interfaced with Raspberry Pi CM4 UART ports.

RS485 modules can be installed in any I/O slot: A, B, C and D. Up to four RS485 modules can be installed simultaneously.

Enable/Disable RS485 module

To enable/disable RS485 module on a specific industrial I/O slot please use iotg-rpi4-config utility.

Configuration and Access

Once properly enabled on a specific I/O slot, RS232 interface can be accessed in Linux via ttyRS485_X tty device, where X is a slot name: A, B, C, D.

Modbus RS485

The following example demonstrates how to use RS485 module installed into industrial I/O slot A in a Modbus RS485 Network. IOTG-RPI4 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.

pi@raspberrypi:~$ wget https://www.modbusdriver.com/downloads/modpoll.tgz -P /tmp/
...
pi@raspberrypi:~$ sudo tar -xvf /tmp/modpoll.tgz -C /opt/
...

Device connection

--------------------                                  -------------------------
|                  |                                  |                       |
|                  *--(+)---< <------------- 5V-30V   |        IOTG-RPI4      |
|                  |                                  |                       |
|                  *--(-)---< <-------------- GND     |------  ------------   |
| XY-MD02 (RS485)  |                                  |     |==| IE-RS485 |   |
|                  *--(A+)--< <---...---> >---(2)---*-|     |  ------------   |
|                  |                                  | P17 |     Slot A      |
|                  *--(B-)--< <---...---> >---(4)---*-|     |                 |
|                  |                                  |------                 |
--------------------                                  ------------------------- 

Read data

• Read temperature once:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 2 -1 /dev/ttyRS485_A 
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 2, count = 1
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave...
[2]: 255

• Poll temperature:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 2 /dev/ttyRS485_A 
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 2, count = 1
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave... (Ctrl-C to stop)
[2]: 256
-- Polling slave... (Ctrl-C to stop)
[2]: 255
-- Polling slave... (Ctrl-C to stop)
[2]: 256
...

• Read humidity once:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 3 -1 /dev/ttyRS485_A 
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 3, count = 1
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave...
[3]: 684

• Poll humidity:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 1 -r 3 /dev/ttyRS485_A 
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 3, count = 1
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave... (Ctrl-C to stop)
[3]: 568
-- Polling slave... (Ctrl-C to stop)
[3]: 566
-- Polling slave... (Ctrl-C to stop)
[3]: 563
...

• Read temperature & humidity once:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 2 -r 2 -1 /dev/ttyRS485_A                             
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 2, count = 2
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave...
[2]: 258
[3]: 408

• Poll temperature & humidity:

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 3 -c 2 -r 2 /dev/ttyRS485_A 
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC4
Slave configuration...: address = 1, start reference = 2, count = 2
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, input register table

-- Polling slave... (Ctrl-C to stop)
[2]: 258
[3]: 406
-- Polling slave... (Ctrl-C to stop)
[2]: 258
[3]: 406
-- Polling slave... (Ctrl-C to stop)
[2]: 258
[3]: 405
...

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

pi@raspberrypi:~$ /opt/modpoll/arm-linux-gnueabihf/modpoll -b 9600 -p none -t 4 -c 4 -r 258 -1 /dev/ttyRS485_A                          
modpoll 3.10 - FieldTalk(tm) Modbus(R) Master Simulator
Copyright (c) 2002-2021 proconX Pty Ltd
Visit https://www.modbusdriver.com for Modbus libraries and tools.

Protocol configuration: Modbus RTU, FC3
Slave configuration...: address = 1, start reference = 258, count = 4
Communication.........: /dev/ttyRS485_A, 9600, 8, 1, none, t/o 1.00 s, poll rate 1000 ms
Data type.............: 16-bit register, output (holding) register table

-- Polling slave...
[258]: 1
[259]: 9600
[260]: 0
[261]: 0

Digital I/O

Digital I/O module features 4 digital inputs and 4 digital outputs and takes two IE slots. Four digital inputs are implemented with the CLT3-4B digital termination following EN 61131-2. Four digital outputs are implemented with the VNI4140K solid-state relay following EN 61131-2.
Digital I/O modules can be installed into [AB] or [CD] dual slot. Installation to [BC] slot is prohibited! Up to two Digital I/O modules can be installed simultaneously.

Each Digital I/O module requires an external voltage supply up to 24V to be properly connected. Please refer to Industrial I/O Connector pin-out for more details.

Enable/Disable Digital I/O module

To enable/disable Digital I/O module on a specific dual slot please use iotg-rpi4-config utility.

Configuration and Access

Once properly enabled on a specific dual slot, use iotg-rpi4-dio utility to access digital inputs and outputs. The utility is part of IOT-GATE-RPI4 OS Configuration Layer.

The example below shows how to access Digital inputs and outputs of a module configured and installed on [CD] dual slot.

• Drive OUT2 pin HI:

pi@raspberrypi:~$ iotg-rpi4-dio -s cd -o 2 1

• Read IN1 pin state (LO):

pi@raspberrypi:~$ iotg-rpi4-dio -s cd -i 1
0

RTC

IOT-GATE-RPI4 RTC is implemented with the AM1805 real-time clock (RTC) chip.
By default RTC is installed and pre-configured in the IOT-GATE-RPI4 OS Configuration Layer provided by CompuLab.

Accessing and setting the RTC

To access the RTC time and date run:

pi@raspberrypi:~$ sudo hwclock
2021-12-17 18:49:47.763197+02:00

To set the date and write it into the RTC do the following:

pi@raspberrypi:~$ sudo date -s "31 Dec 2021 10:00:00"                                                                                     
Fri Dec 31 10:00:00 IST 2021
pi@raspberrypi:~$ sudo hwclock -w
pi@raspberrypi:~$ sudo hwclock 
2021-12-31 10:00:08.317403+02:00

Enable/Disable RTC via device tree overlay

To enable/disable IOT-GATE-RPI4 RTC add/remove(comment) the following string in the config.txt file:

dtoverlay=iotg-rpi4/iotg-rpi4-rtc

Watchdog

IOT-GATE-RPI4 watchdog function is implemented with the AM1805 RTC chip.
By default watchdog is installed and pre-configured in the IOT-GATE-RPI4 OS Configuration Layer provided by CompuLab.

pi@raspberrypi:~$ sudo systemctl show | grep -i watchdog
RuntimeWatchdogUSec=10s
ShutdownWatchdogUSec=2min
ServiceWatchdogs=yes

Watchdog configuration

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

Watchdog testing

Run the following command to simulate kernel panic:

pi@raspberrypi:~$ sudo su
root@raspberrypi:/home/pi# echo "c" > /proc/sysrq-trigger

As a result, the watchdog is not fed and the system reboots after 10 sec.

Trusted Platform Module

IOT-GATE-RPI4 features an optional on-board TPM implemented with Infineon SLB9670XQ2.0 interfaced with CM4 SPI port.

TPM is mutually exclusive with I/O slot D

Enable/Disable TPM module

To enable/disable TPM module please use iotg-rpi4-config utility.

LEDs

IOT-GATE-RPI4 features two user Bi-Color (Red + Green) LEDs controlled via GPIO pins.

• User LED1

• Set Red ON

pi@raspberrypi:~$ gpioset 3 12=0

• Set Red OFF

pi@raspberrypi:~$ gpioset 3 12=1

• Set Green ON

pi@raspberrypi:~$ gpioset 3 13=0

• Set Green OFF

pi@raspberrypi:~$ gpioset 3 13=1

• User LED2

• Set Red ON

pi@raspberrypi:~$ gpioset 3 14=0

• Set Red OFF

pi@raspberrypi:~$ gpioset 3 14=1

• Set Green ON

pi@raspberrypi:~$ gpioset 3 15=0

• Set Green OFF

pi@raspberrypi:~$ gpioset 3 15=1