Skip to main content
Provisioning does two separate things, and a device needs both before it can reach the platform:
  1. Wi-Fi + identity — credentials, device ID and owner, saved in Preferences
  2. Key registration — the device’s public key recorded against the account that owns it
The library persists the first, so it only happens once. The second is what the secure channel checks on every single connection.
A device with Wi-Fi but no registered key will connect to the relay and be refused with auth_fail: unknown device. The relay holds no record of its public key, so it cannot verify anything the device signs. In a serial log this reads like a network problem. It is not one.

Why the app is the supported path

Each device generates its own P-256 keypair on first boot. The private half is written to NVS and never leaves the chip — not in a log, not over the network, not to us. That is the whole point of the secure channel, and it is also what shapes onboarding:
  • The public key can only be obtained from the device itself
  • The device only offers it during AP-mode provisioning
  • Recording it requires a signed-in user who owns the device row
So an onboarding client has to do two things at once: join the device’s own Wi-Fi access point, and hold an authenticated session. A phone does both. A desktop browser cannot switch Wi-Fi networks, and while joined to the device’s AP it has no route to the internet to finish the registration.

Hyperwisor app (Android)

Install the app, then add your device from it. This is the only onboarding route supported for end users.

What begin() does

When you call device.begin(), the library:
  1. Loads or generates the device keypair (HSC)
  2. Tries to connect with saved Wi-Fi credentials
  3. Starts AP-mode if nothing is configured
  4. Sets up DNS + an HTTP provisioning page
  5. Initializes the realtime connection
  6. Loads deviceid, ssid, email, productid, and versionid from storage
  7. Registers default and user-provided command handlers

AP-mode provisioning (first boot)

If the device has no saved credentials it starts its own access point and serves a setup page: The app joins that network and submits Wi-Fi and identity. The device replies with an acknowledgment carrying its device_id and public_key; the app reads the key from that reply and registers it against your account. The device then restarts and connects on its own from then on. That acknowledgment is the only moment the public key is published — which is why abandoning setup half-way leaves a device on Wi-Fi but unregistered.

Setting credentials from code

These set Wi-Fi and identity only. They do not register the public key. A device provisioned this way is refused as unknown device until the key is registered by one of the methods below. This is not an onboarding path — use it for a device whose key is already registered, or on the bench where you register the key yourself.
Helpers to inspect and reset stored credentials:
Clearing credentials does not discard the keypair. A device keeps its identity across a re-provision, so it stays registered.

Registering a key without the app (development only)

Two options on the bench. Both need a user access token, which is why neither belongs in a shipped product: tokens expire, and a user’s session sitting on a device is a credential you cannot rotate. Read the key and register it yourself. Print it over serial, then call the endpoint with your own session:
Or let the device register itself:
Registration is an upsert, so re-running it after a factory reset is safe. The endpoint checks that the token’s user owns the device row — you cannot register a key against somebody else’s device.

Reading identity at runtime

Next: API reference

Every method you can call on the device.