# 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.