# Xterra Overland Dashboard - Codex Handoff

## Repository

This repository is the source of truth.

Before making any code changes:

1. Read:
   - docs/project-state.md
   - docs/hardware-status.md
   - docs/protocol.md
   - docs/pico-architecture.md
   - docs/ui-wireframes.md
   - docs/implementation-roadmap.md

2. Inspect the existing codebase.

3. Do not assume documentation is correct.
   Verify implementation against documentation.

4. Prefer incremental commits.

5. Run tests before proposing changes.

---

# Project Overview

The project is an overland vehicle monitoring and control system for a Nissan Xterra.

Architecture:

## Dashboard

- Raspberry Pi Pico 2 W
- 3.5" 320x480 ST7796S display
- FT6336U capacitive touch
- Active buzzer

Responsibilities:

- Live monitoring
- Relay control
- Alarms
- Touchscreen UI

## Cargo Controller

- ESP32 relay board
- GPIO16 = Starlink relay trigger
- GPIO17 = Fridge relay trigger

Important:

The ESP32 relay outputs do NOT carry load current.

They only trigger Bosch automotive relays.

High-current loads never pass through ESP32 relay contacts.

---

# Communications

Primary:

- UART over CAT5
- 115200 baud
- Newline-delimited JSON

Backup:

- WiFi HTTP API

Fallback only:

- RS-485 (not currently planned)

Protocol specification:

docs/protocol.md

---

# Temperature Sensors

DS18B20 sensors:

- Fridge Zone 1
- Fridge Zone 2
- Rear Seat Area
- Outside Air

Missing sensors should report:

- temperature = null
- sensor_health = false

---

# Current Status

Completed:

- ESP32 firmware compiles
- UART protocol defined
- Pico architecture defined
- Pico state management implemented
- Alarm system implemented
- Communication service implemented
- HTTP fallback implemented
- Touch routing abstraction implemented
- Display abstraction implemented
- Unit tests implemented

In Progress:

- ESP32 hardware bring-up

Not Started:

- Pico display integration
- Pico touch integration
- Pico UART integration
- Real hardware drivers

---

# Development Rules

1. Prefer small commits.

2. Preserve existing architecture.

3. Keep business logic hardware-independent.

4. Hardware-specific code belongs in:

hardware/

5. Communication-specific code belongs in:

comms/

6. UI state transformation belongs in:

view models

7. Add tests whenever possible.

---

# Immediate Goal

Current milestone:

ESP32 hardware bring-up.

Success criteria:

- Firmware uploads
- WiFi AP starts
- HTTP API responds
- Relay outputs work
- DS18B20 framework works
- UART initializes

Do not begin large UI rewrites until ESP32 hardware validation is complete.