View source for IOT-GATE-RPI4: Raspberry Pi OS: How-To Guide

= Overview =
IOT-GATE-RPI4 runs standard [https://www.raspberrypi.com/software/operating-systems/ 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 [https://www.raspberrypi.com/news/raspberry-pi-bullseye-update-april-2022/ 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
{{Note| 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 [[IOT-GATE-RPI4:_Raspberry_Pi_OS:_How-To_Guide#Raspberry_Pi_Setup_Wizard|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 [https://manpages.debian.org/testing/modemmanager/mmcli.8 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.
<pre>
pi@raspberrypi:~$ sudo nmcli connection add type gsm ifname '*' con-name CellularCon apn ISP-APN
</pre>
* Connect cellular network
<pre>
pi@raspberrypi:~$ sudo nmcli connection up CellularCon
</pre>
* Disconnect cellular network
<pre>
pi@raspberrypi:~$ sudo nmcli connection down CellularCon
</pre>

= GPS =
IOT-GATE-RPI4 features an optional GPS interface implemented with the cellular modem module.</br>
== 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.</br>
GPS antenna should be attached to the '''AUX''' SMA connector on the gateway.<br>
{{Note|GPS antenna should be positioned at least 1m away from the gateway}}

== Using GPS ==
The [https://manpages.debian.org/jessie/gpsd-clients/cgps.1.en.html cgps] client can be used to display the GPS information. <br>
The [https://manpages.debian.org/testing/modemmanager/mmcli.8 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.
<pre>
root@raspberrypi:~# mmcli -m 0
</pre>

The cgps client utility depends on the gpsd daemon (starts automatically after the initialization command is performed).
* Initialization of the GPS interface:
<pre>
root@raspberrypi:~# sed -i "/^DEVICES=.*/c\DEVICES=\"/dev/ttyUSB1\"" /etc/default/gpsd
</pre>

* Enable the GPS with the following AT commands:
<pre>
root@raspberrypi:~# echo AT+QGPS= 1 | socat - /dev/ttyUSB2,crnl
</pre>
* 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. 

<pre>
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                ││                                 │
└───────────────────────────────────────────┘└─────────────────────────────────┘
</pre>

* GPS can be disabled with the following AT commands:
<pre>
root@raspberrypi:~# echo AT+QGPS= 0 | socat - /dev/ttyUSB2,crnl
</pre>

= WiFi =
Please refer to the [https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-networking 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 [https://www.raspberrypi.com/documentation/computers/config_txt.html config.txt] to use the IOT-GATE-RPI4 external antenna with the WiFi module.
<pre>
dtparam=ant2
</pre>

= 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)

{{Note|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 [[IOT-GATE-RPI4 I/O Configuration|''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:
<pre>
pi@raspberrypi:~$ sudo ip link set canB type can bitrate 1000000
</pre>
* Enable the CAN interface:
<pre>
pi@raspberrypi:~$ sudo ip link set canB up
</pre>

==== Software installation ====
Use the following command to install ''can-utils'' if not installed:
<pre>
pi@raspberrypi:~$ sudo apt-get install --no-install-recommends can-utils
</pre>

==== Send/Receive packets ====
Use ''cansend'' and ''candump'' utilities to send and receive packets via CAN interface. 
* Send standard CAN frame (on the first device):
<pre>
pi@raspberrypi:~$ sudo cansend canB 111#1122334455667788
</pre>

* Send extended CAN frame (on the first device):
<pre>
pi@raspberrypi:~$ sudo cansend canB 11111111#1122334455667788
</pre>

* CAN frames (extended mode) generator, random payload, interval between two successive flames 50 msec:
<pre>
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
...
</pre>

* Dump all received data frames as well as error frames (on the second device):
<pre>
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
...
</pre>

== 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 [[IOT-GATE-RPI4 I/O Configuration|''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 [[IOT-GATE-RPI4 I/O Configuration|''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. 
<pre>
pi@raspberrypi:~$ wget https://www.modbusdriver.com/downloads/modpoll.tgz -P /tmp/
...
pi@raspberrypi:~$ sudo tar -xvf /tmp/modpoll.tgz -C /opt/
...
</pre>

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

==== Read data ====

* Read temperature once:
<pre>
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
</pre>

* Poll temperature:
<pre>
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
...
</pre>

* Read humidity once:
<pre>
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
</pre>

* Poll humidity:
<pre>
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
...
</pre>

* Read temperature & humidity once:
<pre>
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
</pre>

* Poll temperature & humidity:
<pre>
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
...
</pre>

* Read slave address, baudrate, temperature & humidity corrections:
<pre>
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
</pre>

== 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.<br>
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.
{{Note|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 [[IOT-GATE-RPI4 I/O Configuration|''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|IOT-GATE-RPI4 OS Configuration Layer]].<br>

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:
<pre>
pi@raspberrypi:~$ iotg-rpi4-dio -s cd -o 2 1
</pre>

* Read IN1 pin state (LO):
<pre>
pi@raspberrypi:~$ iotg-rpi4-dio -s cd -i 1
0
</pre>

= RTC =
IOT-GATE-RPI4 RTC is implemented with the AM1805 real-time clock (RTC) chip.</br>
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:
<pre>
pi@raspberrypi:~$ sudo hwclock
2021-12-17 18:49:47.763197+02:00
</pre>

To set the date and write it into the RTC do the following: 
<pre>
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
</pre>

== Enable/Disable RTC via device tree overlay ==
To enable/disable IOT-GATE-RPI4 RTC add/remove(comment) the following string in the [https://www.raspberrypi.com/documentation/computers/config_txt.html config.txt] file:
<pre>
dtoverlay=iotg-rpi4/iotg-rpi4-rtc
</pre>

= Watchdog =
IOT-GATE-RPI4 watchdog function is implemented with the AM1805 RTC chip.</br>
By default watchdog is installed and pre-configured in the IOT-GATE-RPI4 OS Configuration Layer provided by CompuLab.
<pre>
pi@raspberrypi:~$ sudo systemctl show | grep -i watchdog
RuntimeWatchdogUSec=10s
ShutdownWatchdogUSec=2min
ServiceWatchdogs=yes
</pre>

== 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:
<pre>
pi@raspberrypi:~$ sudo su
root@raspberrypi:/home/pi# echo "c" > /proc/sysrq-trigger
</pre>
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.
{{Note|TPM is mutually exclusive with I/O slot '''D'''}}
== Enable/Disable TPM module ==
To enable/disable TPM module please use [[IOT-GATE-RPI4 I/O Configuration|''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''
:<pre>pi@raspberrypi:~$ gpioset 3 12=0</pre>
:* Set Red ''OFF''
:<pre>pi@raspberrypi:~$ gpioset 3 12=1</pre>
:* Set Green ''ON''
:<pre>pi@raspberrypi:~$ gpioset 3 13=0</pre>
:* Set Green ''OFF''
:<pre>pi@raspberrypi:~$ gpioset 3 13=1</pre>

* User LED2
:* Set Red ''ON''
:<pre>pi@raspberrypi:~$ gpioset 3 14=0</pre>
:* Set Red ''OFF''
:<pre>pi@raspberrypi:~$ gpioset 3 14=1</pre>
:* Set Green ''ON''
:<pre>pi@raspberrypi:~$ gpioset 3 15=0</pre>
:* Set Green ''OFF''
:<pre>pi@raspberrypi:~$ gpioset 3 15=1</pre>

[[Category:Linux]]
[[Category:IOT-GATE-RPI4]]