# 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