Clean up documentation structure
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
# ESP32 API and Serial Commands
|
||||
|
||||
## HTTP API
|
||||
|
||||
Base URL while connected to the ESP32 access point:
|
||||
|
||||
http://192.168.4.1
|
||||
|
||||
## Status
|
||||
|
||||
### GET /status
|
||||
|
||||
Returns full controller status, including battery/BMS telemetry, relay states, temperature sensor states, alarms, system info, and current configuration.
|
||||
|
||||
Relay states use generic IDs:
|
||||
|
||||
relay_1
|
||||
relay_2
|
||||
|
||||
Temperature sensors use generic IDs:
|
||||
|
||||
temp_1 through temp_8
|
||||
|
||||
## Relay Control API
|
||||
|
||||
GET /relay/relay_1/on
|
||||
GET /relay/relay_1/off
|
||||
GET /relay/relay_2/on
|
||||
GET /relay/relay_2/off
|
||||
|
||||
Relay display names are configurable. Firmware and API clients should not assume what a relay controls.
|
||||
|
||||
## Configuration API
|
||||
|
||||
### GET /config
|
||||
|
||||
Returns saved configuration.
|
||||
|
||||
### POST /config/device
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
"device_name": "Overland Controller"
|
||||
}
|
||||
|
||||
### POST /config/relay
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
"id": "relay_1",
|
||||
"name": "Aux Power",
|
||||
"enabled": true
|
||||
}
|
||||
|
||||
### POST /config/bms
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
"enabled": true,
|
||||
"name": "House Battery",
|
||||
"address": "aa:bb:cc:dd:ee:ff",
|
||||
"address_type": "public"
|
||||
}
|
||||
|
||||
### POST /config/temp
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
"id": "temp_1",
|
||||
"name": "Cabin",
|
||||
"address": "",
|
||||
"enabled": true
|
||||
}
|
||||
|
||||
### POST /config/factory-reset
|
||||
|
||||
Clears saved configuration and restores generic defaults.
|
||||
|
||||
## Serial Monitor
|
||||
|
||||
Baud:
|
||||
|
||||
115200
|
||||
|
||||
Line ending:
|
||||
|
||||
Newline
|
||||
|
||||
## Status and Config Commands
|
||||
|
||||
status
|
||||
config
|
||||
save
|
||||
factory reset
|
||||
|
||||
## Device Configuration Commands
|
||||
|
||||
devicename Overland Controller
|
||||
|
||||
Run `save` after changing the device name.
|
||||
|
||||
## Log Level Commands
|
||||
|
||||
log quiet
|
||||
log info
|
||||
log debug
|
||||
|
||||
## Relay Control Commands
|
||||
|
||||
relay 1 on
|
||||
relay 1 off
|
||||
relay 2 on
|
||||
relay 2 off
|
||||
|
||||
## Relay Configuration Commands
|
||||
|
||||
relayname 1 Aux Power
|
||||
relayname 2 Accessory Power
|
||||
|
||||
Run `save` after changing names.
|
||||
|
||||
## Temperature Sensor Configuration Commands
|
||||
|
||||
tempname 1 Cabin
|
||||
tempname 2 Outside Air
|
||||
|
||||
Run `save` after changing names.
|
||||
|
||||
## BMS Configuration Commands
|
||||
|
||||
bmsname House Battery
|
||||
bmsaddr aa:bb:cc:dd:ee:ff
|
||||
|
||||
Run `save` after changing BMS config manually.
|
||||
|
||||
## BMS Setup Mode Commands
|
||||
|
||||
enter setup
|
||||
scan ble
|
||||
select bms 1
|
||||
exit setup
|
||||
|
||||
Notes:
|
||||
|
||||
- Some BMS modules advertise intermittently.
|
||||
- Multiple BLE scans may be required.
|
||||
- Once a BMS address is configured, BMS telemetry reconnects directly using the saved address.
|
||||
|
||||
## Typical First-Time Setup Flow
|
||||
|
||||
log info
|
||||
enter setup
|
||||
scan ble
|
||||
scan ble
|
||||
select bms 1
|
||||
relayname 1 Aux Power
|
||||
relayname 2 Accessory Power
|
||||
tempname 1 Cabin
|
||||
tempname 2 Outside Air
|
||||
save
|
||||
config
|
||||
|
||||
## Known Notes
|
||||
|
||||
- DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
|
||||
- The firmware uses generic relay and temperature IDs. Installation-specific names belong in saved configuration only.
|
||||
@@ -0,0 +1,169 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Communications
|
||||
|
||||
## Architecture
|
||||
|
||||
Pico Dashboard
|
||||
↓
|
||||
UART over CAT5
|
||||
↓
|
||||
ESP32 Controller
|
||||
|
||||
Backup:
|
||||
WiFi
|
||||
|
||||
## Protocol
|
||||
|
||||
Message Types:
|
||||
|
||||
- status_request
|
||||
- status_response
|
||||
- set_relay
|
||||
- relay_response
|
||||
- enable_wifi
|
||||
- wifi_response
|
||||
- toggle_ignition
|
||||
- ignition_response
|
||||
- toggle_sensor_fault
|
||||
- sensor_fault_response
|
||||
|
||||
## Failure Handling
|
||||
|
||||
If UART over CAT5 is lost:
|
||||
- Dashboard displays warning
|
||||
- Last known values remain visible
|
||||
- Relay commands fail safely
|
||||
|
||||
## Future Features
|
||||
|
||||
- MQTT
|
||||
- Home Assistant
|
||||
- OTA Updates
|
||||
- Remote Diagnostics
|
||||
@@ -0,0 +1,75 @@
|
||||
# Dashboard User Interface
|
||||
|
||||
## Dashboard Screen
|
||||
|
||||
Displays:
|
||||
- Battery %
|
||||
- Runtime Remaining
|
||||
- Fridge Zone 1 Temperature
|
||||
- Fridge Zone 2 Temperature
|
||||
- Rear Seat Temperature
|
||||
- Outside Temperature
|
||||
- Starlink Status
|
||||
- Fridge Status
|
||||
|
||||
## Battery Screen
|
||||
|
||||
Displays:
|
||||
- SOC
|
||||
- Voltage
|
||||
- Current
|
||||
- Remaining Ah
|
||||
- Runtime Estimate
|
||||
- Battery Temperature
|
||||
|
||||
Future:
|
||||
- Cell Voltages
|
||||
- Cell Imbalance
|
||||
- Charge Cycles
|
||||
|
||||
## Temperature Screen
|
||||
|
||||
Displays:
|
||||
- Fridge Zone 1
|
||||
- Fridge Zone 2
|
||||
- Rear Seat
|
||||
- Outside Air
|
||||
|
||||
Future:
|
||||
- Battery Bay
|
||||
- Cabin Air
|
||||
|
||||
## Power Screen
|
||||
|
||||
Controls:
|
||||
- Starlink
|
||||
- Fridge
|
||||
|
||||
Future:
|
||||
- Inverter
|
||||
- Camp Lights
|
||||
|
||||
## System Screen
|
||||
|
||||
Displays:
|
||||
- UART Status
|
||||
- WiFi Status
|
||||
- Message Counts
|
||||
- Latency
|
||||
- Packet Loss
|
||||
|
||||
Testing:
|
||||
- UART Disconnect
|
||||
- Sensor Fault Simulation
|
||||
- Ignition Simulation
|
||||
|
||||
## Config Screen
|
||||
|
||||
Configuration:
|
||||
- Alarm Thresholds
|
||||
- Audible Alarm Settings
|
||||
|
||||
Future:
|
||||
- WiFi Settings
|
||||
- Device Naming
|
||||
- Firmware Information
|
||||
@@ -0,0 +1,162 @@
|
||||
# Hardware Bring-Up Checklist
|
||||
|
||||
## ESP32 Cargo Controller
|
||||
|
||||
### Compile
|
||||
|
||||
* Firmware compiles successfully
|
||||
* Required libraries installed:
|
||||
|
||||
* ArduinoJson
|
||||
* OneWire
|
||||
* DallasTemperature
|
||||
|
||||
### Upload
|
||||
|
||||
* Board: ESP32 Dev Module
|
||||
* Serial monitor opens at 115200 baud
|
||||
* Boot message appears
|
||||
|
||||
### WiFi AP
|
||||
|
||||
Verify ESP32 creates AP:
|
||||
|
||||
* SSID: OverlandController
|
||||
|
||||
### HTTP API
|
||||
|
||||
Test:
|
||||
|
||||
```
|
||||
http://192.168.4.1/status
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
* JSON response
|
||||
* Battery placeholder values present
|
||||
* Relay states present
|
||||
* Sensor health present
|
||||
* Network status present
|
||||
|
||||
### Relays
|
||||
|
||||
Test endpoints:
|
||||
|
||||
```
|
||||
/relay/starlink/on
|
||||
/relay/starlink/off
|
||||
/relay/fridge/on
|
||||
/relay/fridge/off
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
* GPIO16 controls Starlink relay channel
|
||||
* GPIO17 controls Fridge relay channel
|
||||
* Relay logic is correct
|
||||
* If relay behavior is backwards, update relay active-high/active-low logic
|
||||
|
||||
### DS18B20 Sensors
|
||||
|
||||
Verify:
|
||||
|
||||
* Sensor bus initializes
|
||||
* Missing sensors do not crash firmware
|
||||
* Connected sensors report temperatures
|
||||
* Sensor fault state works
|
||||
|
||||
### UART
|
||||
|
||||
Verify:
|
||||
|
||||
* UART initializes
|
||||
* ESP32 does not crash without Pico connected
|
||||
* Serial JSON protocol works once Pico or USB-UART test is connected
|
||||
|
||||
---
|
||||
|
||||
## Pico Dashboard
|
||||
|
||||
### Pico Boot
|
||||
|
||||
Verify:
|
||||
|
||||
* Pico 2 W boots
|
||||
* MicroPython or CircuitPython environment works
|
||||
* Main script runs
|
||||
|
||||
### Display
|
||||
|
||||
Verify:
|
||||
|
||||
* ST7796S initializes
|
||||
* Screen fill works
|
||||
* Text drawing works
|
||||
* Rotation/orientation is correct
|
||||
|
||||
### Touch
|
||||
|
||||
Verify:
|
||||
|
||||
* FT6336U initializes
|
||||
* Touch events are detected
|
||||
* X/Y coordinates match screen orientation
|
||||
* Bottom navigation zones match expected touch positions
|
||||
|
||||
### Buzzer
|
||||
|
||||
Verify:
|
||||
|
||||
* Active buzzer turns on
|
||||
* Active buzzer turns off
|
||||
* Buzzer does not block UI loop
|
||||
|
||||
### UART to ESP32
|
||||
|
||||
Verify:
|
||||
|
||||
* Pico sends status request
|
||||
* ESP32 responds with status response
|
||||
* Pico parses response
|
||||
* Pico updates app state
|
||||
* Pico sends relay command
|
||||
* ESP32 toggles relay
|
||||
* Pico receives relay response
|
||||
|
||||
---
|
||||
|
||||
## System Integration
|
||||
|
||||
### Dashboard
|
||||
|
||||
Verify:
|
||||
|
||||
* Battery placeholder data displays
|
||||
* Temperatures display
|
||||
* Relay states display
|
||||
* Communication state displays
|
||||
|
||||
### Alarms
|
||||
|
||||
Verify:
|
||||
|
||||
* Communication loss alarm triggers
|
||||
* Sensor fault alarm triggers
|
||||
* Fridge high-temp alarm triggers
|
||||
* Low battery alarm triggers
|
||||
* Critical alarms trigger buzzer
|
||||
|
||||
---
|
||||
|
||||
## Do Not Proceed Until
|
||||
|
||||
Before moving to production wiring:
|
||||
|
||||
* ESP32 firmware boots reliably
|
||||
* Relays behave correctly
|
||||
* UART protocol works
|
||||
* Pico display works
|
||||
* Pico touch works
|
||||
* Buzzer works
|
||||
* No high-current loads pass through ESP32 relay contacts
|
||||
@@ -0,0 +1,184 @@
|
||||
# Revised Milestone Order
|
||||
|
||||
## Milestone 1: ESP32 Hardware Bring-Up
|
||||
|
||||
### Goal
|
||||
|
||||
Verify cargo-controller hardware.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Flash ESP32 firmware
|
||||
- Verify WiFi AP
|
||||
- Verify HTTP API
|
||||
- Verify relay outputs
|
||||
- Verify DS18B20 framework
|
||||
- Verify UART initialization
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- ESP32 boots reliably
|
||||
- Relays operate correctly
|
||||
- HTTP API responds correctly
|
||||
- No crashes or watchdog resets
|
||||
|
||||
---
|
||||
|
||||
## Milestone 2: JBD/Xiaoxiang BMS Integration
|
||||
|
||||
### Goal
|
||||
|
||||
Replace placeholder battery values with live battery telemetry.
|
||||
|
||||
### Tasks
|
||||
|
||||
- BLE communication
|
||||
- JBD packet parsing
|
||||
- Battery SOC
|
||||
- Voltage
|
||||
- Current
|
||||
- Remaining Ah
|
||||
- Runtime calculations
|
||||
- Battery temperature
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- Live battery telemetry available
|
||||
- Battery data exposed through API
|
||||
- Placeholder battery values removed
|
||||
|
||||
---
|
||||
|
||||
## Milestone 3: Pico Hardware Bring-Up
|
||||
|
||||
### Goal
|
||||
|
||||
Verify dashboard hardware.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Display initialization
|
||||
- Touch initialization
|
||||
- Buzzer verification
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- Display functional
|
||||
- Touch functional
|
||||
- Buzzer functional
|
||||
|
||||
---
|
||||
|
||||
## Milestone 4: UART Communications
|
||||
|
||||
### Goal
|
||||
|
||||
Connect Pico and ESP32.
|
||||
|
||||
### Tasks
|
||||
|
||||
- UART transport
|
||||
- Status requests
|
||||
- Status responses
|
||||
- Relay commands
|
||||
- Error handling
|
||||
- Timeout detection
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- Live data displayed on Pico
|
||||
- Relay control operational
|
||||
|
||||
---
|
||||
|
||||
## Milestone 5: Dashboard UI
|
||||
|
||||
### Goal
|
||||
|
||||
Create the primary user interface.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Dashboard screen
|
||||
- Battery screen
|
||||
- Temperatures screen
|
||||
- Power screen
|
||||
- System screen
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- All screens functional
|
||||
- Navigation stable
|
||||
- Live updates working
|
||||
|
||||
---
|
||||
|
||||
## Milestone 6: DS18B20 Integration
|
||||
|
||||
### Goal
|
||||
|
||||
Implement all production temperature sensors.
|
||||
|
||||
### Sensors
|
||||
|
||||
- Fridge Zone 1
|
||||
- Fridge Zone 2
|
||||
- Rear Seat Area
|
||||
- Outside Air
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- Sensors report correctly
|
||||
- Sensor failures detected
|
||||
|
||||
---
|
||||
|
||||
## Milestone 7: Alarm System
|
||||
|
||||
### Goal
|
||||
|
||||
Implement monitoring and alerting.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Alarm manager
|
||||
- Alarm overlay
|
||||
- Buzzer integration
|
||||
- Communication alarms
|
||||
- Battery alarms
|
||||
- Temperature alarms
|
||||
- Sensor fault alarms
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- Alarms trigger correctly
|
||||
- Audible alerts function correctly
|
||||
|
||||
---
|
||||
|
||||
## Milestone 8: Vehicle Integration
|
||||
|
||||
### Potential Features
|
||||
|
||||
- Ignition state
|
||||
- OBD-II
|
||||
- CAN bus
|
||||
- Fuel level
|
||||
- Engine data
|
||||
|
||||
Future planning only.
|
||||
|
||||
---
|
||||
|
||||
## Milestone 9: Future Expansion
|
||||
|
||||
### Potential Features
|
||||
|
||||
- Additional relays
|
||||
- Inverter control
|
||||
- Lighting control
|
||||
- GPS
|
||||
- Starlink diagnostics
|
||||
- Home Assistant
|
||||
|
||||
Future planning only.
|
||||
@@ -0,0 +1,325 @@
|
||||
# Pico Dashboard Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
The Raspberry Pi Pico 2 W dashboard is the primary user interface for the Xterra Overland Power & Monitoring Dashboard.
|
||||
|
||||
Its responsibilities are:
|
||||
|
||||
* Display live system status
|
||||
* Display alarms and warnings
|
||||
* Allow relay control
|
||||
* Provide touchscreen navigation
|
||||
* Communicate with the ESP32 cargo controller
|
||||
* Provide audible alerts through a dashboard buzzer
|
||||
|
||||
The Pico is intentionally a display and control device.
|
||||
|
||||
The ESP32 remains responsible for hardware control and sensor collection.
|
||||
|
||||
---
|
||||
|
||||
# Hardware
|
||||
|
||||
## Dashboard Controller
|
||||
|
||||
* Raspberry Pi Pico 2 W
|
||||
|
||||
## Display
|
||||
|
||||
* ST7796S
|
||||
* 320x480 resolution
|
||||
* SPI interface
|
||||
|
||||
## Touch Controller
|
||||
|
||||
* FT6336U
|
||||
* Capacitive touch
|
||||
* I2C interface
|
||||
|
||||
## Audio
|
||||
|
||||
* Active buzzer
|
||||
|
||||
## Communications
|
||||
|
||||
Primary:
|
||||
|
||||
* UART over CAT5
|
||||
|
||||
Backup:
|
||||
|
||||
* WiFi HTTP API
|
||||
|
||||
Fallback only:
|
||||
|
||||
* RS-485 (not currently planned)
|
||||
|
||||
---
|
||||
|
||||
# Software Architecture
|
||||
|
||||
```text
|
||||
main.py
|
||||
│
|
||||
├── app_state.py
|
||||
│
|
||||
├── comms/
|
||||
│ ├── uart_client.py
|
||||
│ ├── http_client.py
|
||||
│ └── protocol.py
|
||||
│
|
||||
├── hardware/
|
||||
│ ├── display.py
|
||||
│ ├── touch.py
|
||||
│ └── buzzer.py
|
||||
│
|
||||
├── alarms/
|
||||
│ ├── alarm_manager.py
|
||||
│ └── alarm_definitions.py
|
||||
│
|
||||
└── ui/
|
||||
├── screen_manager.py
|
||||
├── dashboard_screen.py
|
||||
├── battery_screen.py
|
||||
├── temps_screen.py
|
||||
├── power_screen.py
|
||||
├── system_screen.py
|
||||
└── alarm_overlay.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Application State
|
||||
|
||||
A single application state object should hold all current controller data.
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
state.battery_soc
|
||||
state.battery_voltage
|
||||
|
||||
state.fridge_zone_1_temp
|
||||
state.fridge_zone_2_temp
|
||||
|
||||
state.starlink_enabled
|
||||
state.fridge_enabled
|
||||
|
||||
state.ignition_on
|
||||
|
||||
state.uart_connected
|
||||
state.wifi_connected
|
||||
```
|
||||
|
||||
All screens should render from the application state rather than communicating directly with the ESP32.
|
||||
|
||||
---
|
||||
|
||||
# Communication Layer
|
||||
|
||||
## Responsibilities
|
||||
|
||||
* Send status requests
|
||||
* Receive status responses
|
||||
* Send relay commands
|
||||
* Handle communication failures
|
||||
* Switch to HTTP fallback if UART fails
|
||||
|
||||
The communication layer should be the only component that knows how to talk to the ESP32.
|
||||
|
||||
---
|
||||
|
||||
# Screen Manager
|
||||
|
||||
The screen manager owns navigation.
|
||||
|
||||
Initial screens:
|
||||
|
||||
1. Dashboard
|
||||
2. Battery
|
||||
3. Temperatures
|
||||
4. Power
|
||||
5. System
|
||||
|
||||
Only one screen should be active at a time.
|
||||
|
||||
---
|
||||
|
||||
# Dashboard Screen
|
||||
|
||||
The dashboard screen is the default landing page.
|
||||
|
||||
Display:
|
||||
|
||||
* Battery SOC
|
||||
* Battery voltage
|
||||
* Battery current
|
||||
* Remaining runtime
|
||||
* Fridge temperatures
|
||||
* Relay status
|
||||
* Communication status
|
||||
* Active alarms
|
||||
|
||||
Goal:
|
||||
|
||||
Quick vehicle-at-a-glance information.
|
||||
|
||||
---
|
||||
|
||||
# Battery Screen
|
||||
|
||||
Display:
|
||||
|
||||
* SOC
|
||||
* Voltage
|
||||
* Current
|
||||
* Remaining amp-hours
|
||||
* Runtime estimate
|
||||
* Battery temperature
|
||||
|
||||
Future:
|
||||
|
||||
* BMS cell voltages
|
||||
* Charge/discharge limits
|
||||
|
||||
---
|
||||
|
||||
# Temperature Screen
|
||||
|
||||
Display:
|
||||
|
||||
* Fridge Zone 1
|
||||
* Fridge Zone 2
|
||||
* Rear Seat Area
|
||||
* Outside Air
|
||||
|
||||
Display sensor fault indicators when sensors are missing.
|
||||
|
||||
---
|
||||
|
||||
# Power Screen
|
||||
|
||||
Display:
|
||||
|
||||
* Starlink relay status
|
||||
* Fridge relay status
|
||||
|
||||
Allow relay control.
|
||||
|
||||
Future:
|
||||
|
||||
* Inverter
|
||||
* Lighting
|
||||
* Additional accessory relays
|
||||
|
||||
---
|
||||
|
||||
# System Screen
|
||||
|
||||
Display:
|
||||
|
||||
* ESP32 status
|
||||
* Communication status
|
||||
* Firmware versions
|
||||
* WiFi status
|
||||
* Sensor health
|
||||
|
||||
Future:
|
||||
|
||||
* Configuration options
|
||||
|
||||
---
|
||||
|
||||
# Alarm Manager
|
||||
|
||||
The alarm manager continuously evaluates system state.
|
||||
|
||||
Initial alarms:
|
||||
|
||||
## Battery Low
|
||||
|
||||
Triggered when SOC falls below configured threshold.
|
||||
|
||||
## Battery Voltage Low
|
||||
|
||||
Triggered when voltage falls below configured threshold.
|
||||
|
||||
## Fridge Temperature High
|
||||
|
||||
Triggered when fridge temperature exceeds configured threshold.
|
||||
|
||||
## Sensor Failure
|
||||
|
||||
Triggered when a sensor becomes unavailable.
|
||||
|
||||
## Communication Failure
|
||||
|
||||
Triggered when ESP32 communication is lost.
|
||||
|
||||
---
|
||||
|
||||
# Alarm Overlay
|
||||
|
||||
The alarm overlay is visible from any screen.
|
||||
|
||||
Severity levels:
|
||||
|
||||
* Info
|
||||
* Warning
|
||||
* Critical
|
||||
|
||||
Critical alarms should trigger the buzzer.
|
||||
|
||||
---
|
||||
|
||||
# Buzzer Manager
|
||||
|
||||
Initial buzzer events:
|
||||
|
||||
* Critical battery alarm
|
||||
* High fridge temperature
|
||||
* Communication loss
|
||||
* Sensor failure
|
||||
|
||||
The buzzer should be non-blocking and event-driven.
|
||||
|
||||
---
|
||||
|
||||
# UI Design Goals
|
||||
|
||||
* Touchscreen-only operation
|
||||
* Large buttons
|
||||
* Readable in sunlight
|
||||
* Minimal navigation depth
|
||||
* Fast status visibility
|
||||
* Safe operation while driving
|
||||
|
||||
---
|
||||
|
||||
# Initial Bring-Up Order
|
||||
|
||||
1. Display test
|
||||
2. Touch test
|
||||
3. Buzzer test
|
||||
4. Static UI rendering
|
||||
5. UART communications
|
||||
6. Live status display
|
||||
7. Relay control
|
||||
8. Alarm overlay
|
||||
9. WiFi fallback
|
||||
|
||||
---
|
||||
|
||||
# Out of Scope
|
||||
|
||||
Not currently planned:
|
||||
|
||||
* Persistent logging
|
||||
* Historical graphs
|
||||
* Cloud connectivity
|
||||
* Internet access requirements
|
||||
* User accounts
|
||||
* Remote access
|
||||
|
||||
The system is intended to operate fully offline.
|
||||
@@ -0,0 +1,61 @@
|
||||
# Sensor Architecture
|
||||
|
||||
## Current Sensors
|
||||
|
||||
### Fridge Zone 1
|
||||
|
||||
Purpose:
|
||||
Refrigerator or freezer monitoring.
|
||||
|
||||
Alarm:
|
||||
User configurable.
|
||||
|
||||
### Fridge Zone 2
|
||||
|
||||
Purpose:
|
||||
Refrigerator or freezer monitoring.
|
||||
|
||||
Alarm:
|
||||
User configurable.
|
||||
|
||||
### Rear Seat Area
|
||||
|
||||
Purpose:
|
||||
Monitor child seating area.
|
||||
|
||||
Alarms:
|
||||
- Warning Threshold
|
||||
- Critical Threshold
|
||||
|
||||
### Outside Air
|
||||
|
||||
Purpose:
|
||||
Ambient outside temperature.
|
||||
|
||||
## Future Sensors
|
||||
|
||||
### Battery Bay
|
||||
|
||||
Purpose:
|
||||
Battery compartment monitoring.
|
||||
|
||||
### Cabin Air
|
||||
|
||||
Purpose:
|
||||
Cabin temperature monitoring.
|
||||
|
||||
### Water Tank
|
||||
|
||||
Purpose:
|
||||
Water freeze protection.
|
||||
|
||||
### Cooler
|
||||
|
||||
Purpose:
|
||||
Secondary food storage monitoring.
|
||||
|
||||
## Sensor Bus
|
||||
|
||||
DS18B20 OneWire
|
||||
|
||||
Single bus shared across all sensors.
|
||||
@@ -0,0 +1,70 @@
|
||||
# UART Communication Plan
|
||||
|
||||
## Overview
|
||||
|
||||
The first hardware version will use UART over CAT5 between the Pico dashboard and the ESP32 controller.
|
||||
|
||||
UART is simpler than RS-485 and should be reliable for the short cable run inside the Xterra.
|
||||
|
||||
RS-485 remains a future fallback if testing reveals communication issues.
|
||||
|
||||
## Architecture
|
||||
|
||||
Pico Dashboard
|
||||
|
|
||||
| UART over CAT5
|
||||
|
|
||||
ESP32 Controller
|
||||
|
||||
Backup:
|
||||
WiFi HTTP API
|
||||
|
||||
Fallback:
|
||||
RS-485 over CAT5
|
||||
|
||||
## UART Wiring
|
||||
|
||||
Pico TX -> ESP32 RX
|
||||
Pico RX <- ESP32 TX
|
||||
Ground <-> Ground
|
||||
|
||||
## Planned Baud Rate
|
||||
|
||||
Initial:
|
||||
115200
|
||||
|
||||
Future Options:
|
||||
- 57600
|
||||
- 230400
|
||||
|
||||
## Message Format
|
||||
|
||||
Newline-delimited JSON
|
||||
|
||||
Request:
|
||||
{"type":"status_request"}
|
||||
|
||||
Response:
|
||||
{"type":"status_response"}
|
||||
|
||||
## Failure Handling
|
||||
|
||||
If communication is lost:
|
||||
|
||||
- Dashboard shows warning
|
||||
- Last known values remain visible
|
||||
- Relay commands fail safely
|
||||
- WiFi backup may be attempted
|
||||
|
||||
## Advantages
|
||||
|
||||
- Fewer parts
|
||||
- Easier debugging
|
||||
- Easier wiring
|
||||
- No transceivers
|
||||
- No direction control
|
||||
- Works well for short runs
|
||||
|
||||
## Future RS-485 Option
|
||||
|
||||
If vehicle electrical noise causes issues, the transport layer can be switched to RS-485 without changing application logic.
|
||||
@@ -0,0 +1,230 @@
|
||||
# Pico Dashboard UI Wireframes
|
||||
|
||||
## UI Goals
|
||||
|
||||
* Touchscreen-only
|
||||
* Large touch targets
|
||||
* Readable at a glance
|
||||
* Minimal menu depth
|
||||
* Fast access to relay controls
|
||||
* Alarm visibility from every screen
|
||||
|
||||
## Screen Size
|
||||
|
||||
Target display:
|
||||
|
||||
* 320x480
|
||||
* Portrait orientation
|
||||
* ST7796S
|
||||
|
||||
## Global Layout
|
||||
|
||||
Top status bar:
|
||||
|
||||
* Battery SOC
|
||||
* Communication status
|
||||
* Active alarm indicator
|
||||
|
||||
Bottom navigation bar:
|
||||
|
||||
* Dash
|
||||
* Battery
|
||||
* Temps
|
||||
* Power
|
||||
* System
|
||||
|
||||
## Dashboard Screen
|
||||
|
||||
Purpose:
|
||||
|
||||
Quick system overview.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ SOC 82% UART OK ⚠ 0 │
|
||||
├──────────────────────────────┤
|
||||
│ Battery │
|
||||
│ 13.2V -6.4A 12.0 hr │
|
||||
├──────────────────────────────┤
|
||||
│ Fridge │
|
||||
│ Zone 1: 34.5°F │
|
||||
│ Zone 2: 36.0°F │
|
||||
├──────────────────────────────┤
|
||||
│ Power │
|
||||
│ Starlink OFF Fridge ON │
|
||||
├──────────────────────────────┤
|
||||
│ Dash Bat Temps Power System │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Battery Screen
|
||||
|
||||
Purpose:
|
||||
|
||||
Detailed house battery status.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ SOC 82% UART OK ⚠ 0 │
|
||||
├──────────────────────────────┤
|
||||
│ Battery │
|
||||
│ │
|
||||
│ SOC: 82% │
|
||||
│ Voltage: 13.2V │
|
||||
│ Current: -6.4A │
|
||||
│ Remaining: 82Ah │
|
||||
│ Runtime: 12.0 hr │
|
||||
│ Temp: 76°F │
|
||||
├──────────────────────────────┤
|
||||
│ Dash Bat Temps Power System │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Temperatures Screen
|
||||
|
||||
Purpose:
|
||||
|
||||
Show all DS18B20 temperature sensors and sensor health.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ SOC 82% UART OK ⚠ 0 │
|
||||
├──────────────────────────────┤
|
||||
│ Temperatures │
|
||||
│ │
|
||||
│ Fridge Zone 1 34.5°F OK │
|
||||
│ Fridge Zone 2 36.0°F OK │
|
||||
│ Rear Seat 71.2°F OK │
|
||||
│ Outside Air 89.1°F OK │
|
||||
├──────────────────────────────┤
|
||||
│ Dash Bat Temps Power System │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
Fault example:
|
||||
|
||||
```
|
||||
│ Outside Air --.-°F FAULT │
|
||||
```
|
||||
|
||||
## Power Screen
|
||||
|
||||
Purpose:
|
||||
|
||||
Control accessory relays.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ SOC 82% UART OK ⚠ 0 │
|
||||
├──────────────────────────────┤
|
||||
│ Power Controls │
|
||||
│ │
|
||||
│ Starlink │
|
||||
│ [ OFF ] │
|
||||
│ │
|
||||
│ Fridge │
|
||||
│ [ ON ] │
|
||||
│ │
|
||||
│ Relay board drives Bosch │
|
||||
│ relays only. │
|
||||
├──────────────────────────────┤
|
||||
│ Dash Bat Temps Power System │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## System Screen
|
||||
|
||||
Purpose:
|
||||
|
||||
Show controller and communication health.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ SOC 82% UART OK ⚠ 0 │
|
||||
├──────────────────────────────┤
|
||||
│ System │
|
||||
│ │
|
||||
│ ESP32: Online │
|
||||
│ UART: Connected │
|
||||
│ WiFi API: Available │
|
||||
│ Sensors: 4 / 4 OK │
|
||||
│ Ignition: Off │
|
||||
│ Firmware: TBD │
|
||||
├──────────────────────────────┤
|
||||
│ Dash Bat Temps Power System │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Alarm Overlay
|
||||
|
||||
Critical alarms should appear over any screen.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ CRITICAL ALARM │
|
||||
├──────────────────────────────┤
|
||||
│ Fridge Zone 1 High Temp │
|
||||
│ │
|
||||
│ Current: 48.2°F │
|
||||
│ Limit: 40.0°F │
|
||||
│ │
|
||||
│ [ ACKNOWLEDGE ] │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Touch Target Guidelines
|
||||
|
||||
Minimum target size:
|
||||
|
||||
* 48 px tall
|
||||
* Full-width buttons preferred for critical controls
|
||||
* Avoid small corner-only touch targets
|
||||
|
||||
## Navigation
|
||||
|
||||
Bottom navigation buttons:
|
||||
|
||||
* Dash
|
||||
* Bat
|
||||
* Temps
|
||||
* Power
|
||||
* System
|
||||
|
||||
The active screen should be visually highlighted.
|
||||
|
||||
## Initial UI Priority
|
||||
|
||||
Build order:
|
||||
|
||||
1. Static dashboard screen
|
||||
2. Bottom navigation
|
||||
3. Battery screen
|
||||
4. Temperature screen
|
||||
5. Power screen
|
||||
6. System screen
|
||||
7. Alarm overlay
|
||||
8. Relay command feedback
|
||||
9. Communication failure state
|
||||
|
||||
## Out of Scope for Initial UI
|
||||
|
||||
Not included in first UI version:
|
||||
|
||||
* Graphs
|
||||
* Historical charts
|
||||
* Settings menus
|
||||
* WiFi configuration
|
||||
* Touch keyboard
|
||||
* OTA update controls
|
||||
Reference in New Issue
Block a user