View source for IOT-DIN-IMX8PLUS: Debian Linux: I/O Modules Guide

= Overview =
IOT-DIN-IMX8PLUS supports up to eight I/O Expansion Modules that can be stacked with the main gateway in order to extend the feature set of the system.
A gateway assembly includes one gateway (the left most unit) and multiple I/O Expansion modules. Module stacking is done from left to right. Up to 8 I/O Expansion Modules can be supported in one gateway assembly. 
The modules are interconnected using Compulab’s proprietary StackLink expansion connector that extends a series of the IOT-DIN-IMX8PLUS interfaces, creating a chain of peripherals.

=== I/O Expansion Modules Stacking Rules ===
* There can be up-to 8 I/O Expansion Modules in one assembly
* IFM-WB modules can only be installed in position A (next to main gateway)
* There can be up-to 3 (in total) modules of types IFM-RS485, IFM-RS232, IFM-WB
* There can be up-to 4 IFM-DI8O8 modules
* There can be only 1 IFM-ADC8 module

= I/O Modules Configuration =
I/O expansion  modules are managed as a front-plane of virtual slots that map device access files to physical I/O modules per their positions in the stack.<br>
During O/S boot IOT-DIN-IMX8PLUS automatically runs the StackLink configurator script that detects I/O modules and configures the virtual device files used to address the hardware.<br>
The script creates the IFM front-plane file directory that includes type and access files for all populated stack slots.

== IFM Front-Plane ==

During O/S boot the StackLink configurator script creates the IFM front-plane file directory that includes type and access files for all populated stack slots (from A to last populated slot).

<pre>
/run/iotdin-imx8p/stack/frontplane
</pre>
'''Front-plane directory structure'''

Example I/O modules stack:

<pre>

+----------+-------+-------+-------+-------+
|  Slot #  |   A   |   B   |   C   |   D   |
+----------+-------+-------+-------+-------+
| IFM Type | ADC8  | DI8O8 | RS485 | RS232 |
+----------+-------+-------+-------+-------+
</pre>

Front-plane file directory:

