Network Configuration Is Not Device Binding: Model the Imou Onboarding State Machine

#camera #automation

Treat Imou onboarding as at least two different jobs: putting the device on a network, then associating it with a developer or user account. Network configuration (SmartConfig, SoftAP, wired, or other device-supported methods) is a client OpenSDK responsibility on current mobile documentation. Binding is an account and device-lifecycle operation; some newer devices require SDK-assisted binding rather than HTTP bindDevice alone. Do not collapse those states into a single “add camera” button that always calls one API.

Why it matters

Product UIs often show one progress bar labeled “connecting.” Failures then become unsupportable: Wi-Fi password errors, firmware that needs SDK pairing, wrong regional account, and already-bound devices all look the same. A state machine makes retries, user copy, and logs honest. It also keeps appSecret and administrator tokens on the backend while the phone handles only the local radio steps the SDK documents.

Support varies by device generation and firmware. This article does not publish a model matrix.

Approach / architecture

Model explicit states and owners:

State	Meaning	Typical owner
`UNPROVISIONED`	Device has no usable LAN/WAN path yet	Mobile OpenSDK on the phone
`NETWORK_READY`	Device can reach the platform path documented for that model	Client; verify with SDK/device signals, not hope
`BINDING`	Account association in progress	Backend + SDK-assisted path when required
`BOUND`	Device appears in authorized inventory	Backend device query
`FAILED_NETWORK`	Provisioning step failed	Client; collect SDK error without secrets
`FAILED_BIND`	Association failed	Backend; distinguish HTTP vs SDK-assisted requirement

select provisioning method (device-dependent)
  -> OpenSDK network configuration
  -> NETWORK_READY
  -> bind path (HTTP and/or SDK-assisted, version-dependent)
  -> list/query device
  -> BOUND

Do not call bindDevice until the client reports a documented ready condition. Do not treat a successful Wi-Fi join as proof of account binding.

Six implementation steps

List the device’s supported onboarding methods from current documentation and a real unit. SmartConfig, SoftAP, and wired are not universally interchangeable. Record the tested firmware.
Keep provisioning in the client SDK. Current mobile development guidance assigns network configuration, initialization, playback, and picture decryption to the client SDK. Do not invent an HTTP “configure Wi-Fi” substitute.
Keep secrets on the backend. The phone may receive short-lived, purpose-limited tokens if a documented flow requires them. It must not receive appSecret or a standing administrator accessToken.
Choose the bind path per device behavior, not per hope. If HTTP bindDevice fails on a unit that uses upgraded security firmware, follow the documented SDK-assisted binding path. Treat that as device-version-dependent, not a rule for every new SKU.
Confirm binding with inventory APIs. After a reported success, query the device from the backend with the credential the method page allows. UI success without inventory proof is incomplete.
Define retry and offboarding. Network failure retries stay in the SDK step. Bind failure must not loop bindDevice blindly. Unbind and user removal are separate lifecycle events; confirm side effects on the live bind/unbind pages rather than assuming storage or live URLs always survive.

APIs / SDKs

Mobile development summary: client vs HTTP split; SmartConfig/SoftAP; SDK-assisted bind note.
Device bind module: HTTP bind/unbind and related management.
Device query methods such as listDeviceDetailsByPage on their current pages: inventory confirmation after bind.

Limits & pitfalls

Do not publish a per-model provisioning matrix from this article.
Do not assume HTTP bindDevice works for every firmware generation.
Do not assume unbind deletes cloud storage or policies unless a live page says so.
Do not run provisioning from a backend that cannot reach the local radio.
Do not log Wi-Fi passwords, appSecret, or administrator tokens.
Recheck mobile and bind pages on publication day.

Support, logs, and test evidence

Support tickets should name the last successful state, not “camera won’t add.” Capture SDK result codes from the provisioning step separately from OpenAPI result codes from bind. Include device generation or firmware only when the user consents and your privacy policy allows it. Never include Wi-Fi passwords, QR payload secrets, appSecret, or administrator tokens.

A useful internal test card lists: method used (SmartConfig, SoftAP, wired, or other documented option), whether NETWORK_READY was observed, which bind path was attempted, HTTP versus SDK-assisted outcome, and whether backend inventory showed the device. Run that card on at least one device that succeeds with HTTP bind and, if you have one, one device that requires the SDK-assisted path. Do not generalize those two results into a catalog of SKUs.

Automation should stop at the API and SDK boundaries you actually documented. A backend job cannot complete SoftAP. A mobile screen cannot safely hold the administrator token used for account bind. If a product manager wants a single REST endpoint named /addCamera, implement it as an orchestrator that still respects the state machine and returns the failed state to the client.

When onboarding succeeds, schedule a follow-up check: device still listed, expected channel count, and no unexpected live addresses created as a side effect. When it fails, persist the state transition so a retry does not skip NETWORK_READY and hammer bindDevice. These operational habits are guidance for your application; they are not Imou availability guarantees.

A concrete backend skeleton

In code, represent onboarding as a persisted record: device_hint, state, provisioning_method, last_error_class, bound_device_id. The mobile app updates state through your BFF after SDK callbacks, never by writing OpenAPI itself. The BFF exposes POST /onboarding/{id}/network-result and POST /onboarding/{id}/bind. Bind uses administrator credentials only inside that service.

Timeouts should be per state. A SoftAP session that the user cancelled is not a bind timeout. A bind timeout should trigger inventory lookup before a second bind, in case the first call succeeded.

This skeleton is sample architecture. It is not an official Imou state machine SDK.

Read the mobile development summary and test onboarding as two states—network, then bind—on a real device before you ship a single “add camera” API.

DEV Community