/strato-pi-max-kernel-module

Strato Pi Max driver kernel module

Primary LanguageCGNU General Public License v3.0GPL-3.0

Strato Pi Max driver kernel module

Raspberry Pi OS Kernel module for Strato Pi Max.

It gives access to all Strato Pi Max functionalities and configuration options via sysfs virtual files.

Compile and Install

For installation on Ubuntu read this.

Make sure your system is updated:

sudo apt update
sudo apt upgrade

If you are using a 32-bit OS, add to /boot/firmware/config.txt (/boot/config.txt in older versions) the following line: [why?]

arm_64bit=0

Reboot:

sudo reboot

After reboot, install git and the Raspberry Pi kernel headers:

sudo apt install git raspberrypi-kernel-headers

Clone this repo:

git clone --depth 1 https://github.com/sfera-labs/strato-pi-max-kernel-module.git

Make and install:

cd strato-pi-max-kernel-module
make clean
make
sudo make install

Compile the Device Tree and install it:

dtc -@ -Hepapr -I dts -O dtb -o stratopimax.dtbo stratopimax.dts
sudo cp stratopimax.dtbo /boot/overlays/

This overlay, amongst the different peripherals, configures the secondary SD interface to use the sdhost controller, so that sdio is available for WiFi on CM units equipped with it.

To load the driver at boot, add to /boot/firmware/config.txt (/boot/config.txt in older versions) the following line:

dtoverlay=stratopimax

Optionally, to be able to use the /sys/class/stratopimax/ files not as super user, create a new group "stratopimax" and set it as the module owner group by adding an udev rule:

sudo groupadd stratopimax
sudo cp 99-stratopimax.rules /etc/udev/rules.d/

and add your user to the group, e.g. for user "pi":

sudo usermod -a -G stratopimax pi

Reboot:

sudo reboot

Usage

After loading the module, you will find all the available devices under the path /sys/class/stratopimax/.

The following paragraphs list all the devices (directories) and properties (files) coresponding to Strato Pi Max's and its expansion boards' features.

You can write and/or read these files to configure, monitor and control your Strato Pi Max. The kernel module will take care of performing the corresponding GPIO or I2C operations.

Some properties corresponds to configuration parameters. Some are permanently saved each time they are changed, so that their value is retained across power cycles. Other are not persistent, i.e. their values are reset to default after a power cycle. To change the default values use the system/config file (see below).

This allows us to have a different configuration during the power up phase, even after an abrupt shutdown. For instance, you may want a short watchdog timeout while your application is running, but it needs to be reset to a longer timeout when a power cycle occurs so that Strato Pi Max has the time to boot and restart your application handling the watchdog heartbeat.

All properties' attributes are summarized here:

Attribute Description
R Readable
W Writable
RC Readable. Cleared when read
WF Writable only when expansion board is off
CS Configuration value, not persisted, unless configuration saved after modification via system/config
CP Configuration value, persisted when written

System - /sys/class/stratopimax/system/

File Description Attr Value Value description
fw_version Firmware version R M.m Major (M) and minor (m) version
config Configuration commands W S Save the current configuration as default to be retained across power cycles
R Restore the factory configuration
sys_errs System errors flags RC MLKJxHGFxDCBA Bitmap (0/1) sequence.
A: system setup failure
B: RP2040 failure
C: RP2040 reset occurred
D: configuration loading error
F: RP2040 I2C master failure
G: RP2040 I2C slave failure
H: RP2040 SPI failure
J: USB ports fault
K: I/O expanders fault (see ioexp_errs)
L: accelerometer fault
M: UPS fault
ioexp_errs I/O expanders errors flags RC GFEDCBA Bitmap (0/1) sequence.
A: I/O expander BU17 fault
B: I/O expander BU21 fault
C: I/O expander BU22 fault
D: I/O expander on expansion board in slot 1 fault
E: I/O expander on expansion board in slot 2 fault
F: I/O expander on expansion board in slot 3 fault
G: I/O expander on expansion board in slot 4 fault

Power cycle - /sys/class/stratopimax/power/

File Description Attr Value Value description
down_enabled Delayed power cycle enabling R W 0 Disabled
1 Enabled
down_delay Shutdown delay from enabling R W CS 1 ... 65535 Value in seconds. Default: 60
off_time Power off duration R W CS 1 ... 65535 Value in seconds. Default: 5
up_delay Power-up delay configuration R W CS 1 ... 65535 Value in seconds. Default: 0
up_mode Power-up mode configuration when power cycle occurring while main power not available (requires UPS expansion board) R W CS M Power up only when main power is restored
A Always: power up even if running on battery, with no main power available
sd_switch SDA/SDB switch configuration on power cycle R W CS 0 Disabled
1 Enabled
pcie_switch PCIE on/off toggle configuration on power cycle R W CS 0 Disabled
1 Enabled

Watchdog - /sys/class/stratopimax/watchdog/

