Porting

Portings of the iottly SDK from the Python reference implementation to other languages are welcome!

The iottly SDK makes use of Unix domain sockets to communicates with a local iottly agent daemon, so in order to port the SDK you should be able to handle such communication mechanism from your environment.

In this document we will discuss the programming interface exposed by the iottly agent for the integration of an SDK.

UDS interface

This interface is provided by versions of the iottly agent >= 1.6.3.

Using this interface an SDK can communicate bi-directionally with the agent via a shared Unix domain socket.

Communication protocol

Once the sdk is connected to the iottly agent it must send a connected status signal message. In this message, the sdk identifies must identify the application passing an user-provided name.

After sending this start-up message the sdk must listen to signal or data message coming from the agent.

The sdk could receive (if connected to an agent >= 1.8.0) an sdkinit signal message from the agent containing the version of the agent. This information can be used asynchronously to adapt the communication protocol between sdk and agent to the most recent protocol understood by both. Until this message is not received, the sdk must assume a connection with an agent < 1.8.0 and must behave accordingly.

The sdk should allow the user to send messages to iottly. The sdk can also allow the user to send messages to a particular channel on iottly.

The sdk should allow the user to invoke the user-defined scripts available on the agent. If implemented, the sdk must ensure that this invocation happens without blocking in the case of a disconnected agent.

These messages are written to the socket with the JSON encoding described in the next section.

Payload specs

All the exchanged payloads are JSON encoded with the UTF-8 charset.

Messages sent from the SDK to the iottly agent

SDKs can send two types of messages to the iottly agent:

• signal messages

• data messages

Each type of message is denoted by the top-level key of the JSON message.

Currently supported messages:

• Status signal

{
  "signal": {
    "sdkclient": {
      "name": "<String>",
      "status": "connected",
      "version": "<Maj.Min.Patch>"
    }
  }
}

or

{
  "signal": {
    "sdkclient": {
      "name": "<String>",
      "status": "disconnected"
    }
  }
}

• Forwarding of errors to iottly

{
  "signal": {
    "sdkclient": {
      "name": "<String>",
      "error": {}
    }
  }
}

• Forwarding data to iottly

{
  "data": {
    "sdkclient": {
      "name": "<String>"
    },
    "payload": {}
  }
}

• Forwarding data to iottly with a specific channel

{
  "data": {
    "sdkclient": {
      "name": "<String>"
    },
    "payload": {},
    "channel": "<String>"
  }
}

• Calling user-defined script on the iottly agent

{
  "signal": {
    "sdkclient": {
      "name": "<String>",
      "call": {
        "<cmd_name>": {}
      }
    }
  }
}

Messages received by SDK from the iottly agent

• Connection status signal

{
  "signal": {
    "connectionstatus": "connected | disconnected"
  }
}

• Agent status signal

{
  "signal": {
    "agentstatus": "closing"
  }
}

Note

The started and stopped statuses are not received from the iottly agent but generated internally by the SDK.

• Agent version (semantic version number)

{
  "signal": {
    "sdkinit": {
      "version": "<Maj.Min.Patch>"
    }
  }
}

• Messages from iottly or from a Python snippet running on the agent.

{
  "data": {
    "cmd": {
      "k": "v"
    }
  }
}

Changelog

• Version 1.3.0:

  • Adds SDK version to the connected status signal sent by the SDK at start-up.

  • Adds sdkinit signal sent by the agent to communicate its version to an SDK client.

  • Adds payload to type to call user-defined script on the agent from the SDK.