API Reference
Start typing to search…

Full cloud to cloud connector

Overview

This type of connector is used to synchronize both devices and detailed tenant data between the Xyte and Partner cloud.

If End Customers create accounts on your cloud, build up tree of locations and devices, this integration allows to sync both the device data and re-create the current End Customer's tree structure and device inventory in Xyte.

User Flow

This is the recommended from for a User connecting to the OEM's Cloud and adding the Xyte integration.

  1. User logs into the OEM cloud
  2. User selects the add "Xyte Integration" option
  3. The system shows the user helpful information on how to
    1. Sign-up or sign-in to the Xyte Cloud
    2. Obtain an API key
  4. The User copies the API key and enabled the integration
  5. The C2C integration registers devices with the Xyte cloud and starts sending data (telemetries, etc)
  6. The C2C integration copies the "space" (location/container/etc) structure to the User's Xyte tenant via the "Space Management APIs"
  7. The C2C integration assigns devices to the User's Xyte tenant

Implementation

Setup Partner Portal

  1. Obtain credentials to access your Xyte Partner portal at https://partners.xyte.io

  2. Navigate to Model Management https://partners.xyte.io/models

  3. Click "Add Model" to create your first model (SKU)

  4. Fill in "Model name" and change "Authentication method" to "MAC & Serial Number

  5. Copy the "Model ID" (for later)

  6. Go to the "Hardware Keys" tab and copy the first key (for later)

Register Device

Use the Register Device API:

  1. device_model - Model ID from step #5 above
  2. hardware_key - Hardware Key from step #6 above
  3. mac - MAC address of your device
  4. sn - Serial number of your device
  5. 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"
}

Copy and save the "id", "access_key" and "hub_url" fields for the next step.

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 Telemetry API:

  1. Use the "hub_url" from the above step, as the target URL
  2. Use the "id" from the above step in the URL between the /device/and /telemetryparts
  3. Use the "access_key" from the above step as the value to the "Authorization" header.
  4. 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}}'

Setup 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".

Visit the lab and:

  1. Navigate to "Settings" (left side menu)
  2. Navigate to API Keys
  3. Click "Create API Key", give it a name and copy the key for the next steps.

Create Space

Use the Create Space API:

  1. Use the "api key" from step #3 above as the value to the "Authorization" header.
  2. Select a name for the new space you want to create
curl --request POST \
  --url https://hub.xyte.io/core/v1/organization/spaces \
  --header 'Authorization: 365315e276c3056a01.......' \
  --header 'content-type: application/json' \
  --data '{
  "name": "My location"
}'

The returned data should be in a format similar to:

{
  "id": 100000,
  "name": "My location",
  "parent_id": 99999,
  "config": {
    "img": null,
    "priority_factor": 0,
    "inherit_location": true,
    "temperature_units": "celsius",
    "inherit_priority_factor": true,
    "inherit_temperature_units": true
  }
}

Copy the "id" of the generated space for the next step.

Customers vs Spaces

Since the Xyte cloud supported the concepts of multiple Customers being managed in a single End Customer Portal, the above code will generate a new "Customer" as no parent_id parameter was provided to the "Create Space API".

A full implementation of the integration, should use the Get Spaces API to retrieve the list of top-level spaces and ask the User first to select under which Customer space to import the devices from the OEM's cloud. And use that Customer space as the parent for all sub-spaces.

In our sample we are actually creating a Customer type space, which is a sub-tenant. As such, devices and spaces synced between the clouds will not be movable to other Customer spaces.

Assign Device

Now we can assign the device that was registered during the "Register Device" step to the User's Xyte tenant under the space created in the "Create Space" step.

Use the Claim Device API:

  1. Use the "api key" from step #3 of "Setup End Customer Portal" as the value to the "Authorization" header.
  2. space_id - The "id" of the space returned during the "Create Space" step
  3. mac - The MAC address of the device from the "Register Device" step
  4. sn - The serial number of the device from the "Register Device" step
  5. name - Any friendly name to give the device
curl --request POST \
  --url https://hub.xyte.io/core/v1/organization/devices/claim \
  --header 'Authorization: 365315e276c3056a01.......' \
  --header 'content-type: application/json' \
  --data '{
  "name": "My nice name",
  "space_id": 100000,
  "cloud_id": "fJxbx5zb5Sz4m0.........."
}

Verify

Visit your End Customer Xyte Portal at https://app.xyte.io

  1. Navigate on to "Overview" (right side menu)

  2. Select the Customer space created during the "Create Space" step

  3. You should see the claimed device

  4. Click the device and navigate to "State" to see the data sent during the "Send Telemetry" step.


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