Tau.Acuvim/docs/device-commissioning.md

Device Commissioning Guide

Step-by-step instructions for field installation and commissioning of an ESP32 TTGO T-Call v1.4 monitoring node connected to an Acuvim II power meter.

---

1. Pre-Installation Checklist

Confirm you have the following items before travelling to the site:

Item	Notes
ESP32 TTGO T-Call v1.4 board	Pre-flashed with production firmware
RS485 transceiver module	MAX485 or SP3485 (may be pre-wired)
Acuvim II RS485 cable	3-wire: A, B, GND (shielded recommended)
Micro SIM card	Active data plan, APN details known (if GSM required)
MicroSD card	FAT32 formatted, 4-32 GB (if offline buffering required)
GSM antenna	SMA or u.FL depending on board variant
USB-C cable + power adapter	5V 1A minimum, or dedicated 5V supply
Enclosure	IP-rated if installed outdoors or in panel
Laptop or phone	For captive portal configuration
Multimeter	For verifying RS485 wiring
Small screwdriver	For Acuvim II RS485 terminal block
Cable ties / DIN rail clips	For mounting

Ensure the MQTT broker credentials for this device have been created on the server before proceeding (see deployment-guide.md, Section 6.2).

---

2. Physical Installation

2.1 Mount the ESP32 Board

Mount the TTGO T-Call v1.4 board inside an enclosure near the Acuvim II meter. Keep the following in mind:

• Maintain at least 50mm clearance around the board for airflow.
• Ensure the USB-C port is accessible for emergency serial access.
• Orient the board so the GSM antenna connector faces outward.
• If using DIN rail mounting, use a 3D-printed bracket or adhesive DIN clip.

2.2 Insert the SIM Card

1. Power off the board (disconnect USB).
2. Locate the nano SIM card slot on the underside of the TTGO T-Call v1.4 board.
3. Insert the SIM card with the contacts facing down and the notched corner oriented according to the slot marking.
4. Push gently until the card clicks into place.
5. Note: The SIM800L modem on the T-Call v1.4 uses a nano SIM (some earlier variants use micro SIM -- verify your board revision).

2.3 Insert the SD Card (Optional)

If an external SD card module is connected (see hardware-wiring.md):

1. Insert a FAT32-formatted microSD card into the SD module.
2. Cards larger than 32 GB must be formatted as FAT32 manually (not exFAT).
3. The firmware will create a /telemetry/ directory on first use.

If the TTGO T-Call v1.4 has no built-in SD slot, an external SPI module is required. See hardware-wiring.md for connection details.

2.4 Connect the GSM Antenna

1. Screw the external GSM antenna onto the SMA connector on the board edge.
2. Alternatively, connect a u.FL-to-SMA pigtail if your board variant uses a u.FL connector.
3. Position the antenna vertically for best signal reception.
4. Do not power on the GSM modem without an antenna connected, as this can damage the RF output stage.

2.5 Wire RS485 to the Acuvim II

Connect the RS485 transceiver module to the Acuvim II meter's RS485 terminal block:

RS485 Module Pin	Acuvim II Terminal	Wire Colour (suggested)
A (Data+)	A (Terminal 19)	White
B (Data-)	B (Terminal 20)	Blue
GND	GND (Terminal 18)	Green/Yellow

Wiring procedure:

1. Power off the Acuvim II before touching the terminal block.
2. Loosen the RS485 terminal screws on the Acuvim II (typically terminals 18, 19, 20 on the rear).
3. Strip 5-7mm of insulation from each wire end.
4. Insert the wires and tighten the terminal screws firmly.
5. Use a multimeter to verify there are no shorts between A, B, and GND.
6. Route the cable away from high-voltage conductors. Use shielded cable for runs longer than 2 metres.
7. If the cable run exceeds 10 metres, add a 120-ohm termination resistor between A and B at the Acuvim II end.

Verify the Acuvim II RS485 settings (accessible via the meter front panel):

Parameter	Expected Value
Baud rate	9600
Data bits	8
Parity	None
Stop bits	1
Slave address	1 (or as planned for multi-meter installations)

