2.6 KiB
Xterra Overland Dashboard - Codex Handoff
Repository
This repository is the source of truth.
Before making any code changes:
-
Read:
- docs/project-state.md
- docs/hardware-status.md
- docs/protocol.md
- docs/pico-architecture.md
- docs/ui-wireframes.md
- docs/implementation-roadmap.md
-
Inspect the existing codebase.
-
Do not assume documentation is correct. Verify implementation against documentation.
-
Prefer incremental commits.
-
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
-
Prefer small commits.
-
Preserve existing architecture.
-
Keep business logic hardware-independent.
-
Hardware-specific code belongs in:
hardware/
- Communication-specific code belongs in:
comms/
- UI state transformation belongs in:
view models
- 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.