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.