2.6 Connect Power

1. Connect a USB-C cable to the TTGO T-Call board.
2. Connect the other end to a 5V USB power adapter (minimum 1A, 2A recommended when GSM is active).
3. Alternatively, supply 5V directly to the board's VIN and GND pins if USB is impractical.
4. Verify the red power LED illuminates on the board.

---

3. Initial Configuration via Captive Portal

3.1 Enter AP Mode

On first boot (or after a factory reset), the device starts in Access Point mode:

• SSID: Acuvim-XXXXXX (where XXXXXX is the last 6 characters of the MAC address)
• Password: acuvim123 (default)
• IP Address: 192.168.4.1

The device LED will blink slowly (1 Hz) to indicate AP mode.

If the device has been previously configured and is connected to WiFi, it runs in STA+AP concurrent mode. The AP remains active for 5 minutes after last client activity.

3.2 Connect to the AP

1. On your phone or laptop, open WiFi settings.
2. Connect to the network named Acuvim-XXXXXX.
3. Enter password acuvim123.
4. A captive portal page should appear automatically.
5. If the captive portal does not appear, open a browser and navigate to http://192.168.4.1.

3.3 Configure WiFi

On the captive portal main page:

1. Navigate to Settings > WiFi.
2. Tap Scan Networks to see available SSIDs.
3. Select the target WiFi network.
4. Enter the WiFi password.
5. Tap Save & Connect.
6. The device will attempt to connect. The status indicator on the portal will show:
   • "Connecting..." (attempting)
   • "Connected" with IP address (success)
   • "Failed" with error (wrong password, out of range, etc.)

If WiFi is not available at this site and the device will operate on GSM only, skip this step.

3.4 Configure MQTT Broker

1. Navigate to Settings > MQTT.
2. Enter the following values:

Field	Value
Broker	console.example.com (your server hostname)
Port	8883 (TLS) or 1883 (non-TLS)
Username	The device ID (e.g., ACV-AABBCCDDEEFF)
Password	The per-device MQTT password created on the server
TLS	Enable for production deployments
Topic Prefix	acuvim (default, do not change unless instructed)

3. Tap Test Connection to verify the device can reach the broker.
4. Tap Save.

3.5 Configure Console URL

1. Navigate to Settings > Console.
2. Enter the console application URL: https://console.example.com
3. Tap Save.

This URL is used for OTA firmware update downloads and version checks.

3.6 Configure GSM (If Applicable)

1. Navigate to Settings > GSM.
2. Enter the APN details from your mobile carrier:

Field	Example
APN	internet
Username	(leave blank if not required)
Password	(leave blank if not required)
Enabled	Yes

3. Tap Save.
4. The device will attempt to register on the cellular network. This may take 30-60 seconds.

3.7 Configure Modbus (If Non-Default)

If the Acuvim II has a non-default slave address or baud rate:

1. Navigate to Settings > Modbus.
2. Adjust:
   • Slave Address: (default: 1)
   • Baud Rate: (default: 9600)
   • Poll Interval: (default: 5 seconds)
3. Tap Save.

3.8 Review Status Page

Navigate to the Status page on the captive portal to verify:

• WiFi: Connected with IP address and signal strength
• MQTT: Connected to broker
• GSM: Registered on network (if enabled)
• Modbus: Reading data from Acuvim II
• SD Card: Available with free space (if inserted)

---

4. Console Verification

4.1 Device Appears in Console

1. Log in to the console application at https://console.example.com.
2. Navigate to Devices.
3. Confirm the new device appears in the list with status "Online".
4. The device registers itself automatically on first MQTT connection.

If the device does not appear:

• Verify MQTT credentials are correct.
• Check the Mosquitto broker logs: docker compose logs mqtt.
• Check the console application logs: docker compose logs console.

4.2 Telemetry is Flowing

