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.

External IDs

In addition to their primary ID every device is assigned an “External ID”, which should be unique on each Campsite. This ID can be reassigned to a potential replacement device to ensure a consistent user experience. A QR-Code printed on a device should for example use the external ID for identification so that it can remain consistent, should the device need replacing. As an example, the socketMasters connection offers a filter to select a device by its external ID.

query devices {
  socketMasters(filters: {
    campsite: "Q2FtcHNpdGU6MzU3ODM2ZDUtMTBlNS00N2ZjLTgwMTMtM2EwYmY5N2ZjNTlj",
    externalId: "test-socket"
  }) {
    edges {
      node {
        label
      }
    }
  }
}

You will receive the socket master that matches your query, if any.

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.