170 lines
2.6 KiB
Markdown
170 lines
2.6 KiB
Markdown
# 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.
|