1. Click on the device in the console device list.
2. Navigate to the Telemetry tab.
3. Confirm that live telemetry data is appearing at the configured poll interval (default: every 5 seconds).
4. Verify the values are reasonable:
   • Voltage: 220-240V (single phase) or as expected for the installation
   • Current: Non-negative, within CT rating
   • Power factor: Between -1.0 and 1.0
   • Frequency: 49.5-50.5 Hz (or 59.5-60.5 Hz in 60 Hz regions)

4.3 Heartbeat Received

1. On the device detail page, check the Health section.
2. Confirm the heartbeat timestamp is recent (within the last 60 seconds by default).
3. Verify the heartbeat fields:
   • Firmware version matches the expected production version
   • Free heap memory is above 50 KB
   • Modbus error rate is below 1%
   • Boot count is 1 (first boot)

---

5. Functional Testing

5.1 Remote Ping Command

1. In the console, navigate to the device detail page.
2. Open the Commands tab.
3. Send a ping command.
4. Verify the device responds with pong within a few seconds.
5. The command status should show "Success".

5.2 Remote Configuration Read

1. Send a get_config command from the console.
2. Verify the response contains the configuration values you set during commissioning.

5.3 OTA Update Test (Optional)

If a test firmware version is available:

1. Navigate to Firmware in the console.
2. Deploy the current (or a test) version to the device.
3. Verify the device downloads, installs, and reboots successfully.
4. Confirm the device comes back online with the updated firmware version.

For first-time installations, this test confirms the OTA pipeline is functional for future remote updates.

5.4 Transport Failover Test (If GSM Enabled)

1. Disconnect the site WiFi (or move the device out of WiFi range).
2. Observe in the console that the device's connection type changes from wifi to gsm.
3. Verify telemetry continues to flow via GSM.
4. Restore WiFi and confirm the device switches back to WiFi.

---

6. Documentation

Record the following information for each commissioned device. This record should be stored in a site handover document and/or in the console application's device metadata.

6.1 Device Record

Field	Value
Device ID	ACV-______________
MAC Address	:::::
IMEI (if GSM)	_______________
Firmware Version	..__
Installation Date	____--
Installer Name	__________________
Site Name	__________________
Building / Area	__________________
Panel / Board ID	__________________
Acuvim II Serial Number	__________________
Acuvim II Slave Address	__
WiFi SSID	__________________
SIM Card Number (ICCID)	____________________
Mobile Carrier	__________________
APN	__________________
Power Source	USB / 5V Supply
SD Card Installed	Yes / No
GPS Coordinates (optional)	__, __

6.2 Photos to Take

1. Overall installation location (wide shot showing panel / DB board).
2. Close-up of the ESP32 board and wiring inside the enclosure.
3. RS485 terminal connections on the Acuvim II.
4. Acuvim II front panel showing the meter model and serial number.
5. Antenna placement (if GSM).
6. Enclosure label showing device ID.

6.3 Update Console Metadata

In the console application, update the device record with:

• Friendly name (e.g., "Building A - Main Incomer")
• Description (location details)
• Group assignment (e.g., "Building A" or "Site North")
• Tags (e.g., ["main-incomer", "3-phase", "building-a"])

---

7. Troubleshooting During Commissioning

Symptom	Action
No AP visible after power on	Wait 30 seconds. If still not visible, verify firmware is flashed. Connect via USB serial to check boot output.
AP visible but captive portal does not open	Open a browser and navigate to http://192.168.4.1 manually.
WiFi connects but MQTT fails	Verify MQTT broker address, port, username, and password. Check that the device credentials exist on the broker.
No Modbus data (all zeros)	Check RS485 wiring (A to A, B to B, GND to GND). Verify Acuvim II baud rate and slave address match device config.
Modbus errors but partial data	Check for loose terminal connections. Verify cable shielding and length. Add 120-ohm termination resistor.
GSM not connecting	Verify SIM card is inserted correctly and has an active data plan. Check APN settings. Ensure antenna is connected.
Device appears offline in console	Check MQTT connection on the captive portal status page. Verify firewall allows port 8883 outbound from the site network.
Telemetry values look wrong	Verify Acuvim II CT ratio and PT ratio settings. Check that the meter is measuring the correct circuit.

For detailed troubleshooting steps, see troubleshooting.md.