Skip to content

sfera-labs/strato-pi-max-kernel-module

BranchesTags

Repository files navigation

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.

Properties with the _config name suffix correspond to configuration parameters whose values are persisted and retained across power cycles.
The configuration parameters with attribute CR (see the attributes table below) are effective immediately, while those marked with C only store the value which will be copied to their "runtime" counterpart (same property name without _config suffix) upon power-up.

Note

A power-up occurs when:

  • the unit is powered on (main power supply connected);
  • a power cycle is explicitly initiated via power/down_enabled; or
  • a power cycle is initiated by another process configured to do so (e.g. watchdog timeout expiration).

A software reboot of the compute module does not correspond to a power-up.

This allows us to have a different configuration for the next power-up phase, whether after a planned or abrupt power-off. For example, it enables switching the boot SD card while the compute module is off or setting a short watchdog timeout only while your application (which manages the watchdog heartbeat) is running; the timeout is then reset to a longer duration when a power cycle occurs, ensuring the compute module has enough time to boot and restart your application.

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
C Configuration value, persisted and retained across power cycles, value copied to "runtime" counterpart on power cycle
CR Configuration value, persisted and retained across power cycles, effective immediately

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 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/saving 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
x: reserved, set to 0
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 0 Disabled
R W 1 Enabled. Once enabled cannot be interrupted
down_delay_config Shutdown delay from enabling R W CR 1 ... 65535 Value in seconds. Default: 60
off_time_config Power-off duration R W CR 1 ... 65535 Value in seconds. Default: 5
up_delay_config Power-up delay configuration R W CR 1 ... 65535 Value in seconds. Default: 0
up_backup_config Configuration for enabling power-up when a power cycle occurs while main power is not available (requires UPS expansion board) R W CR 0 Power-up only when main power is restored (default)
1 Power-up even if running on backup power source (UPS battery)
sd_switch_config SDA/SDB switch configuration on power cycle R W CR 0 Disabled (default)
1 Enabled
pcie_switch_config PCIE on/off toggle configuration on power cycle R W CR 0 Disabled (default)
1 Enabled

Watchdog - /sys/class/stratopimax/watchdog/

File Description Attr Value Value description
enabled Watchdog enabling R W 0 Disabled
1 Enabled
enabled_config Watchdog enabling configuration R W C 0 Disabled (default)
1 Enabled
timeout Watchdog timeout R W 1 ... 65535 Value in seconds. Default: 60
timeout_config Watchdog timeout configuration R W C 60 ... 65535 Value in seconds. Default: 60
down_delay_config Automatic power cycle delay configuration when watchdog timeout expires R W CR 0 ... 65535 Value in seconds. Default: 60
sd_switch_config SDA/SDB switch configuration on watchdog reset R W CR 0 Disabled (default)
1 Switching occurs upon each watchdog reset
2 ... 65535 Number of consecutive resets (with no heartbeat received in between) before switching occurs. Requires watchdog/enabled_config set to 1
pcie_switch_config PCIE on/off toggle configuration on watchdog reset R W CR 0 Disabled (default)
1 Toggling occurs upon each watchdog reset
2 ... 65535 Number of consecutive resets (with no heartbeat received in between) before toggling occurs. Requires watchdog/enabled_config set to 1
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 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 0 ... 65535 Value in Hz

LEDs - /sys/class/stratopimax/led/

File Description Attr Value Value description
red Red LED control W 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 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 0 Disabled
1 Enabled
usb1_enabled_config USB1 enabling configuration R W C 0 Disabled
1 Enabled (default)
usb1_err USB1 fault R 0 OK
1 Fault
usb2_enabled USB2 enabling R W 0 Disabled
1 Enabled
usb2_enabled_config USB2 enabling configuration R W C 0 Disabled
1 Enabled (default)
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 0 Disabled
1 Enabled
sd_main_enabled_config Main SD interface enabling configuration R W C 0 Disabled
1 Enabled (default)
sd_sec_enabled Secondary SD interface enabling R W 0 Disabled
1 Enabled
sd_sec_enabled_config Secondary SD interface enabling configuration R W C 0 Disabled (default)
1 Enabled
sd_main_routing Main SD routing control R W A Main SD interface routed to SDA, secondary SD interface to SDB
B Main SD interface routed to SDB, secondary SD interface to SDA
sd_main_routing_config Main SD routing configuration R W C A Main SD interface routed to SDA, secondary SD interface to SDB (default)
B 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_config PCIE enabling configuration R W C 0 Disabled
1 Enabled (default)

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 Z-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 0 Disabled
1 Enabled
sN_enabled_config Slot N enabling configuration R W C 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 typology.

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

UPS - /sys/class/stratopimax/ups/

File Description Attr Value Value description
enabled UPS enabling R W 0 Disabled
1 Enabled
enabled_config UPS enabling configuration R W C 0 Disabled
1 Enabled (default)
battery_v_config UPS battery voltage configuration R W CR 12000 12 V battery (default)
24000 24 V battery
battery_capacity_config UPS battery capacity configuration R W CR 100 ... 60000 Value in mAh. Default: 800
battery_i_max UPS battery maximum charging current while at maximum voltage R W 0 Value automatically derived from capacity (default)
1 ... 65535 Value in mA. The automatically derived limit still applies if lower than this value
battery_i_max_config UPS battery maximum charging current while at maximum voltage configuration R W C 0 Value automatically derived from capacity (default)
1 ... 65535 Value in mA. The automatically derived limit still applies if lower than this value
down_delay_config Automatic power cycle timeout configuration when main power source not available R W CR 0 Disabled (default)
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

Power Supply Output - /sys/class/stratopimax/power_out/

File Description Attr Value Value description
vso_enabled VSO power supply output control R W 0 Disabled
1 Enabled
vso_enabled_config VSO power supply output configuration R W C 0 Disabled
1 Enabled (default)

Industrial Digital I/O Expansion Board

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

File Description Attr Value Value description
inN_wb_config Input N Wire-break detection configuration R WF CR 0 Disabled (default)
1 Enabled
inN_filter_config Input N filter configuration R WF CR 0 50 µs delay (default)
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 (write to clear)
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 (write to clear)
R 1 Active (set until cleared)
alarm_t2 Inputs temperature alarm 2 R W 0 Not active (write to clear)
R 1 Active (set until cleared)
over_temp Inputs thermal shutdown R W 0 Not active (write to clear)
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_pp_config Output N high-side/push-pull mode configuration R WF CR 0 High-side mode (default)
1 Push-pull mode
outN_ol_config Output N open-load detection configuration (only for high-side mode) R WF CR 0 Disabled (default)
1 Enabled
join_l_config Outputs 1-2 (L side terminal block) join configuration (only for high-side mode) R WF CR 0 Disabled (default)
1 Outputs 1-2 joined. Configurations and status for output 1 apply to pair
join_h_config Outputs 4-5 and 6-7 (H side terminal block) join configuration (only for high-side mode) R WF CR 0 Disabled (default)
1 Outputs 4-5 and 6-7 joined. Configurations and status for outputs 4 and 6 apply to respective pairs
watchdog_config Outputs watchdog configuration R WF CR 0 Disabled
1 Enabled (default)
watchdog_timeout_config Outputs watchdog timeout configuration R WF CR 0 0.9 s (default)
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 (write to clear)
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 (write to clear)
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 (write to clear)
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_config RS-485 local echo configuration R W CR 0 Disabled (default)
1 Enabled

About

Strato Pi Max driver kernel module

sferalabs.cc/strato-pi-max/

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

4 watching

Forks

0 forks
Report repository

Languages