Overview

The first step in communicating with the cloud is for the Device to register itself and obtain the authorization credentials needed for all future API calls.

The Device should send its registration request as soon as it has network connectivity. The exact fields to include depend on the authentication method — see Authentication Method for the required fields per method.

Registration is performed via the Register Device API and returns the following fields:

• id — Unique ID assigned to the Device.
• access_key — Authentication key that must be used for all future communication.
• hub_url — URL of the Hub Server assigned to this Device.
• hub_url_static_cert — URL of the Hub Server assigned to this Device that accepts custom SSL certificates.
• mqtt_hub_url — Relevant only for Devices authenticating with MQTT. See MQTT Endpoints.

All subsequent communication must be directed to the server in hub_url (or hub_url_static_cert) and authenticated with the returned id and access_key. Pass the id in the deviceId URL parameter and the access_key in the HTTP Authorization header.

A Device can register only once. The Provisioning Server prevents a Device with the same Cloud ID or MAC/SN combination from registering again.

The Provisioning Server address and custom SSL settings are available in the Provisioning Server area of the Partner Portal.

Registration flow

On first boot, or whenever it first connects to the network, the Device calls the Register Device API against the Provisioning Server.

If registration fails, retry on every subsequent boot or network reconnection until it succeeds. A retry interval of around 15 minutes works well in practice.

Devices on a Model whose Authentication Method is X.509 Certificate register in two steps: the first call is answered with a challenge, which the Device signs with its private key before resending. See Registering with an X.509 certificate.

Deleted devices

If a Device is deleted from the cloud (via API or via support), all subsequent API calls made by that Device will return HTTP 401 Not authorized. The Device must re-register to obtain a new id, access_key, and hub_url.

Using the same credentials on more than one unit

Xyte identifies a Device only by the id and access_key it received at registration. It does not check which hardware or which program is presenting them. If two units present the same credentials, both are treated as the same Device: telemetry from either one updates the same record, and any child Devices either one registers are created under that Device, in its organization and Space.

In practice this shows up as a second processor (a test unit, a replacement, or one loaded with a program that carries another unit's credentials) populating the original Device's Space with child Devices and reporting their status. No Device is moved; the second unit is simply acting as the first.

To avoid it:

• Store credentials per unit, never inside a program image that may be loaded on other hardware.
• Before repurposing a unit for testing or another site, clear the credentials it stored at registration, or delete the Device from the cloud. After deletion its credentials return 401, and the unit registers again as a new, unclaimed Device.
• A replacement unit should register as a new Device rather than inherit the old one's credentials.

Child device registration

The Xyte architecture lets Devices that cannot reach the cloud directly communicate through a parent Device.

The parent Device registers as a normal Xyte Device, then calls the Register Child Device API to register each of its children. See the Child Devices section for the full pattern.

Sub-models

Some Device Models share the same Commands, Telemetry, and Configuration but differ in naming or minor hardware specifics. The platform supports these via Sub-models: pass a sub-model field in the registration body to identify which variant the Device is.