API

class IottlySDK(name, socket_path='/var/run/iottly.com-agent/sdk/iottly_sdk_socket', max_buffered_msgs=10, on_agent_status_changed=None, on_connection_status_changed=None)

Class handling interactions with the iottly-agent

After initializing the SDK it is possible to:

  • Register callbacks that will be called when a particular type of message is received from the iottly agent.

  • Send messages to iottly through the iottly agent

The SDK is initialized with a name that will identify your application in your iottly project.

Optionally you can provide 2 callbacks to the IottlySDK constructor:

  • on_agent_status_changed: that will be called when the SDK connect

    and disconnect from the iottly agent. This callback will receive a string argument of:

    • started: if the sdk is successfully linked with the iottly agent

    • stopping: if the iottly agent is going through a scheduled reboot

    • stopped: if the sdk is disconnected from the iottly agent

  • on_connection_status_changed: that will be called when the iottly agent

    has sent a notification on a change in the MQTT connectivity of the device. This callback will receive a string argument of:

    • connected: MQTT is up in the linked iottly agent

    • disconnected: MQTT is down in the linked iottly agent

      (messages sent with the iottly agent while disconnected will be bufferd internally)q

Parameters

name (str) – an identifier for the connected application.

Keyword Arguments

  • socket_path (str) – the path to the unix-socket exposed by the iottly agent.

  • max_buffered_msgs (int) – the maximum number of messages buffered internally.

  • on_agent_status_changed (func, optional) – callback to receive notification on the iottly agent status.

  • on_connection_status_changed (func, optional) – callback to receive notification on the iottly agent connection status.

subscribe(cmd_type, callback)

Subscribe to specific command received from the iottly-agent.

After subscribing a callback for a command type, the iottly SDK is notified each time the iottly agent receives a message for the particular command.

The callback will be invoked with a dict containing the command parameters.

Note

If you call subscribe with a cmd_type already registered the callback is overwritten.

Parameters

  • cmd_type (str) – The string denoting a particular type of command.

  • callback (func or callable) – The callback invoked when a message of type cmd_type is received from the iottly agent

Raises

TypeError – The method was invoked with an argument of wrong type.

start()

Connect to the iottly agent.

send(msg, channel=None)

Sends a message to iottly.

Use this method for sending a message to iottly through the iottly agent running on the same machine.

If the agent is unavailable the message is buffered internally. At most max_buffered_msgs messages will be kept in the internal buffer, after this limit is reached the older messages will be discarded.

See also

The max_buffered_msgs parameter is configurable during the SDK initialization.

Parameters

  • msg (dict) – The data to be sent. The dict should be JSON-serializable.

  • channel (str) – The channel to which the message will be forwarded. This can be used, for example, to route traffic to a specific webhook. Default to None

Raises

  • TypeError – send was invoked with a non dict argument.

  • ValueError – send was invoked with a non JSON-serializable dict.

call_agent(*args, **kwargs)

Call a Python snippet in the user-defined scripts of the attached agent.

Use this method when you want to invoke a snippet from the user-defined scripts in the iottly agent currently attached to this instance of the iottly SDK.

Calls to user snippets are kept synchronous so, if the agent is unavailiable the call is dropped with a DisconnectedSDK error. You should trap this error and retry later after the SDK has established a connection with the iottly agent (see the on_agent_status_changed callback in the SDK constructor).

Warning

Requires iottly agent version >= 1.8.0

Parameters

  • cmd (str) – The name of the command to be called.

  • args (dict) – The arguments that will be provided to the user-defined command. This dict must be JSON-serializable.

Raises

  • DisconnectedSDK – call_agent called while the SDK was not connected to a iottly agent.

  • InvalidAgentVersion – call_agent called while the SDK was connected to an agent < 1.8.0