# M1730-ESP32

ESP32 firmware that drives one or more **M1730 analog panel meters** (moving-coil ammeters) via PWM, with a web configuration UI and Home Assistant integration over MQTT.

## Table of contents

- [How it works](#how-it-works)
- [Hardware](#hardware)
- [Building and flashing](#building-and-flashing)
- [First-time Wi-Fi setup](#first-time-wi-fi-setup)
- [Web UI](#web-ui)
- [MQTT / Home Assistant](#mqtt--home-assistant)
- [HTTP API](#http-api)
- [Configuration reference](#configuration-reference)

---

## How it works

Each meter needle is controlled by a PWM signal on a GPIO pin. The firmware maps a **0–100 %** value to a PWM duty cycle, scaled by a per-meter **Max Duty** percentage that you calibrate for full-scale deflection. All settings are stored in LittleFS (`/config.json`) so they survive reboots.

```
needle position = (currentValue / 100) × (maxDuty / 100) × 1023 ticks
```

PWM runs at 5 kHz with 10-bit resolution (0–1023).

### Physical range mapping

Each meter has configurable **Min** / **Max** values that define its physical range (e.g. 0–50 A). The firmware normalises to 0–100 % internally, but MQTT publishes and receives in physical units — Home Assistant never has to deal with percentages.

---

## Hardware

| Item | Details |
|------|---------|
| MCU | ESP32-S3 DevKitC-1 |
| Meter | M1730 moving-coil panel ammeter (or any PWM-driveable analog meter) |
| Max meters | 8 simultaneous (ESP32 LEDC channels 0–7) |
| PWM freq | 5 kHz |
| PWM resolution | 10-bit |

Connect the meter coil (via a current-limiting resistor sized for full-scale) between a GPIO pin and GND. Find the correct resistor value by raising **Max Duty** slowly until the needle reaches full scale. 660

---

## Building and flashing

The project uses [PlatformIO](https://platformio.org/).

```bash
# Build
pio run

# Flash
pio run --target upload

# Open serial monitor (115200 baud)
pio device monitor
```

Board target: `esp32-s3-devkitc-1`

---

## First-time Wi-Fi setup

On first boot (or when stored Wi-Fi credentials are missing), the device starts an access point named **M1730**. Connect to it with any phone or laptop — a captive portal will appear automatically.

1. Enter your Wi-Fi SSID and password.
2. Optionally change the **Device hostname** (default: `m1730`).
3. Click **Save**. The device connects to your network and restarts.

After connecting, the device is reachable at:

- `http://m1730.local` (mDNS, works on most local networks)
- `http://<IP address>` (shown in the serial monitor on boot)

---

## Web UI

Browse to the device address to open the configuration page.

### Info panel

Shows the current hostname and IP address.

### Hostname

Sets the mDNS name (`<hostname>.local`) and the MQTT device name. Saved across reboots.

### Meters

Use the **Meters** dropdown to add or remove meters (1–10). Each meter has:

| Field | Description |
|-------|-------------|
| Pin | GPIO pin number connected to the meter coil via current limiting resistor |
| Name | Label shown in Home Assistant and the web UI |
| Unit | Optional unit string shown in Home Assistant (e.g. `W`, `A`, `°C`) |
| Min / Max | Physical range of the meter (e.g. 0–50 A, 0–3000 W). MQTT publishes and receives values in this range; HA discovery uses these as the number entity min/max |
| Max Duty | PWM duty at full scale, as a percentage (0–100). Calibrate this so the needle just reaches full deflection |
| Output slider | Moves the needle live (0–100 % of the configured range). Also sent to MQTT |

Click **Save** to persist all settings. Changing the meter count also triggers an immediate save and meter re-attach.

---

## MQTT / Home Assistant

### Enabling MQTT

In the **MQTT** section of the web UI:

| Field | Description |
|-------|-------------|
| Enable | Toggle MQTT on/off |
| Broker | Hostname or IP of your MQTT broker |
| Port | Default `1883` |
| User / Pass | Broker credentials |
| Prefix | Topic prefix (default `m1730`) |

### Home Assistant auto-discovery

On connect, the device publishes discovery payloads to `homeassistant/number/…/config`. Each meter appears in HA as a **Number** entity with `min`/`max` taken from the meter's configured physical range and a step of 0.1. The entities are grouped under a single HA device named after the hostname.

### Value mapping

Internally the firmware works with a 0–100 % duty value. MQTT publishes and receives **physical values** — the percentage is transparently mapped to the meter's Min–Max range:

```
physicalValue = percentage / 100 × (rangeMax - rangeMin) + rangeMin
```

For example, with Min=0 and Max=50, the slider at 50 % publishes `25.0` to MQTT, and a command of `25.0` on the `/set` topic moves the slider to 50 %.

### Topics

| Direction | Topic | Description |
|-----------|-------|-------------|
| Published | `<prefix>/meter/<n>/current` | Current meter value in physical units (retained) |
| Subscribed | `<prefix>/meter/<n>/current/set` | Set meter value in physical units |
| Published | `<prefix>/status` | `online: true` on connect, `online: false` as LWT |

`<n>` is the zero-based meter index.

### Reconnection

The firmware probes the broker TCP port before attempting a full MQTT connect. If the broker is unreachable, it retries every 30 seconds without blocking the web server.

### Example HA automation

```yaml
automation:
  - alias: Show solar power on meter
    trigger:
      platform: state
      entity_id: sensor.solar_power_w
    action:
      service: number.set_value
      target:
        entity_id: number.m1730_solar
      data:
        value: "{{ trigger.to_state.state | float | round(1) }}"

# Values are in physical units — if the meter Min=0, Max=3000, the HA
# number entity directly accepts watts, no conversion needed.
```

---

## HTTP API

### `GET /set?i=<index>&v=<value>`

Immediately moves meter `<index>` to `<value>` (0–100), updates PWM, persists the value to flash, and publishes to MQTT. Used by the live slider on the web UI.

| Parameter | Type | Description |
|-----------|------|-------------|
| `i` | integer | Meter index (0-based) |
| `v` | float | Value 0–100 |

Returns `200 OK` on success, `400` on bad input.

### `GET /`

Returns the full HTML configuration page.

### `POST /config`

Saves all configuration from the HTML form and re-applies PWM to all meters. Responds with the updated configuration page.

---

## Configuration reference

Config is stored as JSON in LittleFS at `/config.json`.

```json
{
  "hostname": "m1730",
  "mqtt": {
    "enabled": true,
    "host": "192.168.1.10",
    "port": 1883,
    "user": "ha",
    "pass": "secret",
    "prefix": "m1730"
  },
  "meters": [
    {
      "pin": 4,
      "maxD": 72.5,
      "current": 45.0,
      "name": "Solar",
      "unit": "W",
      "rangeMin": 0.0,
      "rangeMax": 3000.0
    }
  ]
}
```

The file is written by the web UI and should not need manual editing. To reset to factory defaults, delete the file or erase flash with `pio run --target erase`.