Network Protocol

Network Protocol

How the factory app talks to the device and its cloud. The ESPHome config does not use any of this; it is documented so the behavior is understood.

1. Onboarding (device in AP mode)

The device serves a local HTTP page, opened by the mobile app with query parameters:

http://<device-ap-ip>/index.html?ott=<token>&apiUrl=<host>&mode=<mode>&deviceType=<type>

The page uses this local API:

Call	Method	Purpose
scan_wifi	POST	Trigger a WiFi scan
dev_info	GET	Read current WiFi state
dev_actions	POST {deviceType}	Set device type option
config	POST	Submit WiFi + pairing config

POST /config body:

{
  "data": [
    {"type": "TOKEN", "data": "<ott>"},
    {"type": "SERVER_CREDENTIALS", "host": "<apiUrl>"},
    {"type": "WIFI_CONFIG", "ssid": "<ssid>", "pass": "<password>"}
  ]
}

The body is effectively plain JSON; there is no encryption to replicate.

2. Cloud registration

After pairing, the device talks HTTPS to the host it was given.

• Endpoint: POST /device-api/v2/register
• Headers: device-id, x-device-id, x-device-ott, plus standard Authorization / Content-Type.
• TLS uses a public CA bundle with no certificate pinning.

Relevance to ESPHome

The unit also has an offline mode, so the cloud is not needed for local operation. The ESPHome config skips registration, tokens and the captive portal. See ESPHome Replication Plan.