# ClearPilot — CLAUDE.md

## Project Overview

ClearPilot is a custom fork of **FrogPilot** (itself a fork of comma.ai's openpilot), based on a 2024 release. It is purpose-built for Brian Hanson's **Hyundai Tucson** (HDA2 equipped). The vehicle's HDA2 system has specific quirks around how it synchronizes driving state with openpilot that require careful handling.

### Key Customizations in This Fork

- **UI changes** to the onroad driving interface
- **Lane change behavior**: brief disengage when turn signal is active during lane changes
- **Lateral control disabled**: the car's own radar cruise control handles lateral; openpilot handles longitudinal only
- **Driver monitoring timeouts**: modified safety timeouts for the driver monitoring system
- **Custom driving models**: `duck-amigo.thneed`, `farmville.onnx`, `wd-40.thneed` in `selfdrive/clearpilot/models/`
- **ClearPilot service**: Node.js service at `selfdrive/clearpilot/` with behavior scripts for lane change and longitudinal control

### Short-Term Goals

- ~~Fix the dashcam/screen recorder feature~~ (done — see Dashcam section below)
- Fix GPS tracking feature
- Add a safe-speed-exceeded chime
- Implement interactions for the "debug function button"

## Working Rules

### CRITICAL: Change Control

This is self-driving software. All changes must be deliberate and well-understood.

- **NEVER make changes outside of what is explicitly requested**
- **Always explain proposed changes first** — describe the change, the logic, and the architecture; let Brian review and approve before writing any code
- **Brian is an expert on this software** — do not override his judgment or assume responsibility for changes he doesn't understand
- **Every line must be understood** — work slowly and deliberately
- **Test everything thoroughly** — Brian must always be in the loop
- **Do not refactor, clean up, or "improve" code beyond the specific request**

### File Ownership

We operate as `root` on this device, but openpilot runs as the `comma` user (uid=1000, gid=1000). After any code changes that touch multiple files or before testing:

```bash
chown -R comma:comma /data/openpilot
```

### Git

- Remote: `git@git.internal.hanson.xyz:brianhansonxyz/comma.git`
- Branch: `clearpilot`
- Large model files are tracked in git (intentional — this is a backup)

### Samba Share

- Share name: `openpilot` (e.g. `\\comma-3889765b\openpilot`)
- Path: `/data/openpilot`
- Username: `comma`
- Password: `i-like-to-drive-cars`
- Runs as `comma:comma` via force user/group — files created over SMB are owned correctly
- Enabled at boot (`smbd` + `nmbd`)

### Testing Changes

To restart the full openpilot stack after making changes:

```bash
# Fix ownership first (we edit as root, openpilot runs as comma)
chown -R comma:comma /data/openpilot

# Kill existing stack — use pgrep/kill to avoid pkill matching our own shell
kill $(pgrep -f 'python.*manager') 2>/dev/null; sleep 2

# Must use a login shell as comma — sudo -u won't set up the right Python/env
su - comma -c "bash /data/openpilot/launch_openpilot.sh"
```

Note: `pkill -f manager` or `pkill -f launch_openpilot` will match the invoking shell's own command line and kill the launch process itself. Use `pgrep`+`kill` or run the kill as a separate step before launching.

**Adding new params**: The params system uses a C++ whitelist. Adding a new param name in `manager.py` alone will crash with `UnknownKeyName`. You must also register the key in `common/params.cc` in the key list (alphabetically, with `PERSISTENT` or `CLEAR_ON_*` flag), then rebuild. The rebuild will recompile `params.cc` -> `libcommon.a` and re-link all binaries that use it.

The `prebuilt` marker file skips compilation. It is **recreated automatically** after each successful build, so you must remove it every time you want to recompile:
```bash
rm -f /data/openpilot/prebuilt
```

## Dashcam / Screen Recorder

### Architecture

The dashcam is the FrogPilot `ScreenRecorder` — it captures the onroad UI screen (with overlays) and encodes to MP4 using the Qualcomm OMX H.264 hardware encoder.

- **Codec**: H.264 AVC (hardware accelerated via `OMX.qcom.video.encoder.avc`)
- **Resolution**: 1440x720 (downscaled from 2160x1080)
- **Bitrate**: 2 Mbps
- **Container**: MP4
- **Segment length**: 3 minutes per file
- **Save path**: `/data/media/0/videos/YYYYMMDD-HHMMSS.mp4`

### Changes Made (2026-04-11)

1. **Disabled comma training data video** (`selfdrive/manager/process_config.py`): commented out `encoderd` and `stream_encoderd`. CAN/sensor logs (`rlog`/`qlog`) are still recorded by `loggerd`.

2. **Re-enabled screen recorder** (`selfdrive/ui/qt/onroad.cc`): uncommented the `QTimer` that feeds frames to the encoder at UI_FREQ rate.

3. **Auto-start recording** (`selfdrive/frogpilot/screenrecorder/screenrecorder.cc`): modified `update_screen()` to automatically start recording when the car is on (`scene.started`) and stop when off. No button press needed.

4. **Hidden UI elements**: the record button is constructed but never made visible or added to layout. Recording is invisible to the driver.

5. **Debug flag** (`ScreenRecorderDebug` param): when set to `"1"`, recording starts even without a car connected. Used for bench testing. Read via `scene.screen_recorder_debug` in `ui.h`/`ui.cc`.

6. **Deleter updated** (`system/loggerd/deleter.py`): free space threshold raised from 5 GB to 9 GB. Oldest videos in `/data/media/0/videos/` are deleted first before falling back to log segments.

### Key Files

| File | Role |
|------|------|
| `selfdrive/frogpilot/screenrecorder/screenrecorder.cc` | Screen capture and auto-start/stop logic |
| `selfdrive/frogpilot/screenrecorder/omx_encoder.cc` | OMX H.264 hardware encoder wrapper |
| `selfdrive/ui/qt/onroad.cc` | Timer that drives frame capture |
| `selfdrive/ui/ui.h` | `screen_recorder_debug` scene flag |
| `selfdrive/ui/ui.cc` | Reads `ScreenRecorderDebug` param |
| `selfdrive/manager/manager.py` | Default params |
| `selfdrive/manager/process_config.py` | encoderd disabled here |
| `system/loggerd/deleter.py` | Storage rotation (9 GB threshold, videos + logs) |

## Device: comma 3x

### Hardware

- Qualcomm Snapdragon SoC (aarch64)
- Serial: comma-3889765b
- Connects to the car via comma panda (CAN bus interface)

### Operating System

- **Ubuntu 20.04.6 LTS (Focal Fossa)** on aarch64
- **Kernel**: 4.9.103+ (custom comma.ai PREEMPT build, Feb 2024) — very old, vendor-patched Qualcomm kernel
- **AGNOS version**: 9.7 (comma's custom OS layer on top of Ubuntu)
- **Display server**: Weston (Wayland compositor) on tty1
- **SELinux**: mounted (enforcement status varies)

### Users

- `comma` (uid=1000) — the user openpilot runs as; member of root, sudo, disk, gpu, gpio groups
- `root` — what we SSH in as; files must be chowned back to comma before running openpilot

### Filesystem / Mount Quirks

| Mount       | Device      | Type    | Notes |
|-------------|-------------|---------|-------|
| `/`         | /dev/sda7   | ext4    | Root filesystem, read-write |
| `/data`     | /dev/sda12  | ext4    | **Persistent**. Openpilot lives here. Survives reboots. |
| `/home`     | overlay     | overlayfs | **VOLATILE** — upperdir on tmpfs, changes lost on reboot |
| `/tmp`      | tmpfs       | tmpfs   | Volatile, 150 MB |
| `/var`      | tmpfs       | tmpfs   | Volatile, 128 MB (fstab) / 1.5 GB (actual) |
| `/systemrw` | /dev/sda10  | ext4    | Writable system overlay, noexec |
| `/persist`  | /dev/sda2   | ext4    | Persistent config/certs, noexec |
| `/cache`    | /dev/sda11  | ext4    | Android-style cache partition |
| `/dsp`      | /dev/sde26  | ext4    | **Read-only** Qualcomm DSP firmware |
| `/firmware`  | /dev/sde4   | vfat    | **Read-only** firmware blobs |
| `/data/media`| NVMe       | auto    | 69 GB dashcam video storage |

### Unusual Packages / Services

- `vnstat` — network traffic monitor
- `cdsprpcd`, `qseecomd` — Qualcomm DSP and secure execution daemons
- `tftp_server` — TFTP server running (Qualcomm firmware access)
- armhf multiarch libraries present (32-bit binary support)
- Reverse SSH tunnel running via screen (`/data/brian/reverse_ssh.sh`)
- `phantom_touch_logger.py`, `power_drop_monitor.py` — comma hardware monitors

### Large Files on Device

- `/data/media` — ~69 GB (dashcam video segments)
- `/data/scons_cache` — ~1.9 GB (build cache)
- `/data/safe_staging` — ~1.5 GB (OTA update staging)
- Model files in repo: ~238 MB total (see models section below)

## Boot Sequence

```
Power On
  -> systemd: comma.service (runs as comma user)
    -> /usr/comma/comma.sh (waits for Weston, handles factory reset)
      -> /data/continue.sh (exec bridge to openpilot)
        -> /data/openpilot/launch_openpilot.sh
          -> Sources launch_env.sh (thread counts, AGNOS_VERSION)
          -> Runs agnos_init (marks boot slot, GPU perms, checks OS update)
          -> Sets PYTHONPATH, symlinks /data/pythonpath
          -> Runs build.py if no `prebuilt` marker
          -> Launches selfdrive/manager/manager.py
            -> manager_init() sets default params
            -> ensure_running() loop starts all managed processes
```

## Openpilot Architecture

### Process Manager

`selfdrive/manager/manager.py` orchestrates all processes defined in `selfdrive/manager/process_config.py`.

### Always-Running Processes (offroad + onroad)

- `thermald` — thermal management, high CPU (~5.6%)
- `pandad` — panda CAN bus interface
- `ui` — Qt-based onroad/offroad UI
- `deleter` — storage cleanup
- `statsd`, `timed`, `logmessaged`, `tombstoned` — telemetry/logging
- `manage_athenad` — comma cloud connectivity

### Onroad-Only Processes (when driving)

- `controlsd` — main vehicle control loop
- `plannerd` — path planning
- `radard` — radar processing
- `modeld` — driving model inference
- `dmonitoringmodeld` — driver monitoring model
- `locationd` — positioning/localization
- `calibrationd` — camera calibration
- `paramsd`, `torqued` — parameter estimation
- `sensord` — IMU/sensor data
- `soundd` — alert sounds
- `camerad` — camera capture
- `loggerd`, `encoderd` — video logging/encoding
- `boardd` — board communication

### GPS

- `ubloxd` + `pigeond` for u-blox GPS hardware
- `qcomgpsd`, `ugpsd`, `navd` currently **commented out** in process_config

### FrogPilot Additions

- `selfdrive/frogpilot/frogpilot_process.py` — FrogPilot main process
- `selfdrive/frogpilot/controls/` — custom planner, control libraries
- `selfdrive/frogpilot/fleetmanager/` — fleet management web UI
- `selfdrive/frogpilot/screenrecorder/` — C++ OMX-based screen recorder (dashcam)
- `selfdrive/frogpilot/ui/qt/` — custom UI widgets and settings panels
- `selfdrive/frogpilot/assets/` — custom assets

### ClearPilot Additions

- `selfdrive/clearpilot/clearpilot.js` — Node.js service
- `selfdrive/clearpilot/behavior/` — lane change, longitudinal control mode scripts
- `selfdrive/clearpilot/models/` — custom driving models (duck-amigo, farmville, wd-40)
- `selfdrive/clearpilot/manager/api.js` — manager API
- `selfdrive/clearpilot/theme/`, `selfdrive/clearpilot/resource/` — theming and assets

### Car Interface (Hyundai)

- `selfdrive/car/hyundai/interface.py` — main car interface
- `selfdrive/car/hyundai/carcontroller.py` — actuator commands
- `selfdrive/car/hyundai/carstate.py` — vehicle state parsing
- `selfdrive/car/hyundai/radar_interface.py` — radar data
- `selfdrive/car/hyundai/hyundaicanfd.py` — CAN-FD message definitions (HDA2 uses CAN-FD)
- `selfdrive/car/hyundai/values.py`, `fingerprints.py` — car-specific constants

### UI Code

- `selfdrive/ui/` — Qt/C++ based
- `selfdrive/ui/qt/onroad.cc` — main driving screen (contains uiDebug publish, screen recorder integration)
- `selfdrive/ui/qt/home.cc` — home/offroad screen
- `selfdrive/ui/qt/sidebar.cc` — sidebar
- `selfdrive/ui/ui.cc`, `ui.h` — UI state management

### Key Dependencies

- **Python 3.11** with: numpy, casadi, onnx/onnxruntime, pycapnp, pyzmq, sentry-sdk, sympy, Cython
- **capnp (Cap'n Proto)** — IPC message serialization between all processes
- **ZeroMQ** — IPC transport layer
- **Qt 5** — UI framework
- **OpenMAX (OMX)** — hardware video encoding (screen recorder)
- **SCons** — build system for native C++ components