<pre>
/run/iotdin-imx8p/stack/frontplane
|-- A
|   |-- access
|   |   |-- adc0 -> /sys/bus/iio/devices/iio:device0
|   |   `-- adc1 -> /sys/bus/iio/devices/iio:device1
|   `-- type.ADC8
|-- B
|   |-- access
|   |   |-- di.map
|   |   |-- do.map
|   |   `-- gpiochip -> /dev/gpiochip6
|   `-- type.DI8O8
|-- C
|   |-- access
|   |   |-- tty0 -> /dev/ttyIFM_RSx_0_0
|   |   |-- tty1 -> /dev/ttyIFM_RSx_0_1
|   |   |-- tty2 -> /dev/ttyIFM_RSx_0_2
|   |   `-- tty3 -> /dev/ttyIFM_RSx_0_3
|   `-- type.RS485
`-- D
    |-- access
    |   |-- tty0 -> /dev/ttyIFM_RSx_1_0
    |   |-- tty1 -> /dev/ttyIFM_RSx_1_1
    |   |-- tty2 -> /dev/ttyIFM_RSx_1_2
    |   `-- tty3 -> /dev/ttyIFM_RSx_1_3
    `-- type.RS232

</pre>

==  Stack Detection Status  ==
StackLink configurator script provides indication of I/O modules stack detection status using IOT-DIN-IMX8PLUS power LED:
{| class="wikitable" style="text-align:left;"
|-
| align="center" | '''''Power LED'''''
| align="center" | '''Status'''
| align="center" | '''Remarks'''
|-
| align="" |''Blinking Blue''
| align="" | Recognized and valid configuration
| align="" | Normal operation
|-
| align="" |''Blinking Amber''
| align="" | Unrecognized I/O module or invalid configuration
| align="" | Check the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#Stack_Detection_Info|log]] for details
|-


|}

==  Stack Detection Info  ==

StackLink configurator script stores stack detection info log in the following designated location:
<!--
<pre>
/run/iotdin-imx8p/log/iotdin-imx8p.stack.log*
</pre>
-->
<pre>
/run/iotdin-imx8p/log/iotdin-imx8p.stack.log.<YYYYMMDD_HHMMSS>
</pre>

== Stack Troubleshooting ==
<br>
{{Warning|DO NOT attach or detach I/O Expansion modules while the gateway is connected to DC power! Disconnect all power sources from the gateway before attaching or detaching I/O modules.}}

In case of invalid IFM stack status:
# Check the stack detection log
# Double check if a desired stack conforms the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Expansion_Modules_Stacking_Rules | Stacking Rules]]
# Verify proper mechanical attachment of modules
# Contact technical support

== IFM Backplane ==
<br>
<code>/run/iotdin-imx8p/stack/backplane</code> directory stores the system information about the physical hardware devices installed in the stack. These files should not be altered.

= IFM-DI8O8 =
IFM-DI8O8 module provides an isolated block of eight digital inputs and a block of eight digital outputs.<br>
During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed IFM-DI8O8 modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Modules_Configuration|Configuration chapter]].<br>

Use '''diodetect''' command to get an overview of all available Digital Inputs and Outputs:
<pre>
compulab@compulab-imx8mp:~$ /opt/iotdin-imx8p/shell/diodetect
Main Gateway:   DI2O2   (2x DI; 2x DO)
Stack Slot B:   DI8O8   (8x DI; 8x DO)
</pre> 
Use '''dioget''' and '''dioset''' commands to access digital inputs and digital outputs.<br>
It is recommended to set the following alias for more convenient work:
<pre>compulab@compulab-imx8mp:~$ dioget=/opt/iotdin-imx8p/shell/dioget</pre>
<pre>compulab@compulab-imx8mp:~$ dioset=/opt/iotdin-imx8p/shell/dioset</pre>

== Reading Digital Inputs ==
Setup alias for more convenient work:
<pre>compulab@compulab-imx8mp:~$ dioget=/opt/iotdin-imx8p/shell/dioget</pre>

<pre>
compulab@compulab-imx8mp:~$ sudo ${dioget} -h
Usage: dioget [options] <command>

Read digital input state from a Digital I/O (DIO) module

Command:
 -m <module> <offset>
        module: DIO module location:
            m|M - Main Gateway
            a|A - Virtual slot A
            ...
            h|H - Virtual slot H
        offset: input pin offset: <0..MaxOffset>
Options:
 -h:    display this help and exit
</pre>

'''Example'''<br>
Read state of input pin '''IN_4''' on IFM-DI8O8 installed in slot B:
<pre>
compulab@compulab-imx8mp:~$ sudo ${dioget} -m B 4
</pre>

== Setting Digital Outputs ==
Setup alias for more convenient work:
<pre>compulab@compulab-imx8mp:~$ dioset=/opt/iotdin-imx8p/shell/dioset</pre>

<pre>
compulab@compulab-imx8mp:~$ sudo ${dioset} -h
Usage: dioset [options] <command>

Set the digital output state of a Digital I/O (DIO) module

Command:
 -m <module> <offset>  <state>
        module: DIO module location:
            m|M - Main Gateway
            a|A - Virtual slot A
            ...
            h|H - Virtual slot H
        offset: output pin offset: <0..MaxOffset>
        state:  output pin state to be set: <0|1>
Options:
 -h:    display this help and exit
</pre>

'''Example'''<br>
Setting output pin '''OUT_4''' to HIGH state on IFM-DI8O8 installed in slot B:
<pre>
compulab@compulab-imx8mp:~$ sudo ${dioset} -m B 4 1
</pre>

= IFM-ADC8 =
IFM-ADC8 provides eight single-ended analog input channels (0-7), divided into two blocks of 4. Inputs operate between 0-10V or 4-20mA ranges for use with industrial sensors. Each block can be set into current or voltage input mode via jumper.<br>

During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed I/O modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Modules_Configuration|Configuration chapter]].<br>

'''Example'''<br>
Рead a detected value of channel '''5''' of IFM-ADC8 module installed in slot '''A''':<br>
<pre>
compulab@compulab-imx8mp:~$ X=5 ; slot=A
compulab@compulab-imx8mp:~$ sudo cat /run/iotdin-imx8p/stack/frontplane/${slot}/access/adc$((X/4))/in_voltage$((X%4))_raw
</pre>
<!--
= IFM-ADC =
IFM-ADC8 provides eight single-ended analog input channels, divided into two blocks of 4. Inputs operate between 0-10V or 4-20mA ranges for use with industrial sensors. Each block can be set into current or voltage input mode via jumper.<br>

During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed I/O modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS: Debian Linux: I/O Modules Guide#Configuration|Configuration chapter]].<br>

Use the following commands to read the detected values:<br>
(table is for the IFM-ADC in stack location '''A''')
{| class="wikitable" style="text-align:center;"
|+
! Channel
! Access File
|-
| 1
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc0/in_voltage0_raw
|-
| 2
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc0/in_voltage1_raw
|-
| 3
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc0/in_voltage2_raw
|-
| 4
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc0/in_voltage3_raw
|-
| 5
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc1/in_voltage0_raw
|-
| 6
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc1/in_voltage1_raw
|-
| 7
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc1/in_voltage2_raw
|-
| 8
| ../run/iotdin-imx8p/stack/frontplane/A/access/adc1/in_voltage3_raw
|}
-->

= IFM-RS485 =
IFM-RS485 I/O module provides four half-duplex RS485 ports.</br>
During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed I/O modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Modules_Configuration|Configuration chapter]].<br>

===Example===
For an IFM-RS485 module installed in slot '''C''' the configurator script will create the following access files:

<pre>
/run/iotdin-imx8p/stack/frontplane/
|-- C
|   |-- access
|   |   |-- tty0
|   |   |-- tty1
|   |   |-- tty2
|   |   `-- tty3
|   `-- type.RS485
</pre>

Use <code>/run/iotdin-imx8p/stack/frontplane/C/access/tty'''X'''</code> to access port #'''X'''

= IFM-RS232 =

IFM-RS232 I/O module provides four 2-wire RS232 ports.</br>
During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed I/O modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Modules_Configuration|Configuration chapter]].<br>

===Example===
For an IFM-RS232 module installed in slot D the configurator script will create the following access files: 

<pre>
/run/iotdin-imx8p/stack/frontplane/
|-- D
|   |-- access
|   |   |-- tty0
|   |   |-- tty1
|   |   |-- tty2
|   |   `-- tty3
|   `-- type.RS232
</pre>
Use <code>/run/iotdin-imx8p/stack/frontplane/D/access/tty'''X'''</code> to access port #'''X'''

= IFM-WB =

IFM-WB I/O module features one 802.11ax WiFi and one Bluetooth 5.3 BLE interfaces.</br>
During O/S boot IOT-DIN-IMX8PLUS will automatically detect installed I/O modules and create necessary access files in the front-plane directory. For additional details please refer to the [[IOT-DIN-IMX8PLUS:_Debian_Linux:_I/O_Modules_Guide#I.2FO_Modules_Configuration|Configuration chapter]].<br>
{{Note|IFM-WB module can only be installed in position A (next to main gateway)}}

For an IFM-WB module installed in slot A the configurator script will create the following access files: 
<pre>
/run/iotdin-imx8p/stack/frontplane/
|-- A
|   |-- access
|   |   |-- bluetooth -> /sys/class/bluetooth/hci0
|   |   `-- wlan -> /sys/class/net/wlan0
|   `-- type.WB
</pre>

=== Example ===
* Display WiFi network interface info
<pre>
compulab@compulab-imx8mp:~$ wlan=$(basename $(readlink -f /run/iotdin-imx8p/stack/frontplane/A/access/wlan))
compulab@compulab-imx8mp:~$ sudo ifconfig ${wlan}
compulab@compulab-imx8mp:~$ sudo iwconfig ${wlan}
</pre>
* Display Bluetooth interface info
<pre>
compulab@compulab-imx8mp:~$ bt=$(basename $(readlink -f /run/iotdin-imx8p/stack/frontplane/A/access/bluetooth))
compulab@compulab-imx8mp:~$ hciconfig ${bt}
</pre>

== WiFi ==
=== Enable/Disable WiFi Interface ===
* To enable WiFi interface:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli radio wifi on</pre>
* To disable WiFi interface:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli radio wifi off</pre>

=== Network Scanning ===
* Sample WiFi scanning:
:<pre>compulab@compulab-imx8mp:~$ nmcli dev wifi list</pre>
:The output will show the list of Access Points and Ad-Hoc cells in range.

=== Connecting to Access Point ===
In the following example:
* Replace <SSID> and <PASSWORD> with the actual access point parameters:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli device wifi connect <SSID> password <PASSWORD> name WifiCon</pre>
* Disconnect wireless network:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli connection down WifiCon</pre>
* Connect wireless network again:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli connection up WifiCon</pre>

=== Creating Access Point ===
{{Note|Debian 12<br>ipv4 forwarding must be turned on manually}}
* Enable port forwarding:
:<pre>compulab@compulab-imx8mp:~$ sudo sed -i 's/^#\(net.ipv[4,6].*forward\)/\1/' /etc/sysctl.conf</pre>

* Enable wireless AP (replace ''<SSID>'' and ''<PASSWORD>'' with desired access point parameters):
:<pre>sudo nmcli device wifi hotspot ssid <SSID> password <PASSWORD> con-name HotspotCon</pre>
* Disable wireless AP:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli connection down HotspotCon</pre>
* Enable wireless AP again:
:<pre>compulab@compulab-imx8mp:~$ sudo nmcli connection up HotspotCon</pre>