diff --git a/README.md b/README.md index b10f658..2f3ebac 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,91 @@ # arduino_gauge_controller -A dedicated gauge controller for Arduinos. \ No newline at end of file +A dedicated gauge controller for Arduinos. + +## Overview + +This repository contains: + +- `Gaugecontroller/Gaugecontroller.ino`: the Arduino Mega firmware for the stepper gauges, LEDs, and integrated HV5812-based VFD +- `gauge.py`: the ESP32 / MicroPython MQTT bridge that exposes the controller to Home Assistant + +## VFD Support + +The integrated gauge controller now includes a 4-digit VFD with: + +- 4 alphanumeric digits +- decimal point indicator +- alarm bell indicator + +On the merged Arduino firmware, the HV5812 control pins are: + +- `D46` -> `DATA` +- `D47` -> `CLOCK` +- `D48` -> `STROBE` +- `D49` -> `BLANK/OE` + +The standalone VFD sketch used `D51/D52/D53/D49`, but `51/52/53` conflict with the gauge stepper pins in the integrated controller. + +## Arduino Serial Commands + +The merged Arduino firmware accepts: + +- `VFD` + clears the display and turns off decimal point and alarm bell +- `VFD 1234` +- `VFD 0123` +- `VFD DEAD` +- `VFD 8888.` +- `VFD BEEF!` +- `VFD 12AF.!` + +Rules: + +- up to 4 characters are displayed +- valid characters are `0-9`, `A-F`, and `-` +- `.` enables the decimal point +- `!` enables the alarm bell +- shorter values are right-aligned +- leading zeroes are preserved if they are part of the input + +## Home Assistant Entities + +The MQTT bridge publishes Home Assistant discovery entities for the VFD: + +- `VFD Display` + text entity for the displayed value +- `VFD Decimal Point` + switch entity +- `VFD Alarm` + switch entity + +The display is intentionally exposed as a text entity rather than a numeric entity so that: + +- leading zeroes are preserved +- hexadecimal values like `DEAD` or `BEEF` work +- clearing the display is possible with an empty value + +## MQTT Topics + +Using the configured `mqtt_prefix` from `config.json`, the VFD topics are: + +- `/vfd/set` +- `/vfd/state` +- `/vfd/decimal_point/set` +- `/vfd/decimal_point/state` +- `/vfd/alarm/set` +- `/vfd/alarm/state` + +Example with the default prefix `gauges`: + +- `gauges/vfd/set` +- `gauges/vfd/decimal_point/set` +- `gauges/vfd/alarm/set` + +Example payloads: + +- publish `0123` to `gauges/vfd/set` +- publish `ON` to `gauges/vfd/decimal_point/set` +- publish `OFF` to `gauges/vfd/alarm/set` + +The MQTT bridge then converts that into the correct Arduino serial command such as `VFD 0123.`. diff --git a/Rewire_checklist.md b/Rewire_checklist.md new file mode 100644 index 0000000..1ef39fd --- /dev/null +++ b/Rewire_checklist.md @@ -0,0 +1,322 @@ +# Rewire Checklist + +This is a practical rebuild checklist for the current integrated setup: + +- `Arduino Mega 2560` +- `ESP32` running `gauge.py` +- `HV5812P` +- 4-digit VFD with decimal point and alarm bell +- 3 gauge drivers +- WS2812B LED chain + +Use this to rebuild the bench wiring from scratch. + +## 1. Power Off Everything + +- disconnect all power supplies +- disconnect USB power if it is currently feeding any board +- do not move wires while the VFD high-voltage supply is live + +## 2. Place The Main Parts + +- place the `Arduino Mega 2560` +- place the `ESP32` +- place the `HV5812P` +- place the 3 gauge driver boards +- place the WS2812B strip connection point +- place the VFD tube connection point + +## 3. Establish A Common Ground First + +Before anything else, create one common logic ground network. + +Connect: + +- `Mega GND` -> ground rail +- `ESP32 GND` -> same ground rail +- `HV5812P GND` -> same ground rail +- `Gauge driver 0 logic GND` -> same ground rail +- `Gauge driver 1 logic GND` -> same ground rail +- `Gauge driver 2 logic GND` -> same ground rail +- `WS2812B GND` -> same ground rail + +If your VFD high-voltage supply has a ground/reference return: + +- `VFD HV supply return` -> same common ground rail + +Do not continue until this common ground is in place. + +## 4. Wire The Arduino Mega Power + +Connect: + +- regulated `5V logic supply` -> `Mega 5V` +- ground rail -> `Mega GND` + +Do not use the Mega to power motors. + +## 5. Wire The ESP32 Power + +Power the ESP32 in the way your board expects. + +Typical options: + +- via board USB +- via board `5V/VIN` if your ESP32 board has its own regulator +- via regulated `3.3V` if it is a bare module that requires that + +Also connect: + +- `ESP32 GND` -> common ground rail + +Do not feed raw `5V` into a bare `3.3V-only` ESP32 module. + +## 6. Wire The ESP32 UART To The Mega + +Connect: + +- `ESP32 GPIO17 (TX)` -> `Mega pin 19 (RX1)` +- `ESP32 GPIO16 (RX)` <- `Mega pin 18 (TX1)` +- `ESP32 GND` -> `Mega GND` + +This UART link is used by `gauge.py`. + +## 7. Wire The HV5812P Logic Side + +Connect: + +- `Mega D46` -> `HV5812P DATA IN / DIN` +- `Mega D47` -> `HV5812P CLOCK / CLK` +- `Mega D48` -> `HV5812P STROBE / LATCH` +- `Mega D49` -> `HV5812P BLANKING / OE` +- `Mega 5V` -> `HV5812P VDD` +- `Mega GND` -> `HV5812P GND` + +Do not connect: + +- `Mega 5V` -> `HV5812P VPP` + +## 8. Wire The HV5812P High-Voltage Side + +Connect: + +- `VFD high-voltage positive supply` -> `HV5812P VPP` +- `VFD high-voltage supply return / reference` -> common ground rail + +At this stage: + +- `VDD` must be `5V` +- `VPP` must be your VFD high-voltage rail + +## 9. Wire The HV5812P Outputs To The VFD + +Connect these one by one: + +- `HVOut1` -> VFD segment `A` +- `HVOut2` -> VFD segment `B` +- `HVOut3` -> VFD segment `C` +- `HVOut4` -> VFD segment `D` +- `HVOut5` -> VFD segment `E` +- `HVOut6` -> VFD segment `F` +- `HVOut7` -> VFD segment `G` +- `HVOut8` -> VFD decimal point segment +- `HVOut9` -> VFD alarm bell segment +- `HVOut10` -> VFD digit 1 grid +- `HVOut11` -> VFD digit 2 grid +- `HVOut12` -> VFD digit 3 grid +- `HVOut13` -> VFD digit 4 grid +- `HVOut14` -> VFD indicator grid between digits 2 and 3 + +## 10. Wire The VFD Filament + +Wire the VFD filament/heater exactly as required by your tube. + +This checklist cannot specify the exact filament supply because it depends on the actual tube. + +Required reminder: + +- do not power the filament from an Arduino GPIO +- use the correct filament supply for the tube + +## 11. Wire Gauge Driver 0 + +Connect: + +- `Mega D50` -> `Gauge driver 0 DIR` +- `Mega D51` -> `Gauge driver 0 STEP` +- `Mega GND` -> `Gauge driver 0 logic GND` + +Then connect the motor side of that driver to: + +- its motor power supply +- its gauge motor + +according to the driver board you are using. + +## 12. Wire Gauge Driver 1 + +Connect: + +- `Mega D8` -> `Gauge driver 1 DIR` +- `Mega D9` -> `Gauge driver 1 STEP` +- `Mega GND` -> `Gauge driver 1 logic GND` + +Then connect the motor side of that driver to: + +- its motor power supply +- its gauge motor + +according to the driver board you are using. + +## 13. Wire Gauge Driver 2 + +Connect: + +- `Mega D52` -> `Gauge driver 2 DIR` +- `Mega D53` -> `Gauge driver 2 STEP` +- `Mega GND` -> `Gauge driver 2 logic GND` + +Then connect the motor side of that driver to: + +- its motor power supply +- its gauge motor + +according to the driver board you are using. + +## 14. Wire The WS2812B LEDs + +Connect: + +- `Mega D22` -> `WS2812B DIN` +- `5V LED supply` -> `WS2812B 5V` +- `WS2812B GND` -> common ground rail + +If the LED chain is long or bright: + +- do not power it from the Mega `5V` +- use a proper external `5V` supply + +## 15. Verify The Pins That Changed For The Integrated VFD + +The VFD is no longer on the old standalone pins. + +Old standalone pins: + +- `D51` -> DATA +- `D52` -> CLOCK +- `D53` -> STROBE +- `D49` -> BLANK + +Current integrated pins: + +- `D46` -> DATA +- `D47` -> CLOCK +- `D48` -> STROBE +- `D49` -> BLANK + +So make sure: + +- nothing VFD-related is still on `D51` +- nothing VFD-related is still on `D52` +- nothing VFD-related is still on `D53` +- only `BLANK/OE` remains on `D49` + +## 16. Sanity Check Before Powering Logic + +Check each item physically: + +- `Mega D46` really goes to `HV5812 DATA` +- `Mega D47` really goes to `HV5812 CLOCK` +- `Mega D48` really goes to `HV5812 STROBE` +- `Mega D49` really goes to `HV5812 BLANKING` +- `Mega D50/D51` only go to gauge driver 0 +- `Mega D8/D9` only go to gauge driver 1 +- `Mega D52/D53` only go to gauge driver 2 +- `Mega D22` only goes to WS2812B `DIN` +- `ESP32 GPIO17` goes to `Mega RX1` +- `ESP32 GPIO16` goes to `Mega TX1` +- all grounds are common +- `HV5812 VDD` is `5V` +- `HV5812 VPP` is high voltage, not `5V` + +## 17. Power Logic Only First + +Apply only logic power first: + +- Mega power +- ESP32 power +- HV5812 `VDD` +- WS2812 `5V` + +Leave motor supply and VFD high voltage off for the first check if possible. + +Verify: + +- Mega boots +- ESP32 boots +- UART communication works + +## 18. Power The VFD High Voltage + +Now apply the VFD high-voltage supply to `HV5812 VPP`. + +Verify: + +- `VDD` remains `5V` +- `VPP` is the expected high voltage +- no logic wire is heating + +## 19. Power The Gauge Drivers + +Now apply motor power to the gauge drivers. + +Verify: + +- no driver fault LEDs +- no motor heating or runaway movement immediately on power-up + +## 20. First Functional Test + +Test in this order: + +1. confirm the ESP32 can talk to the Mega +2. send `VFD 8888` +3. send `VFD DEAD.!` +4. test one gauge movement from Home Assistant or MQTT +5. test one LED output + +## 21. If Something Is Wrong + +Use this triage order: + +1. check grounds +2. check `VDD` and `VPP` +3. check Mega pin number mistakes +4. check crossed UART lines +5. check that the VFD is still on `46/47/48/49`, not `51/52/53/49` + +## 22. Quick Reference + +### Mega pins in use + +- `D8` -> gauge 1 DIR +- `D9` -> gauge 1 STEP +- `D22` -> WS2812 DIN +- `D46` -> HV5812 DATA +- `D47` -> HV5812 CLOCK +- `D48` -> HV5812 STROBE +- `D49` -> HV5812 BLANKING +- `D50` -> gauge 0 DIR +- `D51` -> gauge 0 STEP +- `D52` -> gauge 2 DIR +- `D53` -> gauge 2 STEP +- `D18` -> UART TX1 to ESP32 RX +- `D19` -> UART RX1 from ESP32 TX + +### VFD outputs + +- `HVOut1..7` -> `A..G` +- `HVOut8` -> decimal point +- `HVOut9` -> alarm bell +- `HVOut10..13` -> digit grids 1..4 +- `HVOut14` -> indicator grid diff --git a/Stripboard_layout.md b/Stripboard_layout.md new file mode 100644 index 0000000..2349647 --- /dev/null +++ b/Stripboard_layout.md @@ -0,0 +1,413 @@ +# Stripboard Layout Suggestion + +This is a practical suggested layout for moving the current bench wiring onto stripboard. It is not a PCB netlist. It is a placement and routing plan intended to reduce wiring chaos while keeping the high-voltage VFD side separated from the low-voltage logic side. + +Use this together with: + +- [wiring.md](/home/adebaumann/development/arduino_gauge_controller/wiring.md:1) +- [Rewire_checklist.md](/home/adebaumann/development/arduino_gauge_controller/Rewire_checklist.md:1) + +## Design Goals + +- keep `5V logic` on one side +- keep `VFD high voltage` on the opposite side +- keep the `HV5812P` between those two domains +- bring all off-board wiring to clearly labeled edge connectors +- avoid crossing the gauge step/dir wiring through the VFD area +- make debugging possible with scope probes and a meter + +## Recommended Board Strategy + +Use one main stripboard for: + +- Arduino Mega interface headers +- HV5812P and its support wiring +- connectors for the VFD tube +- connectors for the three gauge drivers +- connector for the WS2812 strip +- connector for the ESP32 UART link + +Do not mount the Arduino Mega itself onto stripboard. Use pin headers or screw terminals so the Mega remains removable. + +If possible, also do not mount the ESP32 directly unless you already have a reliable carrier board for it. + +## Suggested Physical Zoning + +Arrange the board in four zones from left to right: + +1. `Mega / ESP32 low-voltage I/O zone` +2. `Gauge / LED connector zone` +3. `HV5812P driver zone` +4. `VFD high-voltage and tube connector zone` + +That gives you a left-to-right flow like this: + +```text +[ Mega / ESP32 ] [ Gauge + LED connectors ] [ HV5812P ] [ VFD + HV connectors ] +``` + +This is better than putting the HV5812 at the edge near the Mega, because the HV5812 is the boundary device between logic and high voltage. + +## Board Orientation + +Assume the stripboard copper tracks run horizontally. + +Recommended use: + +- horizontal tracks for local distribution +- vertical jumps made with insulated wire links + +Cut tracks aggressively around the HV5812P so it does not accidentally join unrelated nets through the copper strips. + +## Left Side: Mega / ESP32 Interface + +Place a row of labeled pin headers or screw terminals for the signals coming from the Mega: + +- `5V` +- `GND` +- `D22` +- `D46` +- `D47` +- `D48` +- `D49` +- `D50` +- `D51` +- `D52` +- `D53` +- `RX1` +- `TX1` + +Place a second small header for the ESP32: + +- `ESP32 TX` +- `ESP32 RX` +- `ESP32 GND` + +Keep these headers near one board edge so you can unplug and rework them easily. + +## Middle-Left: Gauge / LED Connectors + +Place four connector groups near the Mega interface side: + +1. `Gauge 0` + - `DIR` + - `STEP` + - `GND` +2. `Gauge 1` + - `DIR` + - `STEP` + - `GND` +3. `Gauge 2` + - `DIR` + - `STEP` + - `GND` +4. `WS2812` + - `DIN` + - `5V` + - `GND` + +This keeps all low-voltage off-board connections together. + +## Center: HV5812P Zone + +Mount the `HV5812P` roughly in the center-right of the board. + +Reason: + +- logic-side control pins can approach from the left +- high-voltage outputs can leave to the right toward the VFD connector + +Around the HV5812P: + +- isolate each used pin with track cuts as needed +- keep short local links for `DATA`, `CLOCK`, `STROBE`, `BLANKING` +- keep `VDD` decoupling physically close to the chip + +Recommended support parts close to the HV5812P: + +- `100 nF` ceramic decoupling capacitor between `VDD` and `GND` +- one larger bulk capacitor on the `5V` rail nearby, for example `10 uF` to `47 uF` + +If you already use any datasheet-recommended support parts for the HV side, place them in this same zone. + +## Right Side: VFD Connector Zone + +Put the VFD connectors on the far right side of the board, physically separated from the Mega headers. + +Provide terminals or headers for: + +- `HVOut1` -> `A` +- `HVOut2` -> `B` +- `HVOut3` -> `C` +- `HVOut4` -> `D` +- `HVOut5` -> `E` +- `HVOut6` -> `F` +- `HVOut7` -> `G` +- `HVOut8` -> `DP` +- `HVOut9` -> `BELL` +- `HVOut10` -> `GRID1` +- `HVOut11` -> `GRID2` +- `HVOut12` -> `GRID3` +- `HVOut13` -> `GRID4` +- `HVOut14` -> `GRID_IND` + +Also provide separate terminals for: + +- `VPP` +- `GND` +- filament connections + +Keep the filament connections away from the logic-side headers. + +## Suggested Power Buses + +Use distinct buses and label them clearly: + +- `5V LOGIC` +- `GND` +- `VPP` + +Recommended physical arrangement: + +- `5V` bus along the top-left area only +- `GND` bus available across the board +- `VPP` bus only on the far-right HV area + +Do not run a long exposed `VPP` strip through the entire board. Keep the high-voltage distribution short and local to the HV5812 and VFD connector side. + +## Suggested Routing + +### Mega to HV5812 + +Route these as short direct runs: + +- `D46` -> `DATA` +- `D47` -> `CLOCK` +- `D48` -> `STROBE` +- `D49` -> `BLANKING` + +These should pass from the left interface zone into the HV5812 zone without crossing the VPP area. + +### Mega to Gauges + +Route these directly to the gauge connector blocks: + +- `D50` -> gauge 0 `DIR` +- `D51` -> gauge 0 `STEP` +- `D8` and `D9` + If you are bringing these through the stripboard too, add them to the Mega header group and route them directly to gauge 1. +- `D52` -> gauge 2 `DIR` +- `D53` -> gauge 2 `STEP` + +If `D8` and `D9` come from separate fly wires to the stripboard, keep them in the same low-voltage connector area as the rest of the gauge lines. + +### Mega to WS2812 + +Route: + +- `D22` -> `WS2812 DIN` +- `5V` -> `WS2812 5V` +- `GND` -> `WS2812 GND` + +Keep the LED connector in the low-voltage area. + +### ESP32 to Mega + +If the stripboard is acting as the interconnect backplane: + +- `ESP32 TX` -> `Mega RX1` +- `ESP32 RX` -> `Mega TX1` +- `ESP32 GND` -> `GND` + +## Track Cuts and Links + +Recommended stripboard discipline: + +- every IC pin should be visually checked for unintended strip continuity +- cut under or near pins wherever two adjacent pins must not share the strip +- use insulated jumpers for crossings instead of relying on long exposed component leads +- use a continuity meter after every 5-10 wires added + +For the HV5812P specifically: + +- assume most adjacent pins must not be left on the same uninterrupted strip +- cut first, then add intentional links + +## Physical Separation Rules + +Keep these separations: + +- logic and UART wiring away from `VPP` +- VFD output traces away from ESP32 and Mega headers +- gauge step/dir traces away from VFD high-voltage outputs where possible + +If you can, leave at least one empty strip gap between low-voltage and high-voltage routing regions, and more where practical. + +## Labeling + +Label the board directly with marker or printed tape. + +At minimum label: + +- `5V` +- `GND` +- `VPP` +- `DIN` +- `CLK` +- `STR` +- `BLK` +- `G0 DIR` +- `G0 STEP` +- `G1 DIR` +- `G1 STEP` +- `G2 DIR` +- `G2 STEP` +- `LED DIN` +- `RX1` +- `TX1` +- `A B C D E F G DP BELL G1 G2 G3 G4 GI` + +This matters more than aesthetics. A labeled board is much easier to repair later. + +## Practical Build Order + +1. Place and mark the four physical zones. +2. Mount the low-voltage connector headers. +3. Mount the HV5812P. +4. Cut all required strips around the HV5812P before adding wires. +5. Add `GND` and `5V` low-voltage distribution. +6. Add Mega-to-HV5812 logic lines. +7. Add gauge and LED connector routing. +8. Add `VPP` and the VFD output connector routing. +9. Add the VFD filament connector. +10. Verify continuity and shorts before any power is applied. + +## Recommended First Continuity Checks + +Before power: + +- `5V` is not shorted to `GND` +- `VPP` is not shorted to `GND` +- `VPP` is not shorted to `5V` +- `D46/D47/D48/D49` are only connected to the intended HV5812 pins +- `D50/D51/D52/D53/D8/D9` are only connected to the intended gauge connectors +- `D22` only goes to the WS2812 connector +- `RX1/TX1` are not swapped at the stripboard labels + +## Suggested Board Size + +For comfort rather than minimum size, use a board large enough to avoid crowding: + +- roughly `100 x 160 mm` or larger if you want good service access + +Smaller is possible, but with mixed logic, UART, gauge control, LEDs, and VFD high voltage, cramped stripboard becomes harder to debug than a rat's nest. + +## Recommendation + +If you want the cleanest result: + +- use the stripboard only as an interconnect backplane +- keep the Mega, ESP32, and possibly the gauge drivers off-board on removable connectors +- keep the HV5812 and VFD connector area on the stripboard itself + +That gives you most of the neatness benefit without forcing the whole system into one dense board. + +## ASCII Top View + +This is a suggested top-view arrangement, not a strict scale drawing. + +```text +Top edge + ++--------------------------------------------------------------------------------------------------+ +| [Mega Header Block] [Gauge / LED Connectors] [HV5812P Zone] [VFD Zone] | +| | +| 5V GND D22 D46 D47 D48 D49 D50 D51 D52 D53 RX1 TX1 | +| o o o o o o o o o o o o o | +| | +| [ESP32 Header] | +| TX RX GND | +| o o o | +| | +| [Gauge 0] [Gauge 1] [Gauge 2] [WS2812] | +| DIR STEP G DIR STEP G DIR STEP G DIN 5V G | +| o o o o o o o o o o o o | +| | +| +----------------------+ | +| | HV5812P | | +| | | | +| 5V LOGIC BUS ============================================>| VDD | | +| GND BUS ============================================>| GND |==============| +| | DIN CLK STR BLK | | +| | ^ ^ ^ ^ | | +| +--|----|---|---|------+ | +| | | | | | +| | | | +---- D49 | +| | | +-------- D48 | +| | +------------ D47 | +| +----------------- D46 | +| | +| VPP terminal | +| o | +| | | +| HV AREA | | +| kept to right side only | | +| v | +| A B C D E F G DP BELL G1 G2 G3 G4 GI +| o o o o o o o o o o o o o o +| [VFD output connector block] | +| | +| FIL_A FIL_B GND/HVRET | +| o o o | +| [filament / HV return terminals] | +| | ++--------------------------------------------------------------------------------------------------+ + +Bottom edge +``` + +## Reading The Sketch + +- left side: + all low-voltage headers from the Mega and ESP32 +- center-left: + gauge and LED connector blocks +- center-right: + HV5812P +- far right: + VFD outputs, filament, and `VPP` + +This keeps the dangerous and noisy wiring concentrated on one side of the board. + +## Suggested Copper-Strip Use + +If your strips run horizontally: + +- use upper strips for low-voltage headers and distribution +- use middle strips for gauge and LED routing +- isolate the HV5812P pin rows heavily with track cuts +- use lower-right strips only for the VFD output area and `VPP` + +## Suggested Connector Edge Placement + +If you want the board to be easy to service: + +- put Mega and ESP32 headers on the left edge +- put gauge and LED connectors on the bottom edge +- put VFD and high-voltage terminals on the right edge + +That way: + +- low-voltage control cables enter from the left and bottom +- high-voltage VFD wires leave only on the right + +## Minimum Clearance Advice + +On stripboard, do not pack the `VPP` and VFD output terminals tightly against the low-voltage headers. + +Practical suggestion: + +- leave at least several empty holes / one empty strip region between the HV5812 logic-side routing and the `VPP` / VFD connector zone +- if you have room, leave more than that + +More separation is better than a dense layout here. diff --git a/wiring.md b/wiring.md new file mode 100644 index 0000000..3d7a913 --- /dev/null +++ b/wiring.md @@ -0,0 +1,267 @@ +# Wiring + +This document describes the wiring required for the current integrated system: + +- `Arduino Mega 2560` +- `HV5812P` VFD driver +- 4-digit VFD tube with decimal point and alarm bell +- 3 stepper-driven gauges +- WS2812B LEDs +- ESP32 running `gauge.py` as the MQTT / Home Assistant bridge + +It is intentionally based on the code that is in the repository now: + +- [Gaugecontroller.ino](/home/adebaumann/development/arduino_gauge_controller/Gaugecontroller/Gaugecontroller.ino:1) +- [gauge.py](/home/adebaumann/development/arduino_gauge_controller/gauge.py:1) + +## System Power + +You effectively have three power domains: + +1. `5V logic` + for the Arduino Mega logic, the HV5812 logic side, and usually the step/dir logic inputs +2. `high voltage for the VFD` + for `HV5812P VPP` and the VFD segment/grid drive +3. `motor / actuator power` + for the stepper gauges and their driver hardware + +Minimum common rule: + +- all logic grounds must be common + +That means these must share `GND`: + +- Arduino Mega `GND` +- ESP32 `GND` +- HV5812P logic `GND` +- stepper driver logic `GND` +- WS2812B `GND` + +The VFD high-voltage supply still references the same ground, but its high-voltage nodes must never be connected directly to Arduino or ESP32 GPIO pins. + +## Arduino Mega 2560 + +Use the Mega as the central logic controller. + +Power: + +- `Mega 5V` <- regulated `5V` logic supply +- `Mega GND` <- common logic ground + +Serial bridge to ESP32: + +- `Mega RX1` pin `19` <- `ESP32 TX` GPIO `17` +- `Mega TX1` pin `18` -> `ESP32 RX` GPIO `16` +- `Mega GND` <-> `ESP32 GND` + +This matches the current code: + +- Arduino uses `Serial1` in [Gaugecontroller.ino](/home/adebaumann/development/arduino_gauge_controller/Gaugecontroller/Gaugecontroller.ino:12) +- ESP32 uses `UART(1, tx=17, rx=16)` in [gauge.py](/home/adebaumann/development/arduino_gauge_controller/gauge.py:149) + +## VFD Control: Mega -> HV5812P + +These are the integrated pin assignments used by the merged controller: + +| Mega Pin | HV5812P Signal | Purpose | +|---|---|---| +| `D46` | `DATA IN / DIN` | serial data into HV5812P | +| `D47` | `CLOCK / CLK` | shift clock | +| `D48` | `STROBE / LATCH` | latch transfer | +| `D49` | `BLANKING / OE` | output blanking | +| `5V` | `VDD` | HV5812 logic supply | +| `GND` | `GND` | common reference | +| `VFD HV+` | `VPP` | HV5812 high-voltage rail | + +Important: + +- `VDD` is the low-voltage logic rail +- `VPP` is the high-voltage output rail +- do not connect Arduino `5V` to `VPP` + +## HV5812P -> VFD Tube + +The current output map is: + +| HV5812 Output | Tube Function | +|---|---| +| `HVOut1` | segment `A` | +| `HVOut2` | segment `B` | +| `HVOut3` | segment `C` | +| `HVOut4` | segment `D` | +| `HVOut5` | segment `E` | +| `HVOut6` | segment `F` | +| `HVOut7` | segment `G` | +| `HVOut8` | decimal point segment | +| `HVOut9` | alarm bell segment | +| `HVOut10` | digit grid 1 | +| `HVOut11` | digit grid 2 | +| `HVOut12` | digit grid 3 | +| `HVOut13` | digit grid 4 | +| `HVOut14` | indicator grid between digits 2 and 3 | + +Logical segment layout: + +```text + ---A--- +| | +F B +|---G---| +E C +| | + ---D--- +``` + +Additional VFD wiring notes: + +- the VFD filament/heater wiring is separate from the HV5812 outputs +- the exact filament supply depends on your tube +- the HV5812 only drives the segments and grids + +## Gauge Control Pins + +The current sketch drives three gauges. + +Each gauge needs a driver or actuator input that accepts: + +- `DIR` +- `STEP` +- optionally `ENABLE` if you later add one in code + +Current assignments: + +| Gauge | Mega DIR | Mega STEP | +|---|---|---| +| `Gauge 0` | `D50` | `D51` | +| `Gauge 1` | `D8` | `D9` | +| `Gauge 2` | `D52` | `D53` | + +Connect each pair to the matching stepper driver inputs. + +Example: + +- `Mega D50` -> Gauge 0 driver `DIR` +- `Mega D51` -> Gauge 0 driver `STEP` +- `Mega D8` -> Gauge 1 driver `DIR` +- `Mega D9` -> Gauge 1 driver `STEP` +- `Mega D52` -> Gauge 2 driver `DIR` +- `Mega D53` -> Gauge 2 driver `STEP` + +Also connect: + +- `Mega GND` -> each driver logic ground + +If your driver boards need separate motor power, supply that from the proper motor supply. Do not power motors from the Mega `5V` pin. + +## WS2812B LED Strip + +The current sketch expects one shared WS2812B chain. + +| Mega Pin | WS2812B | +|---|---| +| `D22` | `DIN` | +| `5V` | `5V` | +| `GND` | `GND` | + +Notes: + +- the code expects `7 LEDs per gauge`, so `21 LEDs total` +- use a proper 5V supply sized for the LED current +- keep LED ground common with the Mega + +If the strip is powered from a separate 5V supply: + +- connect external `5V` -> LED `5V` +- connect external `GND` -> LED `GND` +- connect that same `GND` to `Mega GND` + +## ESP32 Bridge + +The ESP32 runs `gauge.py` and talks to the Mega over UART and to Home Assistant over MQTT/Wi-Fi. + +ESP32 to Mega: + +| ESP32 Pin | Mega Pin | Purpose | +|---|---|---| +| `GPIO17` | `RX1` pin `19` | ESP32 TX -> Mega RX | +| `GPIO16` | `TX1` pin `18` | ESP32 RX <- Mega TX | +| `GND` | `GND` | common ground | + +ESP32 power: + +- power the ESP32 from a proper `3.3V` or board-supported USB/5V input, depending on your board +- do not feed raw `5V` into a bare `3.3V` ESP32 module unless the board has its own regulator + +## One-Page Wiring Summary + +### Power + +- `5V logic supply` -> Mega `5V` +- `5V logic supply` -> HV5812 `VDD` +- `5V logic supply` -> WS2812B `5V` +- `motor supply` -> gauge driver motor power inputs +- `VFD high-voltage supply` -> HV5812 `VPP` +- all grounds common + +### Mega to ESP32 + +- `Mega 19 (RX1)` <- `ESP32 GPIO17 (TX)` +- `Mega 18 (TX1)` -> `ESP32 GPIO16 (RX)` +- `Mega GND` <-> `ESP32 GND` + +### Mega to HV5812 + +- `D46` -> `DIN` +- `D47` -> `CLK` +- `D48` -> `STROBE` +- `D49` -> `BLANKING` +- `5V` -> `VDD` +- `GND` -> `GND` +- `VFD HV+` -> `VPP` + +### HV5812 to Tube + +- `HVOut1..7` -> segments `A..G` +- `HVOut8` -> decimal point +- `HVOut9` -> alarm bell +- `HVOut10..13` -> digit grids `1..4` +- `HVOut14` -> indicator grid + +### Mega to Gauges + +- `D50/D51` -> gauge 0 `DIR/STEP` +- `D8/D9` -> gauge 1 `DIR/STEP` +- `D52/D53` -> gauge 2 `DIR/STEP` + +### Mega to LEDs + +- `D22` -> WS2812B `DIN` +- `5V` -> WS2812B `5V` +- `GND` -> WS2812B `GND` + +## Sanity Checklist Before Power-On + +- Mega, ESP32, HV5812 logic, LED strip, and driver logic grounds are all common +- Mega `D46-D49` go to the HV5812, not to the gauge drivers +- Mega `D50-D53` and `D8-D9` go only to the gauge drivers +- HV5812 `VDD` is `5V` +- HV5812 `VPP` is the VFD high-voltage rail, not `5V` +- ESP32 UART is crossed correctly: TX -> RX, RX -> TX +- WS2812B has its own adequate 5V supply if current draw is significant +- motor power is not coming from the Mega + +## What This Does Not Define + +This document does not define: + +- the exact VFD filament supply voltage/current +- the exact motor driver board power pins, because that depends on the driver hardware you are using +- the physical PDIP package pin numbers of the HV5812P + +If you want, the next useful step is a second document with a literal bench-build checklist: + +- `wire 1 from Mega D46 to HV5812 pin ...` +- `wire 2 from Mega D47 to HV5812 pin ...` +- `wire 3 from ESP32 GPIO17 to Mega pin 19` + +That would be the most practical format for cleaning up the desk wiring.