File Description Attr Value Value description
enabled Watchdog enabling R W CS 0 Disabled
1 Enabled
timeout Watchdog timeout configuration R W CS 1 ... 65535 Value in seconds. Default: 60
down_delay Automatic power cycle delay configuration when watchdog timeout expires R W CS 1 ... 65535 Value in seconds. Default: 60
sd_switch SDA/SDB switch configuration on watchdog reset, if no heartbeat is detected R W CS 0 Disabled
1 ... 65535 Number of resets before switching occours
pcie_switch PCIE enable configuration on watchdog reset, if no heartbeat is detected R W CS 0 Disabled
1 ... 65535 Number of resets before on/off toggling occours
heartbeat Watchdog heartbeat update W 1 Update heartbeat
expired Watchdog timeout state R 0 Not expired
1 Expired

Button - /sys/class/stratopimax/button/

File Description Attr Value Value description
status Button state R 0 Not pressed
1 Pressed
count Button presses counter R 0 ... 255 Rolls back to 0 after 255

Buzzer - /sys/class/stratopimax/buzzer/

File Description Attr Value Value description
beep Buzzer beep control W CS 0 Off
1 Steady on
T_ON T_OFF Continuos beep T_ON milliseconds on, T_OFF milliseconds off
T_ON T_OFF REPS Beep REPS times T_ON milliseconds on, T_OFF milliseconds off
tone Buzzer beep tone R W CS 0 ... 65535 Value in Hz

LEDs - /sys/class/stratopimax/led/

File Description Attr Value Value description
red Red LED control W CS 0 Off
1 Steady on
T_ON T_OFF Continuos blink T_ON milliseconds on, T_OFF milliseconds off
T_ON T_OFF REPS Blink REPS times T_ON milliseconds on, T_OFF milliseconds off
green Green LED control W CS 0 Off
1 Steady on
T_ON T_OFF Continuos blink T_ON milliseconds on, T_OFF milliseconds off
T_ON T_OFF REPS Blink REPS times T_ON milliseconds on, T_OFF milliseconds off

USB - /sys/class/stratopimax/usb/

File Description Attr Value Value description
usb1_enabled USB1 enabling R W CS 0 Disabled
1 Enabled
usb1_err USB1 fault R 0 OK
1 Fault
usb2_enabled USB2 enabling R W CS 0 Disabled
1 Enabled
usb2_err USB2 fault R 0 OK
1 Fault

SD Cards Switch - /sys/class/stratopimax/sd/

File Description Attr Value Value description
sd_main_enabled Main SD interface enabling R W CS 0 Disabled
1 Enabled
2 Disabled, reset to enabled upon power cycle
sd_sec_enabled Secondary SD interface enabling R W CS 0 Disabled
1 Enabled
2 Enabled, reset to disabled upon power cycle
sd_main_default Main SD power-up routing R W CS A Main SD interface routed to SDA, secondary SD interface to SDB
A Main SD interface routed to SDB, secondary SD interface to SDA
sd_main_routing Main SD routing state R W A Main SD interface routed to SDA, secondary SD interface to SDB
A Main SD interface routed to SDB, secondary SD interface to SDA

PCIE interface - /sys/class/stratopimax/pcie/

File Description Attr Value Value description
enabled PCIE enabling R W 0 Disabled
1 Enabled
enabled_default PCIE power-up enabling R W CP 0 Disabled
1 Enabled

Power Supply Input - /sys/class/stratopimax/power_in/

File Description Attr Value Value description
mon_v Power supply voltage monitor R V Value in mV
mon_i Power supply current drain monitor R V Value in mA

Fan - /sys/class/stratopimax/fan/

File Description Attr Value Value description
temp Fan controller measured temperature R T Value in °C/100
temp_on Temperature threshold for fan activation R W -12800 ... 12750 Value in °C/100, 0.5°C resolution
temp_off Temperature threshold for fan deactivation R W -12800 ... 12750 Value in °C/100, 0.5°C resolution

Accelerometer - /sys/class/stratopimax/accelerometer/

File Description Attr Value Value description
accel_x X-axis acceleration R -32768 ... 32767 Raw value (resolution: 14-bit, full scale: ±2 g)
accel_y Y-axis acceleration R -32768 ... 32767 Raw value (resolution: 14-bit, full scale: ±2 g)
accel_z X-axis acceleration R -32768 ... 32767 Raw value (resolution: 14-bit, full scale: ±2 g)

Secure Element - /sys/class/stratopimax/sec_elem/

File Description Attr Value Value description
serial_num Secure element serial number R HHHHHHHHHHHHHHHHHH HEX value

Expansion Boards

Expansion Boards configuration - /sys/class/stratopimax/exp_boards/

File Description Attr Value Value description
sN_enabled Slot N enabling R W CS 0 Disabled
1 Enabled
sN_type Slot N expansion board type R 2 Uninterruptible Power Supply
3 CAN and dual RS-485
4 RS-232 and RS-485
5 Industrial digital I/O

Below are the devices corresponding to each expansion board typologies.

For expansion boards that can be installed on multiple slots, devices names have a _s<n> suffix denoting their slot number (1 to 4).

Uninterruptible Power Supply (UPS) Expansion Board

