Archive stale documentation
This commit is contained in:
@@ -0,0 +1,13 @@
|
||||
# Legacy Current-Cleanup Archive
|
||||
|
||||
These files were moved out of the active docs during the June 2026 documentation cleanup.
|
||||
|
||||
They are retained for historical reference only. Current source-of-truth docs are:
|
||||
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/HARDWARE.md`
|
||||
- `docs/ROADMAP.md`
|
||||
- `docs/API.md`
|
||||
- `docs/dashboard-esp32s3.md`
|
||||
|
||||
Do not use the archived Pico/UART wiring or handoff notes for current implementation work.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Overland Controller Handoff
|
||||
|
||||
This handoff is stale and may include legacy Pico/UART dashboard assumptions.
|
||||
|
||||
Current source of truth:
|
||||
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/HARDWARE.md`
|
||||
- `docs/ROADMAP.md`
|
||||
- `docs/API.md`
|
||||
- `docs/dashboard-esp32s3.md`
|
||||
|
||||
The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
|
||||
|
||||
## Current Version
|
||||
|
||||
Firmware: 0.4.0
|
||||
|
||||
## Current State
|
||||
|
||||
The ESP32 backend is now the source of truth and is mostly Phase 1 complete.
|
||||
|
||||
Working:
|
||||
|
||||
- ESP32 WebUI
|
||||
- AP + STA WiFi
|
||||
- Multiple saved WiFi networks with priority
|
||||
- Relay control through built-in relay board
|
||||
- JBD/Xiaoxiang BLE BMS telemetry
|
||||
- DS18B20 temperature support
|
||||
- Temperature scan/assign/config workflow
|
||||
- HTTP API
|
||||
- UART JSON protocol
|
||||
- USB serial maintenance commands
|
||||
- Config-driven relay/temp/BMS/device naming
|
||||
- WebUI Config tab for initial setup
|
||||
|
||||
## Important Recent Fix
|
||||
|
||||
Do not use `client->setConnectTimeout()` for the JBD/Xiaoxiang BMS.
|
||||
|
||||
It caused Greta/BMS BLE connection failures.
|
||||
|
||||
Known-good BMS behavior uses the default NimBLE connection timeout.
|
||||
|
||||
## Current Hardware Direction
|
||||
|
||||
Rear enclosure:
|
||||
|
||||
- ESP32 2-relay board
|
||||
- Mini fuse block
|
||||
- Ground bus
|
||||
- DS18B20 distribution board
|
||||
- CAT6 keystone
|
||||
- Built-in relays used for Starlink Mini and fridge
|
||||
- Positive-side relay switching
|
||||
|
||||
Dashboard enclosure:
|
||||
|
||||
- Raspberry Pi Pico 2 W / RP2350
|
||||
- 3.5" 320x480 ST7796S display
|
||||
- FT6336U capacitive touch, wired but not required for MVP
|
||||
- 12V over CAT5e from rear enclosure
|
||||
- Local 12V-to-5V buck converter in dash enclosure
|
||||
- Pico and display powered from dash buck converter
|
||||
|
||||
## CAT5e Plan
|
||||
|
||||
Rear to dash:
|
||||
|
||||
- Two conductors for fused +12V
|
||||
- Two conductors for ground
|
||||
- One conductor for ESP32 TX to Pico RX
|
||||
- One conductor for ESP32 RX to Pico TX
|
||||
- Spare pair reserved
|
||||
|
||||
All grounds are common:
|
||||
|
||||
- ESP32 GND
|
||||
- Buck GND
|
||||
- Pico GND
|
||||
- Display GND
|
||||
- UART GND
|
||||
|
||||
## Pico Display Solder Map
|
||||
|
||||
Display:
|
||||
|
||||
- VCC -> 5V buck output
|
||||
- GND -> GND
|
||||
- SCLK -> Pico GPIO18 / Pin 24
|
||||
- MOSI -> Pico GPIO19 / Pin 25
|
||||
- LCD_CS -> Pico GPIO17 / Pin 22
|
||||
- LCD_DC -> Pico GPIO16 / Pin 21
|
||||
- LCD_RST -> Pico GPIO20 / Pin 26
|
||||
- LCD_BL -> Pico GPIO21 / Pin 27
|
||||
|
||||
Touch, wired for future:
|
||||
|
||||
- TP_SDA -> Pico GPIO26 / Pin 31
|
||||
- TP_SCL -> Pico GPIO27 / Pin 32
|
||||
- TP_INT -> Pico GPIO28 / Pin 34
|
||||
- TP_RST -> Pico GPIO15 / Pin 20
|
||||
|
||||
UART to ESP32 dashboard UART:
|
||||
|
||||
- Pico GPIO0 / Pin 1 RX <- ESP32 GPIO21 TX
|
||||
- Pico GPIO1 / Pin 2 TX -> ESP32 GPIO22 RX
|
||||
- Pico GND -> ESP32 GND
|
||||
|
||||
Do not use the ESP32 6-pin UART header for dashboard UART. It has continuity to RXD and is likely UART0/programming/debug.
|
||||
|
||||
## Pico MVP Goal
|
||||
|
||||
MVP means Minimum Viable Product.
|
||||
|
||||
Pico MVP should be read-only first:
|
||||
|
||||
- Request status from ESP32 over UART
|
||||
- Parse JSON status response
|
||||
- Display battery SOC, voltage, current, runtime/time-to-full
|
||||
- Display temps
|
||||
- Display relay states
|
||||
- Display ESP32 connection status
|
||||
|
||||
No touch controls for MVP.
|
||||
|
||||
## Runtime / Time-To-Full Logic
|
||||
|
||||
If BMS current is negative/discharging:
|
||||
|
||||
runtime_hours = remaining_ah / abs(current)
|
||||
|
||||
If BMS current is positive/charging:
|
||||
|
||||
time_to_full_hours = (capacity_ah - remaining_ah) / current
|
||||
|
||||
If current is near zero:
|
||||
|
||||
show Idle
|
||||
|
||||
## Next Work
|
||||
|
||||
1. Build Pico MVP.
|
||||
2. First prove UART status over USB serial.
|
||||
3. Then prove display Hello World.
|
||||
4. Then draw read-only dashboard.
|
||||
5. Later add touch navigation and relay controls.
|
||||
6. Later add config backup/restore.
|
||||
7. Later improve BMS out-of-range behavior without changing NimBLE connect timeout.
|
||||
|
||||
|
||||
|
||||
## Dashboard Direction
|
||||
|
||||
Current dashboard target:
|
||||
|
||||
- Waveshare 5" ESP32-S3 Display
|
||||
- WiFi client
|
||||
- Connects to cargo ESP32 AP
|
||||
- Uses existing HTTP API
|
||||
- Planned LVGL implementation
|
||||
|
||||
Important:
|
||||
|
||||
- ESP32 cargo controller remains source of truth.
|
||||
- Dashboard is a client only.
|
||||
- Existing UART protocol remains supported but is no longer the primary dashboard transport.
|
||||
|
||||
See `docs/dashboard-esp32s3.md` for the current Waveshare ESP32-S3 dashboard plan.
|
||||
@@ -0,0 +1,505 @@
|
||||
# Hardware Status
|
||||
|
||||
Last Updated: 2026-06-03
|
||||
|
||||
This document is stale and records earlier hardware ordering/status notes. Current hardware direction is documented in `docs/HARDWARE.md` and `docs/dashboard-esp32s3.md`.
|
||||
|
||||
The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Dashboard Hardware
|
||||
|
||||
### Raspberry Pi Pico 2 W
|
||||
|
||||
Status:
|
||||
- Ordered
|
||||
|
||||
Purpose:
|
||||
- Dashboard controller
|
||||
- Touchscreen UI
|
||||
- Audible alarms
|
||||
- UART communications
|
||||
|
||||
Notes:
|
||||
- Waiting for delivery
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### 3.5 Inch Touchscreen
|
||||
|
||||
Display Controller:
|
||||
- ST7796S
|
||||
|
||||
Touch Controller:
|
||||
- FT6336U
|
||||
|
||||
Status:
|
||||
- Ordered
|
||||
|
||||
Purpose:
|
||||
- Main dashboard display
|
||||
|
||||
Testing Required:
|
||||
- Display initialization
|
||||
- Touch functionality
|
||||
- Performance testing
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### Active 5V Buzzer
|
||||
|
||||
Status:
|
||||
- Ordered
|
||||
|
||||
Purpose:
|
||||
- Audible alarms
|
||||
|
||||
Testing Required:
|
||||
- Alarm volume
|
||||
- Dashboard mounting location
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Controller Hardware
|
||||
|
||||
### ESP32 2-Channel Relay Board
|
||||
|
||||
Status:
|
||||
- On Hand
|
||||
|
||||
Purpose:
|
||||
- Relay control
|
||||
- Sensor collection
|
||||
- Communications
|
||||
|
||||
Known Information:
|
||||
|
||||
GPIO16 = Relay Output 1
|
||||
GPIO17 = Relay Output 2
|
||||
|
||||
Relay ON = HIGH
|
||||
Relay OFF = LOW
|
||||
|
||||
Testing Required:
|
||||
- Verify relay operation
|
||||
- Verify startup behavior
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Communications Hardware
|
||||
|
||||
### CAT5 Cable
|
||||
|
||||
Status:
|
||||
- On Hand
|
||||
|
||||
Purpose:
|
||||
- Dashboard power
|
||||
- UART communications
|
||||
- Ignition sense
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### RS485 Modules
|
||||
|
||||
Status:
|
||||
- Ordered
|
||||
|
||||
Purpose:
|
||||
- Future fallback communication
|
||||
|
||||
Current Plan:
|
||||
- Not used initially
|
||||
|
||||
Testing Required:
|
||||
- Only if UART proves unreliable
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Sensor Hardware
|
||||
|
||||
### DS18B20 Waterproof Sensors
|
||||
|
||||
Quantity:
|
||||
- 4
|
||||
|
||||
Status:
|
||||
- Ordered
|
||||
|
||||
Assignments:
|
||||
|
||||
Sensor 1
|
||||
- Fridge Zone 1
|
||||
|
||||
Sensor 2
|
||||
- Fridge Zone 2
|
||||
|
||||
Sensor 3
|
||||
- Rear Seat Area
|
||||
|
||||
Sensor 4
|
||||
- Outside Air
|
||||
|
||||
Testing Required:
|
||||
- Address discovery
|
||||
- Temperature validation
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Power Hardware
|
||||
|
||||
### 12V To 5V Buck Converter
|
||||
|
||||
Status:
|
||||
- Planned
|
||||
|
||||
Purpose:
|
||||
- Dashboard power
|
||||
|
||||
Requirements:
|
||||
|
||||
Input:
|
||||
- Vehicle 12V
|
||||
|
||||
Output:
|
||||
- 5V
|
||||
|
||||
Recommended:
|
||||
- 3A minimum
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### Bosch Relays
|
||||
|
||||
Status:
|
||||
- Planned
|
||||
|
||||
Purpose:
|
||||
- Starlink power
|
||||
- Fridge power
|
||||
|
||||
Future:
|
||||
- Inverter
|
||||
- Camp lights
|
||||
|
||||
Requirements:
|
||||
- 30A or 40A automotive relays
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### Fuse Block
|
||||
|
||||
Status:
|
||||
- Planned
|
||||
|
||||
Purpose:
|
||||
- Circuit protection
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Future Hardware
|
||||
|
||||
### JBD / Xiaoxiang BMS
|
||||
|
||||
Status:
|
||||
- Existing battery system
|
||||
|
||||
Purpose:
|
||||
- Battery monitoring
|
||||
|
||||
Future Integration:
|
||||
- BLE communications
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### ELM327
|
||||
|
||||
Status:
|
||||
- Future
|
||||
|
||||
Purpose:
|
||||
- OBD-II integration
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
### GPS Module
|
||||
|
||||
Status:
|
||||
- Future
|
||||
|
||||
Purpose:
|
||||
- Vehicle tracking
|
||||
- Trip logging
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Bring-Up Checklist
|
||||
|
||||
ESP32
|
||||
|
||||
[ ] Verify relay outputs
|
||||
[ ] Verify WiFi AP
|
||||
[ ] Verify HTTP status endpoint
|
||||
[ ] Verify DS18B20 support
|
||||
|
||||
Pico
|
||||
|
||||
[ ] Display test
|
||||
[ ] Touch test
|
||||
[ ] Buzzer test
|
||||
[ ] UART communications
|
||||
|
||||
Vehicle
|
||||
|
||||
[ ] Install CAT5 run
|
||||
[ ] Install buck converter
|
||||
[ ] Install relays
|
||||
[ ] Install sensors
|
||||
[ ] Install dashboard enclosure
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Notes
|
||||
|
||||
Current Communication Plan:
|
||||
|
||||
Primary:
|
||||
- UART over CAT5
|
||||
|
||||
Backup:
|
||||
- WiFi HTTP API
|
||||
|
||||
Fallback:
|
||||
- RS485
|
||||
|
||||
Current UI Plan:
|
||||
|
||||
- Touchscreen only
|
||||
- No physical buttons required
|
||||
|
||||
Current Logging Plan:
|
||||
|
||||
- No persistent logging planned
|
||||
- Focus on live monitoring and alarms
|
||||
|
||||
## ESP32 Cargo Controller Bring-Up Results
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-04
|
||||
|
||||
### Hardware
|
||||
|
||||
- ESP32 2-channel relay board
|
||||
- ESP32-WROOM-32
|
||||
- Integrated dual relay module
|
||||
|
||||
### Firmware Status
|
||||
|
||||
- Firmware compiles successfully
|
||||
- Firmware uploads successfully
|
||||
- Board boots reliably
|
||||
- No watchdog resets observed
|
||||
|
||||
### WiFi Access Point
|
||||
|
||||
Status: PASS
|
||||
|
||||
Verified:
|
||||
|
||||
- AP starts correctly
|
||||
- SSID visible
|
||||
- Client devices can connect
|
||||
- HTTP API accessible
|
||||
|
||||
### Status Endpoint
|
||||
|
||||
Status: PASS
|
||||
|
||||
Endpoint:
|
||||
|
||||
/status
|
||||
|
||||
Issue Found:
|
||||
|
||||
- Original streaming JSON implementation produced malformed responses
|
||||
- Browser reported "cannot parse response"
|
||||
|
||||
Resolution:
|
||||
|
||||
- Replaced streamed response with serialized JSON string response
|
||||
|
||||
Result:
|
||||
|
||||
- Valid JSON returned successfully
|
||||
|
||||
### Relay Control
|
||||
|
||||
Status: PASS
|
||||
|
||||
Verified:
|
||||
|
||||
/relay/starlink/on
|
||||
/relay/starlink/off
|
||||
/relay/fridge/on
|
||||
/relay/fridge/off
|
||||
|
||||
Results:
|
||||
|
||||
- Relay 1 responds correctly
|
||||
- Relay 2 responds correctly
|
||||
- Relay state updates correctly
|
||||
- Relay state reflected correctly in status API
|
||||
|
||||
### Relay Default State
|
||||
|
||||
Issue Found:
|
||||
|
||||
- Fridge relay defaulted to ON
|
||||
|
||||
Root Cause:
|
||||
|
||||
bool fridge = true;
|
||||
|
||||
Resolution:
|
||||
|
||||
bool fridge = false;
|
||||
|
||||
Result:
|
||||
|
||||
- Both relays now default OFF at boot
|
||||
|
||||
### DS18B20 Testing
|
||||
|
||||
Status: BLOCKED
|
||||
|
||||
Hardware:
|
||||
|
||||
- Waterproof DS18B20 sensors
|
||||
- 5 meter leads
|
||||
|
||||
Current Result:
|
||||
|
||||
- Sensors not detected
|
||||
|
||||
Likely Cause:
|
||||
|
||||
- Missing 4.7kΩ pull-up resistor on 1-Wire bus
|
||||
|
||||
Planned Fix:
|
||||
|
||||
- Install 4.7kΩ resistor between GPIO4 and 3.3V
|
||||
- Retest sensor detection
|
||||
|
||||
### Overall Milestone Status
|
||||
|
||||
ESP32 Hardware Bring-Up
|
||||
|
||||
Status: COMPLETE
|
||||
|
||||
Completed:
|
||||
|
||||
- Boot validation
|
||||
- WiFi validation
|
||||
- HTTP API validation
|
||||
- Relay validation
|
||||
|
||||
Remaining:
|
||||
|
||||
- DS18B20 validation after resistor installation
|
||||
|
||||
|
||||
## JBD/Xiaoxiang BMS Bring-Up Results
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-04
|
||||
|
||||
### Hardware
|
||||
|
||||
- DGJBD / Xiaoxiang-compatible BMS
|
||||
- Bluetooth name: Greta
|
||||
- ESP32 BLE address: a5:c2:37:2c:05:dc
|
||||
- Battery capacity: 150Ah
|
||||
- Chemistry: 4S LiFePO4
|
||||
|
||||
### BLE Discovery
|
||||
|
||||
Status: PASS
|
||||
|
||||
Verified BLE service and characteristics:
|
||||
|
||||
- Service: 0xff00
|
||||
- Notify characteristic: 0xff01
|
||||
- Write characteristic: 0xff02
|
||||
- Write mode: write without response
|
||||
|
||||
### BMS Read Test
|
||||
|
||||
Status: PASS
|
||||
|
||||
Verified JBD basic status command:
|
||||
|
||||
DD A5 03 00 FF FD 77
|
||||
|
||||
Confirmed live values:
|
||||
|
||||
- SOC: 70%
|
||||
- Pack voltage: 13.34V
|
||||
- Current: 0.00A
|
||||
- Remaining capacity: 104.88Ah
|
||||
- Nominal capacity: 150.00Ah
|
||||
- Cycle count: 3
|
||||
- Cell count: 4
|
||||
- Temperature: approximately 67.6°F
|
||||
|
||||
### ESP32 Firmware Integration
|
||||
|
||||
Status: PASS
|
||||
|
||||
Verified:
|
||||
|
||||
- Main firmware connects to BMS
|
||||
- BMS data is read repeatedly
|
||||
- BMS data is parsed correctly
|
||||
- Serial monitor reports live SOC, voltage, current, and remaining Ah
|
||||
|
||||
### Notes
|
||||
|
||||
- First BMS read after boot may time out.
|
||||
- Subsequent reads succeed consistently.
|
||||
- Current implementation reads basic pack telemetry only.
|
||||
- Cell voltage and cell delta support will require an additional JBD command.
|
||||
|
||||
## JBD Cell Voltage Bring-Up Results
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-04
|
||||
|
||||
### Status
|
||||
|
||||
PASS
|
||||
|
||||
### Verified
|
||||
|
||||
- JBD cell voltage command works
|
||||
- ESP32 receives cell voltage packet
|
||||
- Firmware parses 4 cell voltages
|
||||
- Firmware calculates min cell voltage
|
||||
- Firmware calculates max cell voltage
|
||||
- Firmware calculates cell delta
|
||||
|
||||
### Observed Values
|
||||
|
||||
- Cell count: 4
|
||||
- Minimum cell voltage: 3.336V
|
||||
- Maximum cell voltage: 3.337V
|
||||
- Cell delta: 1mV
|
||||
|
||||
### Notes
|
||||
|
||||
- Pack appears well balanced.
|
||||
- First BMS status read after boot may timeout, but subsequent reads succeed.
|
||||
- This behavior is acceptable for current bring-up.
|
||||
@@ -0,0 +1,163 @@
|
||||
# Legacy UART Communication Protocol
|
||||
|
||||
## Current Decision
|
||||
|
||||
Primary dashboard communication is **WiFi HTTP API** between the Waveshare ESP32-S3 dashboard and the Cargo ESP32.
|
||||
|
||||
This legacy UART protocol is retained for historical reference, diagnostics, simulator work, or alternate clients. It is not the current dashboard architecture.
|
||||
|
||||
RS-485/MAX3485 is fallback-only and is not currently planned.
|
||||
|
||||
## Physical Link
|
||||
|
||||
* Transport: UART
|
||||
* Baud: 115200
|
||||
* Format: 8N1
|
||||
* Framing: newline-delimited JSON
|
||||
* Direction: UART client ↔ ESP32 cargo controller
|
||||
|
||||
## Message Rules
|
||||
|
||||
Each message is one JSON object followed by a newline.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
{"type":"status_request"}
|
||||
```
|
||||
|
||||
Responses should also be one JSON object followed by a newline.
|
||||
|
||||
## Client → ESP32 Messages
|
||||
|
||||
### Status Request
|
||||
|
||||
```
|
||||
{"type":"status_request"}
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```
|
||||
{"type":"status_response"}
|
||||
```
|
||||
|
||||
### Set Relay
|
||||
|
||||
```
|
||||
{
|
||||
"type": "set_relay",
|
||||
"relay": "starlink",
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
Valid relay names:
|
||||
|
||||
* starlink
|
||||
* fridge
|
||||
|
||||
Expected response:
|
||||
|
||||
```
|
||||
{
|
||||
"type": "relay_response",
|
||||
"relay": "starlink",
|
||||
"enabled": true,
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
## ESP32 → Client Messages
|
||||
|
||||
### Status Response
|
||||
|
||||
```
|
||||
{
|
||||
"type": "status_response",
|
||||
"timestamp": 123456,
|
||||
"battery": {
|
||||
"soc": 82.0,
|
||||
"voltage": 13.2,
|
||||
"current": -6.4,
|
||||
"remaining_ah": 82.0,
|
||||
"runtime_hours": 12.0,
|
||||
"temperature_f": 76.0
|
||||
},
|
||||
"temps": {
|
||||
"fridge_zone_1": 34.5,
|
||||
"fridge_zone_2": 36.0,
|
||||
"rear_seat": 71.2,
|
||||
"outside": 89.1
|
||||
},
|
||||
"sensor_health": {
|
||||
"fridge_zone_1": true,
|
||||
"fridge_zone_2": true,
|
||||
"rear_seat": true,
|
||||
"outside": true
|
||||
},
|
||||
"relays": {
|
||||
"starlink": false,
|
||||
"fridge": true
|
||||
},
|
||||
"vehicle": {
|
||||
"ignition_on": false
|
||||
},
|
||||
"network": {
|
||||
"wifi_enabled": true,
|
||||
"uart_connected": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Response
|
||||
|
||||
```
|
||||
{
|
||||
"type": "error",
|
||||
"message": "unknown_message_type"
|
||||
}
|
||||
```
|
||||
|
||||
Known error messages:
|
||||
|
||||
* invalid_json
|
||||
* unknown_message_type
|
||||
* unknown_relay
|
||||
* message_too_long
|
||||
|
||||
## Sensor Null Handling
|
||||
|
||||
If a DS18B20 sensor is missing or faulted, its temperature value should be null.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
{
|
||||
"temps": {
|
||||
"fridge_zone_1": null
|
||||
},
|
||||
"sensor_health": {
|
||||
"fridge_zone_1": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Current Scope
|
||||
|
||||
The protocol currently supports:
|
||||
|
||||
* Live status polling
|
||||
* Relay control
|
||||
* Temperature reporting
|
||||
* Sensor health reporting
|
||||
* Basic error reporting
|
||||
|
||||
The protocol does not currently include:
|
||||
|
||||
* Persistent logging
|
||||
* Historical data sync
|
||||
* OTA updates
|
||||
* BMS write/config commands
|
||||
* Starlink diagnostic integration
|
||||
* GPS/OBD-II data
|
||||
@@ -0,0 +1,40 @@
|
||||
# Temperature API
|
||||
|
||||
## Scan
|
||||
|
||||
POST
|
||||
|
||||
/temps/scan
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"type":"temp_scan_response",
|
||||
"ok":true
|
||||
}
|
||||
|
||||
## Assign
|
||||
|
||||
POST
|
||||
|
||||
/temps/assign
|
||||
|
||||
Body:
|
||||
|
||||
{
|
||||
"id":"temp_1",
|
||||
"index":1
|
||||
}
|
||||
|
||||
## Clear
|
||||
|
||||
POST
|
||||
|
||||
/temps/clear
|
||||
|
||||
Body:
|
||||
|
||||
{
|
||||
"id":"temp_1"
|
||||
}
|
||||
|
||||
@@ -0,0 +1,663 @@
|
||||
# Wiring
|
||||
|
||||
This document contains older wiring notes and may include legacy Pico/UART dashboard assumptions.
|
||||
|
||||
Current dashboard and hardware source of truth:
|
||||
|
||||
- `docs/HARDWARE.md`
|
||||
- `docs/dashboard-esp32s3.md`
|
||||
|
||||
Do not use Pico-specific wiring in this file for the current dashboard build.
|
||||
|
||||
Current planned system uses:
|
||||
|
||||
- Cargo ESP32 2-relay controller board
|
||||
- Waveshare ESP32-S3-Touch-LCD-5 dashboard over WiFi/HTTP
|
||||
- ACC switched 12V fused dashboard power into Waveshare VIN
|
||||
- DS18B20 temperature sensors
|
||||
- JBD/Xiaoxiang BMS over BLE
|
||||
- External fused automotive relays or contactors for major loads
|
||||
|
||||
---
|
||||
|
||||
## Current ESP32 Relay Board
|
||||
|
||||
Board markings:
|
||||
|
||||
ESP32_Relay_X2
|
||||
|
||||
Relay contact terminals:
|
||||
|
||||
NO1 COM1 NC1 NO2 COM2 NC2
|
||||
|
||||
Power terminal:
|
||||
|
||||
VCC GND 5V
|
||||
|
||||
UART/programming header:
|
||||
|
||||
IO0 GND GND RX TX 5V
|
||||
|
||||
Firmware relay mapping:
|
||||
|
||||
relay_1 = GPIO16
|
||||
relay_2 = GPIO17
|
||||
|
||||
---
|
||||
|
||||
## System Power Overview
|
||||
|
||||
Plain text diagram:
|
||||
|
||||
House Battery +
|
||||
|
|
||||
+---- Main fuse / distribution
|
||||
|
|
||||
+---- 2A fuse --------------------> ESP32 relay board VCC
|
||||
|
|
||||
+---- 1A or 2A fuse --------------> CAT5 blue pair to dash +12V
|
||||
|
|
||||
+---- Load fuse ------------------> Automotive relay #1 pin 30
|
||||
|
|
||||
+---- Load fuse ------------------> Automotive relay #2 pin 30
|
||||
|
||||
House Battery -
|
||||
|
|
||||
+---------------------------------> Common ground bus
|
||||
|
|
||||
+--> ESP32 relay board GND
|
||||
+--> CAT5 green pair to dash GND
|
||||
+--> Automotive relay coil grounds
|
||||
+--> Load grounds
|
||||
|
||||
Notes:
|
||||
|
||||
- Fuse every positive feed.
|
||||
- Keep all grounds common.
|
||||
- Do not run high-current loads directly through the ESP32 relay board.
|
||||
- Use the ESP32 relay board to trigger automotive relays.
|
||||
|
||||
---
|
||||
|
||||
## ESP32 Board Power
|
||||
|
||||
Use the bottom-right power terminal:
|
||||
|
||||
VCC GND 5V
|
||||
|
||||
Recommended wiring:
|
||||
|
||||
House battery +
|
||||
|
|
||||
+-- 2A fuse
|
||||
|
|
||||
+---> ESP32 VCC
|
||||
|
||||
House battery -
|
||||
|
|
||||
+---> ESP32 GND
|
||||
|
||||
Leave the ESP32 board 5V terminal unused unless verified for your exact board/power setup.
|
||||
|
||||
---
|
||||
|
||||
## Pico Dashboard Power Over CAT5
|
||||
|
||||
The dash Pico should be powered from a buck converter inside the dash enclosure.
|
||||
|
||||
Rear compartment:
|
||||
|
||||
House battery +
|
||||
|
|
||||
+-- 1A or 2A fuse
|
||||
|
|
||||
+---> CAT5 blue/white + blue conductors
|
||||
|
||||
House battery -
|
||||
|
|
||||
+---> CAT5 green/white + green conductors
|
||||
|
||||
Dash enclosure:
|
||||
|
||||
CAT5 blue pair +12V
|
||||
|
|
||||
+---> Buck converter IN+
|
||||
|
||||
CAT5 green pair GND
|
||||
|
|
||||
+---> Buck converter IN-
|
||||
|
||||
Buck converter OUT+ 5V
|
||||
|
|
||||
+---> Pico VSYS
|
||||
|
||||
Buck converter OUT- GND
|
||||
|
|
||||
+---> Pico GND
|
||||
|
||||
Important:
|
||||
|
||||
- Do not connect 5V to Pico 3V3.
|
||||
- Use Pico VSYS for 5V input.
|
||||
- Keep ESP32 GND and Pico GND connected through the CAT5 ground pair.
|
||||
|
||||
---
|
||||
|
||||
## CAT5 / CAT6 Cable Plan
|
||||
|
||||
Recommended CAT5/CAT6 wiring between the rear ESP32 controller and dash Pico:
|
||||
|
||||
Orange/White ESP32 TX ---> Pico GP1 RX
|
||||
Orange ESP32 RX <--- Pico GP0 TX
|
||||
|
||||
Green/White Ground
|
||||
Green Ground
|
||||
|
||||
Blue/White +12V fused dash feed
|
||||
Blue +12V fused dash feed
|
||||
|
||||
Brown/White Spare
|
||||
Brown Spare
|
||||
|
||||
Notes:
|
||||
|
||||
- Use two conductors for +12V.
|
||||
- Use two conductors for ground.
|
||||
- UART requires shared ground.
|
||||
- Brown pair is reserved for future expansion.
|
||||
|
||||
---
|
||||
|
||||
## Pico 2 W UART Pins
|
||||
|
||||
Recommended Pico UART pins:
|
||||
|
||||
Pico GP0 = UART0 TX
|
||||
Pico GP1 = UART0 RX
|
||||
|
||||
Connection:
|
||||
|
||||
ESP32 TX ---> Pico GP1 RX
|
||||
ESP32 RX <--- Pico GP0 TX
|
||||
ESP32 GND ---> Pico GND
|
||||
|
||||
Do not connect ESP32 5V to Pico unless intentionally using it as a power source.
|
||||
|
||||
Current plan is to power Pico from local dash buck converter instead.
|
||||
|
||||
---
|
||||
|
||||
## ESP32 UART Header
|
||||
|
||||
The ESP32 relay board exposes a 6-pin header:
|
||||
|
||||
IO0 GND GND RX TX 5V
|
||||
|
||||
Use:
|
||||
|
||||
TX ---> Pico GP1 RX
|
||||
RX <--- Pico GP0 TX
|
||||
GND ---> Pico GND
|
||||
|
||||
Do not use IO0 for dashboard wiring.
|
||||
|
||||
Do not use 5V for dashboard power in the current design.
|
||||
|
||||
---
|
||||
|
||||
## DS18B20 Temperature Sensor Bus
|
||||
|
||||
Recommended ESP32 GPIO:
|
||||
|
||||
GPIO4
|
||||
|
||||
All DS18B20 sensors share one 1-Wire data bus.
|
||||
|
||||
Plain text diagram:
|
||||
|
||||
ESP32 3.3V
|
||||
|
|
||||
+---- 4.7k pull-up resistor
|
||||
|
|
||||
ESP32 GPIO4 --------------------+---- DS18B20 Sensor 1 data
|
||||
|
|
||||
+---- DS18B20 Sensor 2 data
|
||||
|
|
||||
+---- DS18B20 Sensor 3 data
|
||||
|
|
||||
+---- DS18B20 Sensor 4 data
|
||||
|
|
||||
+---- Additional sensors up to temp_8
|
||||
|
||||
ESP32 3.3V -------------------------- DS18B20 red wires
|
||||
ESP32 GND -------------------------- DS18B20 black wires
|
||||
ESP32 GPIO4 ------------------------- DS18B20 data wires
|
||||
|
||||
Typical waterproof DS18B20 wiring:
|
||||
|
||||
Red = 3.3V
|
||||
Black = GND
|
||||
Yellow = Data
|
||||
|
||||
Important:
|
||||
|
||||
- A 4.7k resistor is required between 3.3V and data.
|
||||
- One pull-up resistor is used for the whole bus.
|
||||
- Do not use one resistor per sensor.
|
||||
- Long leads may need clean splices and good grounding.
|
||||
|
||||
---
|
||||
|
||||
## BMS Connection
|
||||
|
||||
The JBD/Xiaoxiang BMS is wireless.
|
||||
|
||||
Connection:
|
||||
|
||||
ESP32 <---- BLE ----> JBD/Xiaoxiang BMS
|
||||
|
||||
No physical BMS data wiring is currently required.
|
||||
|
||||
The BMS Bluetooth address is stored in controller configuration.
|
||||
|
||||
---
|
||||
|
||||
## Relay Control Strategy
|
||||
|
||||
The onboard ESP32 relays should trigger automotive relays.
|
||||
|
||||
They should not directly power large vehicle loads.
|
||||
|
||||
Recommended pattern:
|
||||
|
||||
ESP32 onboard relay
|
||||
|
|
||||
+-- switches automotive relay coil
|
||||
|
|
||||
+-- automotive relay switches load power
|
||||
|
||||
This keeps high current off the ESP32 board.
|
||||
|
||||
---
|
||||
|
||||
## Relay 1 Automotive Relay Wiring
|
||||
|
||||
Example installation-specific name:
|
||||
|
||||
relay_1 = Starlink
|
||||
|
||||
ESP32 board contact terminals:
|
||||
|
||||
COM1
|
||||
NO1
|
||||
|
||||
Automotive relay wiring:
|
||||
|
||||
House battery +
|
||||
|
|
||||
+-- load fuse
|
||||
|
|
||||
+---> Automotive relay pin 30
|
||||
|
||||
Automotive relay pin 87
|
||||
|
|
||||
+---> Load positive
|
||||
|
||||
Load negative
|
||||
|
|
||||
+---> Ground bus
|
||||
|
||||
Automotive relay pin 85
|
||||
|
|
||||
+---> Ground bus
|
||||
|
||||
Automotive relay pin 86
|
||||
|
|
||||
+---> Switched positive from ESP32 relay COM1/NO1 circuit
|
||||
|
||||
ESP32 relay contact wiring concept:
|
||||
|
||||
Fused low-current +12V
|
||||
|
|
||||
+---> ESP32 relay COM1
|
||||
|
||||
ESP32 relay NO1
|
||||
|
|
||||
+---> Automotive relay pin 86
|
||||
|
||||
When relay_1 turns on, COM1 connects to NO1 and energizes the automotive relay coil.
|
||||
|
||||
---
|
||||
|
||||
## Relay 2 Automotive Relay Wiring
|
||||
|
||||
Example installation-specific name:
|
||||
|
||||
relay_2 = Fridge
|
||||
|
||||
ESP32 board contact terminals:
|
||||
|
||||
COM2
|
||||
NO2
|
||||
|
||||
Automotive relay wiring:
|
||||
|
||||
House battery +
|
||||
|
|
||||
+-- load fuse
|
||||
|
|
||||
+---> Automotive relay pin 30
|
||||
|
||||
Automotive relay pin 87
|
||||
|
|
||||
+---> Load positive
|
||||
|
||||
Load negative
|
||||
|
|
||||
+---> Ground bus
|
||||
|
||||
Automotive relay pin 85
|
||||
|
|
||||
+---> Ground bus
|
||||
|
||||
Automotive relay pin 86
|
||||
|
|
||||
+---> Switched positive from ESP32 relay COM2/NO2 circuit
|
||||
|
||||
ESP32 relay contact wiring concept:
|
||||
|
||||
Fused low-current +12V
|
||||
|
|
||||
+---> ESP32 relay COM2
|
||||
|
||||
ESP32 relay NO2
|
||||
|
|
||||
+---> Automotive relay pin 86
|
||||
|
||||
When relay_2 turns on, COM2 connects to NO2 and energizes the automotive relay coil.
|
||||
|
||||
---
|
||||
|
||||
## Automotive Relay Pin Reference
|
||||
|
||||
Common Bosch-style relay pins:
|
||||
|
||||
30 = Common load power input
|
||||
87 = Normally open load output
|
||||
87a = Normally closed output, if present
|
||||
85 = Coil side
|
||||
86 = Coil side
|
||||
|
||||
Recommended use:
|
||||
|
||||
30 = fused battery positive
|
||||
87 = load positive
|
||||
85 = ground
|
||||
86 = switched positive from ESP32 relay board
|
||||
|
||||
---
|
||||
|
||||
## Future Reserved Inputs
|
||||
|
||||
Do not wire these yet unless firmware support has been added.
|
||||
|
||||
Recommended reservations:
|
||||
|
||||
GPIO34 = Ignition sense input
|
||||
GPIO35 = House battery voltage sense input
|
||||
|
||||
Reason:
|
||||
|
||||
- GPIO34 and GPIO35 are input-only.
|
||||
- Input-only pins are appropriate for sensing.
|
||||
- They are not appropriate for relay outputs.
|
||||
|
||||
Important:
|
||||
|
||||
Never connect vehicle 12V directly to an ESP32 GPIO.
|
||||
|
||||
Use a voltage divider or proper interface circuit.
|
||||
|
||||
---
|
||||
|
||||
## Current Version 1 Wiring Summary
|
||||
|
||||
Current required physical wiring:
|
||||
|
||||
ESP32 board VCC/GND from fused house battery power
|
||||
|
||||
ESP32 TX/RX/GND to Pico over CAT5
|
||||
|
||||
12V fused dash feed and ground to Pico dash enclosure over CAT5
|
||||
|
||||
Dash buck converter 12V to 5V
|
||||
|
||||
Buck 5V to Pico VSYS
|
||||
|
||||
ESP32 GPIO4 to DS18B20 1-Wire bus
|
||||
|
||||
4.7k pull-up from GPIO4 data bus to 3.3V
|
||||
|
||||
ESP32 relay COM/NO contacts to automotive relay coils
|
||||
|
||||
Automotive relays to actual high-current loads
|
||||
|
||||
ESP32 BLE to JBD/Xiaoxiang BMS
|
||||
|
||||
---
|
||||
|
||||
## Safety Notes
|
||||
|
||||
- Fuse every positive feed.
|
||||
- Use proper wire gauge for each load.
|
||||
- Keep high-current wiring separate from signal wiring where possible.
|
||||
- Use common ground between ESP32, Pico, buck converter, relays, sensors, and battery.
|
||||
- Do not connect 12V directly to any ESP32 or Pico GPIO.
|
||||
- Do not power high-current loads directly through the ESP32 relay board.
|
||||
- Test relay behavior with a multimeter before connecting expensive loads.
|
||||
|
||||
---
|
||||
|
||||
## Dash Power Revision
|
||||
|
||||
The current preferred dashboard power plan is to send fused 12V over the CAT5/CAT6 run and regulate it in the dash enclosure.
|
||||
|
||||
Rear compartment:
|
||||
|
||||
House battery +
|
||||
|
|
||||
+-- 1A or 2A fuse
|
||||
|
|
||||
+---> CAT5/CAT6 blue pair
|
||||
|
||||
House battery -
|
||||
|
|
||||
+---> CAT5/CAT6 green pair
|
||||
|
||||
Dash enclosure:
|
||||
|
||||
CAT5/CAT6 blue pair
|
||||
|
|
||||
+---> Buck converter IN+
|
||||
|
||||
CAT5/CAT6 green pair
|
||||
|
|
||||
+---> Buck converter IN-
|
||||
|
||||
Buck converter OUT+ 5V
|
||||
|
|
||||
+---> Pico VSYS
|
||||
|
||||
Buck converter OUT- GND
|
||||
|
|
||||
+---> Pico GND
|
||||
|
||||
Reason:
|
||||
|
||||
- Less voltage drop concern than sending 5V over the full cable run
|
||||
- Clean local 5V regulation at the dashboard
|
||||
- Pico/display power stays independent from the ESP32 board regulator
|
||||
|
||||
Important:
|
||||
|
||||
- Do not connect 12V directly to Pico.
|
||||
- Do not connect 5V to Pico 3V3.
|
||||
- Use Pico VSYS for 5V input.
|
||||
|
||||
---
|
||||
|
||||
## CAT5/CAT6 Updated Plan
|
||||
|
||||
Recommended cable assignment:
|
||||
|
||||
Orange/White ESP32 TX ---> Pico GP1 RX
|
||||
Orange ESP32 RX <--- Pico GP0 TX
|
||||
|
||||
Green/White Ground
|
||||
Green Ground
|
||||
|
||||
Blue/White +12V fused dash feed
|
||||
Blue +12V fused dash feed
|
||||
|
||||
Brown/White Spare
|
||||
Brown Spare
|
||||
|
||||
Notes:
|
||||
|
||||
- Blue pair carries fused 12V to the dash buck converter.
|
||||
- Green pair carries ground.
|
||||
- Orange pair carries UART.
|
||||
- Brown pair remains spare.
|
||||
|
||||
---
|
||||
|
||||
## Compact Enclosure Direction
|
||||
|
||||
Current rear enclosure target:
|
||||
|
||||
ESP32 relay board
|
||||
compact fuse block
|
||||
ground bus
|
||||
CAT6 keystone
|
||||
wiring exits
|
||||
|
||||
Because the Starlink Mini and typical 12V fridge are modest loads, the onboard relays may be acceptable for the initial build if properly fused.
|
||||
|
||||
Suggested fuse allocation:
|
||||
|
||||
ESP32 controller 2A
|
||||
Pico dashboard 1A or 2A
|
||||
Starlink Mini 7.5A
|
||||
Fridge 10A
|
||||
Spare optional
|
||||
Spare optional
|
||||
|
||||
External automotive relays remain a good upgrade path for higher-current loads.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Current Relay Switching Decision
|
||||
|
||||
For the current Starlink Mini and fridge use case, the built-in ESP32 relay board relays are the planned switching method.
|
||||
|
||||
Use positive-side switching:
|
||||
|
||||
Battery +
|
||||
|
|
||||
Fuse
|
||||
|
|
||||
Relay COM
|
||||
|
|
||||
Relay NO
|
||||
|
|
||||
Load +
|
||||
|
||||
Load -
|
||||
|
|
||||
Ground bus
|
||||
|
||||
External automotive relays are reserved for future higher-current loads.
|
||||
|
||||
## DS18B20 Final Install Direction
|
||||
|
||||
Temporary Wago wiring proved one probe, but final install should use a proper terminal/distribution board.
|
||||
|
||||
Recommended:
|
||||
|
||||
3.3V bus
|
||||
DATA bus
|
||||
GND bus
|
||||
|
||||
With:
|
||||
|
||||
4.7k resistor between DATA and 3.3V
|
||||
|
||||
Only three wires need to return to the ESP32:
|
||||
|
||||
3.3V
|
||||
GPIO4
|
||||
GND
|
||||
|
||||
---
|
||||
|
||||
## Pico Dashboard Wiring
|
||||
|
||||
The Pico dashboard should be powered from a local 12V-to-5V buck converter in the dash enclosure.
|
||||
|
||||
Rear enclosure sends fused 12V over CAT5e.
|
||||
|
||||
Dash side:
|
||||
|
||||
CAT5e +12V -> buck IN+
|
||||
CAT5e GND -> buck IN-
|
||||
|
||||
buck OUT+ 5V -> Pico VSYS
|
||||
buck OUT+ 5V -> Display VCC
|
||||
|
||||
buck OUT- GND -> Pico GND
|
||||
buck OUT- GND -> Display GND
|
||||
|
||||
Display wiring:
|
||||
|
||||
SCLK -> Pico GPIO18
|
||||
MOSI -> Pico GPIO19
|
||||
LCD_CS -> Pico GPIO17
|
||||
LCD_DC -> Pico GPIO16
|
||||
LCD_RST -> Pico GPIO20
|
||||
LCD_BL -> Pico GPIO21
|
||||
|
||||
Touch wiring, reserved for future:
|
||||
|
||||
TP_SDA -> Pico GPIO26
|
||||
TP_SCL -> Pico GPIO27
|
||||
TP_INT -> Pico GPIO28
|
||||
TP_RST -> Pico GPIO15
|
||||
|
||||
UART wiring:
|
||||
|
||||
ESP32 GPIO21 TX -> Pico GPIO0 RX
|
||||
ESP32 GPIO22 RX -> Pico GPIO1 TX
|
||||
ESP32 GND -> Pico GND
|
||||
|
||||
Do not use the ESP32 6-pin UART header for the dashboard UART. It appears to be connected to RXD/TXD for UART0/programming/debug.
|
||||
|
||||
|
||||
|
||||
## Dashboard Wiring (Current Direction)
|
||||
|
||||
Dashboard Hardware:
|
||||
- Waveshare 5" ESP32-S3 Display
|
||||
|
||||
Communications:
|
||||
- WiFi connection to cargo ESP32 AP
|
||||
- HTTP API polling
|
||||
- No UART required for normal operation
|
||||
|
||||
CAT5e Usage:
|
||||
- 12V power from cargo area to dashboard
|
||||
- Local buck converter in dashboard enclosure
|
||||
- Common ground
|
||||
|
||||
Optional Future:
|
||||
- UART over CAT5e for diagnostics or alternate dashboard hardware
|
||||
Reference in New Issue
Block a user