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