nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
overland-controller/docs/HARDWARE.md
T

7.2 KiB
Raw Permalink Blame History

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.

XIAO sensor-node RS485 link

The dashboard uses the Waveshare ESP32-S3-Touch-LCD-5B onboard RS485 receiver for the XIAO BNO086/MAX-M10S node:

Function Dashboard GPIO
RS485 RX GPIO43
RS485 TX GPIO44

The onboard transceiver handles direction automatically. Configure 115200 baud, 8-N-1, connect A-to-A, B-to-B, and share ground. Keep USB CDC On Boot enabled so USB diagnostics do not claim the RS485 UART pins.

LilyGO T-Relay-S3 6-relay cargo controller

The cargo ESP now targets the LilyGO T-Relay-S3 6-relay board.

Relay control is handled through the onboard 74HC595 shift register, not direct ESP32 GPIO relay outputs.

Function GPIO
74HC595 DATA GPIO7
74HC595 CLOCK GPIO5
74HC595 LATCH GPIO6
74HC595 nOE GPIO4
Firmware ID LilyGO relay channel Shift-register output
relay_1 CH1 SR1
relay_2 CH2 SR2
relay_3 CH3 SR3
relay_4 CH4 SR4
relay_5 CH5 SR5
relay_6 CH6 SR6

GPIO4 is reserved for relay output-enable on this board, so the DS18B20 OneWire bus is moved to GPIO14.

Avoid GPIO35-GPIO37 on the LilyGO T-Relay-S3 because they are used by Octal SPI flash.

Reference in New Issue View Git Blame Copy Permalink