Greencell: the charger on your own broker, not a cloud it never had

The HabuDen has no cloud API to connect to. It is commissioned over Bluetooth in
the Greencell GC app, pointed at an MQTT broker the owner runs, and from then on
publishes there — so the connector is an MQTT client rather than an HTTP one,
and nothing in it reaches Greencell. The wire contract is Home Assistant's own
greencell component and the greencell_client 1.0.3 library beneath it, which is
the only published description of the topics: a BROADCAST on /greencell/broadcast
draws device announcements, and /greencell/evse/{sn}/ carries current in
milliamps, voltage, power under "momentary", the EVSE state, and the access level
chosen in the app.

That meant an MQTT client, and the server takes no dependencies, so internal/mqtt
is hand-rolled the way internal/ocpp's RFC 6455 layer is. It is scoped to what
this connector needs and says so: QoS 0 for everything we send, clean session,
no reconnect — a connection lives for one plugin call, which is exactly how the
manager builds and tears down an instance. Inbound PUBLISH is accepted at QoS 0,
1 and 2 with the acknowledgements each requires, because the QoS of a delivery is
the broker's choice and not ours; an unacknowledged QoS 1 is redelivered forever.

Read-only, and the reason is worth writing down rather than rediscovering. A
device in EXECUTE mode accepts START, STOP, SET_CURRENT and QUERY — but the topic
those go to appears in no source: not Greencell's integration page, not
greencell_client, and Home Assistant ships sensor-only for that same reason.
Publishing to a guessed topic would be a control feature whose failure mode is a
driver believing they stopped a charge. So the access level is reported, and
commandTopic is the seam: an operator who has watched their own broker and found
theirs sets it, and a state read then sends QUERY — the one command a READ-mode
device also honours — instead of waiting out the charger's publish cadence. The
day the topic is public, control is a payload away from the same field.

What the cascade resolves here is a broker, not an account, so host, port, TLS and
credentials resolve together from the highest layer that names a host: an
organization's address paired with a user's password would address a broker with
credentials never meant for it. The serial, the QUERY topic and the listen window
each describe the charger rather than the endpoint, so each resolves on its own.

Two reading rules the tests pin. A phase the device did not report stays nil
rather than zero, because zero amps on a charger is a real measurement — a JSON
null decoding to 0.0 was a live bug until a test caught it — and a partial read
returns with received/complete flags instead of failing, since a device that
publishes some topics on a slower cadence is still worth reading. And a reachable
broker with no charger on it is degraded, not down: the half we configure works
and the missing half is the device. The plugin's end-to-end tests run against an
in-process broker written to the raw wire format, so a bug in the client cannot
hide behind a matching bug in the fixture.

The apps get the third connector card. The panel needed nothing — it renders a
plugin's ConfigFields itself — but the per-user panes are still hand-written per
integration, which is now three near-copies and the argument for the generic
version already noted in the plugins README. The web form splits the broker from
the charger because the server resolves them differently. The phone card is a
declarative config against the shared widget, which gained a number field type, a
degraded state that reads amber rather than red, and a fix for a locked field
that was covering its own displayed value with dots. Twenty keys in three
languages across both apps; Greencell, HabuDen and the literal QUERY join the
proper nouns that stay in English.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

API Server/README.md

@@ -26,15 +26,16 @@ internal/
 │   ├── technical.go  fuel.go  charging.go  maintenance.go  documents.go
 │   ├── reminders.go
 │   ├── attachments.go       # one optional file per record (shared handlers)
-│   ├── integrations*.go     # per-user Toyota / Anker Solix settings + OCPP control
+│   ├── integrations*.go     # per-user Toyota / Anker Solix / Greencell settings + OCPP control
 │   └── dist/                # built panel, embedded via go:embed
 ├── config/config.go      # env + .env load, .env write-back
 ├── models/models.go      # domain types + derived-field computation
+├── mqtt/                 # hand-rolled MQTT 3.1.1 client (Greencell EVSE telemetry)
 ├── ocpp/                 # OCPP 1.6J Central System (Anker Solix charging control)
 ├── pb/client.go          # PocketBase superuser client (runtime-retargetable)
 └── plugins/              # plugin system — see plugins/README.md
     ├── plugin.go  manager.go  external.go  doc.go
-    └── builtin/          # built-in connectors: toyota, ankersolix
+    └── builtin/          # built-in connectors: toyota, ankersolix, greencell
 panel/                    # Vue 3 + Tailwind panel source
 scripts/                  # Node/Python maintenance scripts
 bin/api-server.exe        # prebuilt binary the deployment runs
@@ -177,6 +178,9 @@ GET    /api/integrations/toyota        PUT /api/integrations/toyota      POST /a
 GET    /api/integrations/toyota/vehicles
 GET    /api/integrations/anker-solix   PUT /api/integrations/anker-solix POST /api/integrations/anker-solix/health
 GET    /api/integrations/anker-solix/chargers
+GET    /api/integrations/greencell     PUT /api/integrations/greencell   POST /api/integrations/greencell/health
+GET    /api/integrations/greencell/chargers
+GET    /api/integrations/greencell/chargers/{sn}/state
 
 # Anker Solix OCPP charging control (own/proxy mode + a live CSMS session)
 GET    /api/integrations/anker-solix/chargers/{sn}/control
@@ -292,10 +296,10 @@ state and global config persist to PocketBase, in the `app_settings` singleton
 the same place the per-org and per-user layers of the cascade live.
 
 See **[`internal/plugins/README.md`](internal/plugins/README.md)** for the full
-guide. Two built-in connectors ship today — **Toyota Connected** (`toyota`,
-read-only MyToyota vehicle data) and the **Anker Solix** V1 EV charger
-(`anker-solix`) — and any number of external HTTP plugins can be registered at
-runtime with no rebuild.
+guide. Three built-in connectors ship today — **Toyota Connected** (`toyota`,
+read-only MyToyota vehicle data), the **Anker Solix** V1 EV charger
+(`anker-solix`) and the **Greencell** HabuDen EV charger (`greencell`) — and any
+number of external HTTP plugins can be registered at runtime with no rebuild.
 
 ### Integrations & charging control
 
@@ -309,6 +313,20 @@ per-charger control token, not a bearer token) and the owner can start/stop and
 set charge limits, with every command rate-limited and written to a
 `control_audit` trail.
 
+**Greencell** takes the other route. The HabuDen wallbox has no cloud API: it is
+commissioned over Bluetooth in the Greencell GC app, pointed at an MQTT broker
+the owner runs, and from then on publishes its telemetry there. The connector is
+therefore an MQTT client (`internal/mqtt`, hand-rolled like the WebSocket layer,
+since the server takes no dependencies) that joins the same broker and reads
+`/greencell/evse/{sn}/…` — the topics Home Assistant's own `greencell`
+integration speaks, which is the only published description of the protocol. It
+is read-only: the device accepts START/STOP/SET_CURRENT in EXECUTE mode, but the
+topic those go to is documented nowhere, and Home Assistant ships without control
+for the same reason. An operator who has identified their own command topic can
+set `commandTopic`, which is used only to send `QUERY` — the one command a
+READ-mode device also honours — so a read does not have to wait out the
+charger's own publish cadence.
+
 ## Configuration
 
 Copy `.env.example` to `.env` and fill in. Summary: