Overview

This type of connector only synchronizes devices and their state between the Xyte and Partner cloud. End Customer related account data (space tree structure, etc) is not synchronized and is managed separately or only in one cloud.

One Time Setup

Create Model(s) in the Partner Portal

Obtain credentials to access your Xyte Partner portal at https://partners.xyte.io
Navigate to Model Management https://partners.xyte.io/models
Click "Add Model" to create your first model
This can either be very generic (single model), family (speaker) or a specific SKU.
Fill in "Model name" and change "Authentication method" to "MAC & Serial Number
Copy the "Model ID" (for later)
Go to the "Hardware Keys" tab and copy the first key (for later)

Ongoing Integration

For each device registered with our current cloud solution, or new devices being added:

Register Device with Xyte
Start periodic Telemetry Sync

Register Device

Use the Register Device API:

device_model - Model ID (step #5 in Create Model(s) in the Partner Portal)
hardware_key - Hardware Key (step #6 in Create Model(s) in the Partner Portal)
mac - MAC address of your device
sn - Serial number of your device
firmware_version - Semver based firmware version of your device

curl https://entry.xyte.io/v1/devices \
      -H "Content-Type: application/json" \
      -X POST \
      --data '{"device_model":"755ab4a0-37b1-4bf0-b3e4......","hardware_key":"4fa553d3-e88e-4e0a-a6......","mac":"8E:00:00:00:00:06","sn":"1000","firmware_version":"1.1.1"}'

The returned data should be in a format similar to:

{
    "id": "19f85812-ee1a-4732-a115-f3b9afdadeab",
    "access_key": "fa5549605d5f7559257b1bd2055d730b",
    "hub_url": "https://eu-1.endpoints.xyte.io",
    "hub_url_static_cert": "https://eu-1.cssl.endpoints.xyte.io",
    "mqtt_hub_url": "mqtts://mqtt-us-1.endpoints.xyte.io:8883"
}

Save the following fields in a local database for each of the devices:
id, access_key and hub_url

Send Telemetries

The device should update the server on its current state, both periodically (30-60 seconds) or when a change happens.

Use the Send Mass Telemetry

Use the hub_url from the above step, as the target URL
Use the id from the above step in the URL between the /device/and /telemetryparts
Use the access_key from the above step as the value to the "Authorization" header.
The data contains the "status" of the device and a "telemetries" key containing a flat key/value mapping of all data points to sync to the cloud.

curl https://eu-1.endpoints.xyte.io/v1/devices/19f85812-ee1a-4732..../telemetry \
      -H "Content-Type: application/json" \
      -H "Authorization: fa5549605d5f7559257b...." \
      -X POST \
      --data '{"status":"online","telemetries":{"cpu":30,"input":"hdmi","muted":true}}'

The Send Mass Telemetry API can be used to send telemetry data for multiple devices in a single call.

Carefully review the return statuses for the call and handle removed devices accordingly.

Verify

Login to End Customer Portal

For testing a "Lab" tenant is automatically created on the End Customer Portal, you can access it by visiting https://app.xyte.io and using the same credentials as the Partner Portal credentials from step #1 in "Setup Partner Portal".

spaces synced between the clouds will not be movable to other Customer spaces.

Claim a Device

Click "Overview" on the left side menu.
Click the "Add Device" button on top right.
Select a model you created during setup.
Provide the Mac and SN pair for one of the registered devices.
Your device should be claimed and visible in the UI. Check the "State" tab to see the current state of the device as calculated from sent telemetries.

The Partner Portal can be used to generate visual widgets to display the information in a user friendly way.