8b092d0ca6
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>
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
1. **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`).
|
|
2. **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/)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|