Transformer Viewer U1.4 Modular ================================= Purpose ------- Transformer Viewer measures voltage and current on up to four transformer channels using INA226 sensors and publishes the measurements through MQTT. The project includes a multilingual Project UNION web interface for status, configuration, WiFi, MQTT, mDNS and OTA firmware updates. Important --------- The source code has not been modified. This documentation was created from the supplied TransformerViewer_Library_U1_4_Modular project. Target hardware --------------- - ESP32 development board - 4 MB flash is recommended - Four INA226 current/voltage sensor modules - I2C connection on GPIO21 (SDA) and GPIO22 (SCL) - WiFi network for web configuration and MQTT - MQTT broker if MQTT publishing is required Required Arduino libraries -------------------------- - ProjectUNION Core 0.3.1 - ProjectUNION MQTT 0.3.1 - PubSubClient - INA226 The project must not require: - ProjectUNION DCC - NmraDcc Project files ------------- Keep these files in the same Arduino sketch folder: - TransformerViewer_Library_U1_4_Modular.ino - project_icon.h Recommended Arduino IDE settings -------------------------------- Board: ESP32 Dev Module, or the exact compatible ESP32 board being used Flash size: 4 MB, unless the actual board uses another size Upload speed: Use the normal upload speed supported reliably by the board Serial monitor: 115200 baud Before compiling ---------------- 1. Install the ESP32 board package in Arduino IDE. 2. Install ProjectUNION Core 0.3.1. 3. Install ProjectUNION MQTT 0.3.1. 4. Install PubSubClient. 5. Install the INA226 library expected by the project. 6. Confirm that the sketch folder name matches the main .ino filename. 7. Confirm that project_icon.h is present beside the .ino file. Hardware connections -------------------- ESP32 I2C: - GPIO21 -> SDA on all INA226 modules - GPIO22 -> SCL on all INA226 modules - GND -> GND on all INA226 modules - Supply voltage -> according to the exact INA226 module specification INA226 addresses: - Channel 1: 0x40 - Channel 2: 0x41 - Channel 3: 0x44 - Channel 4: 0x45 All four modules share the same SDA and SCL bus. Their address jumpers must be configured so that each module has the address assigned above. Measurement assumptions in this version --------------------------------------- - Number of sensors: 4 - Shunt resistance used by the software: 0.018 ohm - Maximum configured current: 2.0 A - Default publish interval: 1000 ms - Minimum accepted publish interval: 500 ms The physical shunt resistor and INA226 module must match the assumptions in the source code. Verify this carefully before powering the measurement circuit. First startup ------------- 1. Assemble and verify the hardware. 2. Upload the sketch through Arduino IDE. 3. Open the Serial Monitor at 115200 baud. 4. Connect to the Project UNION setup access point if WiFi has not previously been configured. 5. Configure WiFi and hostname through the web interface. 6. Configure MQTT broker settings. 7. Configure transformer descriptions, locations, channel activation and transformer number offset. 8. Verify that all expected INA226 channels report correctly. Legacy configuration migration ------------------------------ This project contains a one-time migration from the older TransformerViewer v1.5 Preferences configuration. Old namespace/key: ina226 / config New namespace: project-union The migration can preserve: - WiFi SSID and password - Hostname - Language - MQTT broker, port, username, password and TLS setting - Device name - Base topic - Transformer number offset - Measurement interval - Active channel settings - Transformer descriptions and locations The old configuration is not deleted, so returning to the previous firmware remains possible. MQTT ---- Default base topic: WDP/Custom/Transformer The exact generated topics depend on the transformer offset and the project implementation. Confirm them with the web configuration and MQTT broker after the first upload. Recommended validation ---------------------- - Test one Transformer Viewer unit before updating additional units. - Verify all four I2C addresses. - Compare voltage and current readings with a trusted meter. - Verify the configured 0.018-ohm shunt value against the hardware. - Test MQTT publishing. - Test saved configuration after restart. - Test OTA firmware update. - Test both TransformerViewer A and B configurations if both are used. Known documentation observations -------------------------------- The supplied README file starts with the heading "TransformerViewer Library U1.2", although the project code and change history identify the supplied version as U1.4 Modular. This appears to be an outdated heading only; no source code has been changed. Safety and responsibility ------------------------- Disconnect power before changing wiring. Transformer and model railway power systems may supply substantial current. Use correctly rated wiring, fuses, shunts, terminals and modules. All use is at the builder's own responsibility.