xterra-overland-dashboard/docs/project-state.md

# Xterra Overland Power & Monitoring Dashboard

## Current Goal

Build a custom monitoring and control system for a Nissan Xterra using:

- Raspberry Pi Pico 2 W dashboard module
- ESP32 cargo-area controller
- 3.5 inch 320x480 SPI capacitive touchscreen
- DS18B20 temperature sensors
- UART over CAT5 communication
- WiFi HTTP backup interface

--------------------------------------------------

## Current Hardware

Ordered / Planned

- Raspberry Pi Pico 2 W
- ESP32 2-channel relay board
- 3.5 inch 320x480 touchscreen
- ST7796S display controller
- FT6336U capacitive touch controller
- 4x DS18B20 waterproof sensors
- Active 5V buzzer
- CAT5 cable
- Bosch automotive relays
- 12V to 5V buck converter

--------------------------------------------------

## Architecture

Dashboard Module (Pico)

Responsibilities:

- Touchscreen UI
- Audible alarms
- Dashboard display
- User interaction
- Sends commands to ESP32
- Receives status updates

Cargo Controller (ESP32)

Responsibilities:

- Relay control
- Sensor collection
- Configuration storage
- Future battery monitoring
- HTTP backup API
- UART communications

--------------------------------------------------

## Communications

Primary:

UART over CAT5

Backup:

WiFi HTTP API

Fallback:

RS485 over CAT5 if UART proves unreliable

Message format:

Newline-delimited JSON

Example Request:

{"type":"status_request"}

Example Response:

{"type":"status_response"}

--------------------------------------------------

## CAT5 Pinout

Pair 1

Blue       +5V
Blue/White +5V

Pair 2

Orange       Ground
Orange/White Ground

Pair 3

Green       Pico TX -> ESP32 RX
Green/White Pico RX <- ESP32 TX

Pair 4

Brown       Ignition Sense
Brown/White Spare

--------------------------------------------------

## Power Plan

House Battery

- Powers ESP32 directly through fused 12V
- Powers 12V to 5V buck converter
- Buck converter powers Pico through CAT5

Important:

- ESP32 relay board never carries fridge load current
- ESP32 relay board never carries Starlink load current
- ESP32 relay outputs only trigger Bosch relays
- High current circuits are separately fused

--------------------------------------------------

## Temperature Sensors

Current Sensors

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

No battery bay temperature sensor planned.

Reason:

Battery temperature will eventually come from the JBD/Xiaoxiang BMS.

--------------------------------------------------

## Battery Monitoring

Future Integration

JBD / Xiaoxiang BLE Battery

Planned Data:

- State of Charge
- Voltage
- Current
- Remaining Ah
- Runtime Estimate
- Battery Temperature
- Cell Voltages
- Cell Imbalance

--------------------------------------------------

## Relay Outputs

Current

- Starlink
- Fridge

Future

- Inverter
- Camp Lights

Known GPIO Assignments

GPIO16 = Relay Output 1
GPIO17 = Relay Output 2

Relay ON  = HIGH
Relay OFF = LOW

--------------------------------------------------

## Dashboard Screens

Implemented in Simulator

- Dashboard
- Battery
- Temps
- Power
- System
- Config

Dashboard Screen

- Battery Percentage
- Runtime Remaining
- Fridge Zone 1 Temperature
- Fridge Zone 2 Temperature
- Rear Seat Temperature
- Outside Air Temperature
- Relay Status

--------------------------------------------------

## Alarm System

Implemented in Simulator

- Warning alarms
- Critical alarms
- Full screen alarm overlay
- Acknowledge required
- Sensor fault alarms
- Configurable thresholds

Alarm Targets

- Rear Seat Warning
- Rear Seat Critical
- Fridge Zone 1 Warm
- Fridge Zone 2 Warm
- Battery Low

Future

- Dashboard buzzer

--------------------------------------------------

## Simulator Status

Location

simulator/

Implemented

- Flask backend
- Browser dashboard
- Pico simulator
- ESP32 simulator
- Protocol layer
- Transport layer
- Config persistence
- Sensor fault simulation
- Ignition simulation
- Communication failure simulation
- Latency simulation
- Packet loss simulation

Run Command

python3 simulator/app.py

--------------------------------------------------

## Firmware Status

ESP32 Firmware

Location

firmware/esp32/xterra-controller/

Implemented

- Relay framework
- Sensor framework
- DS18B20 support
- HTTP status endpoint
- WiFi AP mode
- GPIO16 relay
- GPIO17 relay

Next ESP32 Tasks

- Verify relay hardware
- Verify DS18B20 hardware
- Implement UART communications

--------------------------------------------------

## Pico Status

Not started.

Next Tasks

Create:

firmware/pico/display_test/
firmware/pico/touch_test/
firmware/pico/dashboard/

Goals

1. Verify ST7796S display
2. Verify FT6336U touch controller
3. Select graphics library
4. Build dashboard UI
5. Implement UART communications

--------------------------------------------------

## Important Decisions

- Touchscreen-only interface
- Active buzzer mounted in dashboard enclosure
- UART over CAT5 is primary wired communication
- WiFi is backup communication
- RS485 is back-burnered as fallback
- No persistent logging currently planned
- Focus on live monitoring, alarms, and control
- Repository is the source of truth
- Verify current file contents before generating patches

--------------------------------------------------

## Repository

Repository is the source of truth.

Do not assume previous patches were applied successfully.

Verify file contents before modifying existing files.

--------------------------------------------------

## New Chat Handoff

When continuing this project in a new chat:

Continue my Xterra Overland Power & Monitoring Dashboard project from docs/project-state.md.

The repository is the source of truth.

Ask me for current file contents before generating patches that modify existing files.