Skip to content
Cynox IoT Documentation

Devices and Commands

Devices

Devices in the GraphQL API follow a hierarchical structure. All device types implement the DeviceBase interface.

Unique IDs

The primary “id” is used to identify a device within the API environment. A callback from a webhook for example, would refer to a device using this id. The “externalId” gets assigned during device setup on premises. A device is normally dedicated to a specific location and/or use case. It can be assumed, that the “externalId” does not change, even if a physical device needs to be replaced at some point. A use case could be scanning a QR-code, containing the “externalId” and using it to identify a socket master, to switch on power.

As an example, the socketMasters connection offers a filter to select a device by its external ID.

query devices {
  socketMasters(filters: {
    campsite: "Q2FtcHNpdGU6MzU3ODM2ZDUtMTBlNS00N2ZjLTgwMTMtM2EwYmY5N2ZjNTlj",
    externalId: "E598F20D-E4B1-4D1F-8FF4-A2699D3C4704"
  }) {
    edges {
      node {
        label
      }
    }
  }
}

This will return the socket master that matches your requested “externalId”, if found.

Issuing device commands

The GraphQL API allows you to issue commands to a device. Commands are represented in GraphQL by the DeviceCommand interface with different commands providing an appropriate subtype. To issue a command, create a new DeviceCommand object using the appropriate mutation. For example, to request a socket to switch on or off, use the requestSocketSwitchState mutation.

Command states

Because commands represent asynchronous operations, they go through a series of states:

state transitions initial Created Created initial->Created Cancelled Cancelled Sent Sent Created->Sent sent to device    Sent->Cancelled Timed out waiting for device    Confirmed Confirmed Sent->Confirmed Device acknowledged    Confirmed->Cancelled Execution timed out    Confirmed->Cancelled Timed out waiting for device    ^success? Confirmed->^success? Execution successful    Done Done Error Error ^success?->Done yes    ^success?->Error no    ^success?->^success?

After a command has been issued, the execution state should be monitored, to evaluate the progress/result. This can be achieved by either polling the command, or by using a GraphQL subscription which automatically notifies about command updates.

Polling a command

The ID of a command will be returned when the respective mutation is executed. It can be used to request the current command status using a node query.

query MyQuery {
  node(
    id: "U29ja2V0TWFzdGVyU2V0U3dpdGNoU3RhdGVDb21tYW5kOmRjN2Y0MzA1LTllZWEtNGFhZC05N2IzLTNhMzQyZjMzYWNjZA=="
  ) {
    ... on DeviceCommand {
      executionState
      errorMessage
      inProgress
    }
    ... on SocketMasterSetSwitchStateCommand {
      switchState
    }
  }
}

As long as inProgress is true, the command has not reached its final executionState (DONE, ERROR or CANCELLED). In case of an error, the errorMessage provides additional information, about why the command failed.

A response would look similar to this:

{
  "data": {
    "node": {
      "executionState": "DONE",
      "errorMessage": null,
      "inProgress": false,
      "switchState": "OFF"
    }
  }
}

Getting notified about device changes

To get notified about device and command changes, you can use Webhooks or GraphQL Subscriptions.