Files

Joachim Hummel 8b092d0ca6 Add CLAUDE.md with project guidance

Document the project overview, build commands, and architecture
for the oneUpPower kernel module and oneUpMon monitor app.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-16 22:31:33 +02:00

2.9 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Argon ONE UP is a hardware support package for the Argon40 ONE UP laptop (Raspberry Pi-based). It consists of two main components:

oneUpPower - A Linux kernel module (battery/oneUpPower.c) that provides battery monitoring and automatic shutdown via the Linux power supply framework. Communicates with the battery management IC over I2C (bus 1, address 0x64).
oneUpMon - A PyQt6 desktop monitoring application (monitor/oneUpMon.py) that displays real-time CPU, disk I/O, network, temperature, and fan speed charts.

Only 64-bit Raspberry Pi OS is officially supported.

Build Commands

Kernel Module (battery/)

cd battery
./firsttime          # Install build dependencies (detects OS: Debian/Alpine/Ubuntu)
./build              # Compile oneUpPower.ko using kernel build system
sudo ./install       # Install module, add to /etc/modules, create modprobe config
sudo ./remove        # Unload and remove the module
./setupdkms          # Optional: register with DKMS for auto-rebuild on kernel updates

The build uses the standard Linux kernel module build system (make -C /lib/modules/$(uname -r)/build M=$(pwd) modules).

Monitor Application

python3 monitor/oneUpMon.py

Python dependencies: PyQt6 (with QtCharts), gpiozero, RPi.GPIO, smartmontools (for drive temps).

Architecture

Kernel Module (battery/oneUpPower.c)

Registers two power supplies with the kernel: BAT0 (battery) and AC0 (AC adapter)
Spawns a kernel thread (system_monitor) polling I2C registers every ~1 second
Reads SOC from registers 0x04/0x05, current direction from 0x0E/0x0F
Triggers graceful shutdown via call_usermodehelper("/sbin/shutdown") when unplugged and SOC drops below threshold
Module parameter soc_shutdown (0-20): 0 disables auto-shutdown, 1-20 sets the SOC% threshold (default 5)
Configured in /etc/modprobe.d/oneUpPower.conf

Monitor Application (monitor/)

oneUpMon.py: Main PyQt6 window with a grid of rolling charts (CPU, disk I/O, network, temperatures/fan). Uses RollingChart (fixed Y-axis) and RollingChartDynamic (auto-scaling Y-axis) chart classes. 60-second rolling window.
systemsupport.py: Data collection layer. Reads /proc/stat for CPU load, /sys/block/*/stat for disk I/O, /sys/class/net/*/statistics/ for network, and runs smartctl for drive temperatures.
configfile.py: INI config parser for /etc/sysmon.ini (drive/network filtering, smartctl options).
fanspeed.py: Reads case fan RPM via GPIO pulse counting.

Other Directories

config/: Raspberry Pi boot firmware config fragments (fan settings, overclock)
fioscript/: FIO benchmark job files for NVME drive testing
archive/: Legacy Argon40-supplied Python scripts (three versions: kickstarter, latest, original_beta) - reference only, not actively developed

2.9 KiB Raw Permalink Blame History