Digital inputs - /sys/class/stratopimax/ups/

File Description Attr Value Value description
enabled UPS enabling R W CS 0 Disabled
1 Enabled
battery_v UPS battery voltage configuration R W CS 12000 12 V battery
24000 24 V battery
vso VSO power supply output control R W CS 0 Disabled
1 Enabled
battery_capacity UPS battery capacity configuration R W CS 100 ... 60000 Value in mAh. Default: 800
battery_i_max UPS battery maximum charging current while at maximum voltage configuration R W CS 0 Value automatically derived from capacity (default)
1 ... 65535 Value in mA. The automatically derived limit still applies if lower than this value
power_delay Automatic power cycle timeout configuration when main power source not available R W CS 0 Disabled
1 ... 65535 Value in seconds
battery Power source state R 0 Running on main power
1 Running on battery
status UPS status R 0 Idle
1 Detecting battery
2 Battery disconnected
4 Charging battery
5 Battery charged
6 Running on battery
8 Battery over-voltage error
9 Battery under-voltage error
10 Charger damaged
11 Unstable
charger_mon_v Battery charger output voltage monitor R 0 ... 65535 Value in mV
charger_mon_i Battery charger output current drain monitor R 0 ... 65535 Value in mA

Industrial Digital I/O Expansion Board

Digital inputs - /sys/class/stratopimax/digital_in_s<n>/

File Description Attr Value Value description
inN_mode Input N configuration R WF CS 1 Wire-break detection disabled
2 Wire-break detection enabled
inputs_mode Inputs configuration combined R WF CS CCCCCCC Concatenation of all 7 inputs configurations
inN_filter Input N filter configuration R WF CS 0 50 µs delay
1 100 µs delay
2 400 µs delay
3 800 µs delay
4 1.6 ms delay
5 3.2 ms delay
6 12.8 ms delay
7 20 ms delay
8 filter bypassed
inN Input N state R 0 low
1 high
inputs Inputs state combined R SSSSSSS Concatenation of all 7 inputs states
inN_wb Input N wire-break R W 0 not detected
R 1 detected (set until cleared)
inputs_wb Inputs wire-break combined R SSSSSSS Concatenation of all 7 inputs wire-break states
W 0 clear
alarm_t1 Inputs temperature alarm 1 R W 0 not active
R 1 active (set until cleared)
alarm_t2 Inputs temperature alarm 2 R W 0 not active
R 1 active (set until cleared)
over_temp Inputs thermal shutdown R W 0 not active
R 1 active (set until cleared)
fault Inputs general fault R 0 not active
1 active

Digital outputs - /sys/class/stratopimax/digital_out_s<n>/

File Description Attr Value Value description
outN_mode Output N configuration R WF CS 1 High-side mode, open-load detection disabled
2 High-side mode, open-load detection enabled
3 Push-pull mode, open-load detection disabled
outputs_mode Outputs configuration combined R WF CS CCCCCCC Concatenation of all 7 outputs configurations
join_l Outputs 1-2 (L side) join configuration. Can be joined only in high-side mode. `out2_mode` will be ignored R WF CS 0 Disabled
1 Outputs 1-2 joined
join_h Outputs 4-5 and 6-7 (H side) join configuration. Can be joined only in high-side mode. `out5_mode` and `out7_mode` will be ignored R WF CS 0 Disabled
1 Outputs 4-5 and 6-7 joined
watchdog Outputs watchdog configuration R WF CS 0 Disabled
1 Enabled
watchdog_timeout Outputs watchdog timeout configuration R WF CS 0 0.9 s
1 0.45 s
2 0.15 s
outN Output N state R W 0 low
1 high
outputs Outputs state combined R W SSSSSSS Concatenation of all 7 outputs states
outN_ol Output N open-load R W 0 not detected
R 1 detected (set until cleared)
outputs_ol Outputs open-load combined R SSSSSSS Concatenation of all 7 outputs open-load states
W 0 clear
outN_ov Output N over-voltage R W 0 not detected
R 1 detected (set until cleared)
outputs_ol Outputs over-voltage combined R SSSSSSS Concatenation of all 7 outputs over-voltage states
W 0 clear
outN_ot Output N over-temperature R W 0 not detected
R 1 detected (set until cleared)
outputs_ot Outputs over-temperature combined R SSSSSSS Concatenation of all 7 outputs over-temperature states
W 0 clear
outN_ov_lock Output N over-voltage protection lock R 0 not active
1 active
outputs_ov_lock Outputs over-voltage protection lock combined R SSSSSSS Concatenation of all 7 outputs over-voltage protection lock states
outN_ot_lock Output N over-temperature protection lock R 0 not active
1 active
outputs_ot_lock Outputs over-temperature protection lock combined R SSSSSSS Concatenation of all 7 outputs over-temperature protection lock states

RS-485 Expansion Boards

Digital inputs - /sys/class/stratopimax/rs485_s<n>/

File Description Attr Value Value description
echo RS-485 local echo configuration R W CS 0 Disabled
1 Enabled