overland-controller/docs/HARDWARE.md

Hardware

Cargo ESP32

The cargo ESP32 is the controller and source of truth.

Responsibilities:

• BMS BLE
• Relays
• DS18B20 temps
• WebUI
• HTTP API
• AP mode
• Alarms

Relay board outputs are trigger/control outputs only.

High-current loads must use properly fused automotive relays or contactors.

Do not directly route fridge, Starlink, inverter, lights, or other major loads through the ESP32 relay board.

Dashboard

Target:

Waveshare ESP32-S3-Touch-LCD-5

Reasons:

• ESP32-S3 is mature enough for LVGL dashboard
• 5 inch 800x480 display gives enough UI space
• WiFi connects to Cargo ESP32 AP
• CAN interface with onboard TJA1051 supports future OBD-II vehicle data
• microSD allows future logging
• 7-36V VIN supports vehicle power

Dashboard Power

Preferred:

ACC switched 12V
  -> fuse
  -> Waveshare VIN

Do not use OBD-II pin 16 for permanent dashboard power.

CAN / OBD-II

OBD-II pins:

Pin 6  = CAN-H
Pin 14 = CAN-L
Pin 5  = Signal Ground, optional if needed
Pin 16 = Battery 12V, do not use for permanent display power

Waveshare CAN termination must remain disabled on vehicle CAN.

Preferred CAN wiring:

OBD pin 6  -> Waveshare CAN-H
OBD pin 14 -> Waveshare CAN-L

Optional:

OBD pin 5 -> board/system ground

Use twisted pair. Cat5e/Cat6 twisted pair is acceptable for short vehicle runs.

Avoid Scotchlok/vampire taps on vehicle CAN. Prefer OBD splitter or proper automotive splice.

Vehicle Data

Coolant temp:

Standard OBD-II PID 0105

RPM:

Standard OBD-II PID 010C

Vehicle speed:

Standard OBD-II PID 010D

Transmission Temperature Sender

Preferred over Nissan-specific trans-temp CAN reverse engineering.

Candidate:

Autometer 2258 / 2259 style sender

Resistance table:

100F = 1123 ohms
120F = 708 ohms
140F = 460 ohms
150F = 374 ohms
170F = 253 ohms
190F = 175 ohms
210F = 123 ohms
230F = 89 ohms
250F = 65 ohms
280F = 42 ohms
300F = 32 ohms
320F = 25 ohms
340F = 20 ohms

Implementation:

• Sender to ADC voltage divider, or
• Sender to ADS1115 over I2C if no suitable exposed ADC exists

Use lookup-table interpolation.

Cargo OLED service display

Planned optional hardware:

• 0.96 inch SSD1306 OLED
• 128x64 resolution
• I2C interface
• Typical address: 0x3C
• Suggested initial pins:
  • SDA: GPIO 21
  • SCL: GPIO 22
  • VCC: 3.3V
  • GND: common ground

Purpose:

• Show first-boot AP setup credentials without requiring Serial Monitor.
• Show AP SSID, password, and IP address during setup/recovery.
• Show quick service status:
  • battery SOC
  • voltage/current
  • relay states
  • WiFi/IP
  • active alarms

Firmware support is optional and disabled by default with OLED_ENABLED set to 0. Enable only after the OLED libraries are installed and the display is wired.

Current communications and GPIO decision

Active dashboard communication is WiFi/HTTP using /api/v1.

The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.

Current Cargo ESP32 GPIO plan:

• GPIO 16: Relay 1 trigger output
• GPIO 17: Relay 2 trigger output
• GPIO 4: DS18B20 OneWire temperature bus
• GPIO 34: Ignition sense input
• GPIO 21: SSD1306 OLED I2C SDA
• GPIO 22: SSD1306 OLED I2C SCL
• GPIO 25: OLED setup/status button

Automotive Load-Switching Layer

Current v1 load-control assumption:

Cargo ESP32
    -> control outputs
    -> automotive load-switching layer
    -> fused loads

Expected fused loads:

• Fridge
• Starlink
• Lights
• Spare output

The ESP32 relay board is treated as a trigger/control layer only. Major load current must be handled by properly fused automotive wiring, relays, contactors, smart high-side switches, or another suitable fused distribution module.

The exact load-switching hardware is not finalized yet.

Candidate options:

• Bosch-style automotive relays
• WUPP-style fused relay/distribution module
• Smart high-side switching
• Future custom PCB

Selected Dashboard Hardware

The selected dashboard hardware target is the Waveshare ESP32-S3 Touch LCD 5B.

Key hardware notes:

• 5-inch touchscreen display
• 1024x600 resolution
• ESP32-S3 based
• Capacitive touch
• Native WiFi
• Integrated CAN transceiver available for future vehicle integration

This is the active dashboard platform for the project. The previous Pico dashboard implementation has been archived and is reference-only.

DS18B20 Temperature Sensors

DS18B20 temperature sensors are already part of the Cargo ESP implementation and WebUI/API flow.

Current expectation:

• DS18B20 sensors connect to the Cargo ESP side.
• Cargo ESP owns sensor reads and temperature state.
• The WebUI displays the temperature data.
• The Dashboard ESP32-S3 will consume temperature data from the Cargo ESP API.

Do not move cargo/fridge temperature sensing to the dashboard controller unless the architecture is explicitly changed later.

Ordered Cargo ESP Hardware: LILYGO T-Relay-S3 6-Way

The LILYGO T-Relay-S3 6-way board has been ordered as a future Cargo ESP candidate.

Current active testing should continue on the existing 2-channel relay board until the LilyGO board arrives and is bench tested.

Planned LilyGO role:

LILYGO T-Relay-S3 6-way
        -> low-current control/relay outputs
WUPP 6-relay fused block
        -> fused load switching
Fridge / Starlink / lights / spare / spare / spare

Important guardrails:

• Do not migrate active firmware assumptions until the board is physically available.
• Bench test relay boot behavior before connecting to WUPP or vehicle loads.
• Confirm relay polarity/state behavior.
• Confirm available GPIO for DS18B20 and any optional OLED/status hardware.
• Treat the LilyGO board as the controller, not the high-current load path.

M9N GPS Module

The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.