Connectors

While you can certainly use any of our libraries to develop applications for the embedded devices of your choosing, we also provide you with a series of hands-off device connectors that make it easy to get your device up and running on BUGswarm without having to write any embedded code.


How they work:

A connector is a client-side, device-specific application that allows you to quickly get your embedded devices connected to and participating on BUGswarm. With a minimal amount of configuration and zero embedded code to write, you can have your devices producing and consuming in a matter of minutes. In order to achieve this simplicity and ease, connectors follow a specific messaging contract with all applications that may be interested in the data that connectors produce. For instance, the BUGswarm Management UI is a web application used to create and configure swarms and resources. Additionally, the UI allows for communication with devices exhibiting the connector contract and producing Location and Acceleration feeds. For an example of how this communication between connectors and connector-interested applications such as the Management UI, check out our JavaScript-based Web Connector. Simply input your participation API key, the ID of the resource you wish to use as your web-connector device, and the ID of the swarm it is a member of and click 'Connect'. You should then be able to view that resource in the Management UI and observe that the Location and Acceleration services are now available. Keep in mind that if you are not using one of the supported devices listed in the web-connector, you may not receive valid data.


Contract:


Connector connects to a swarm:

  1. Send a private Capabilities message to each swarm member based on the swarm presence available messages received.

Connector disconnects from a swarm:

  1. Cancel any active feed responses associated with that swarm.

Connector has a new feed:

  1. Send a private `Capabilities` message to each swarm member based on the swarm presence available messages received.

Connector loses a feed:

  1. Send a private `Capabilities` message to each swarm member based on the swarm presence available messages received.
  2. Cancel any active feed responses associated with the swarms it is a member of for that feed.

Member joins the swarm:

  1. Send a private `Capabilities` message to the new member.

Member leaves the swarm:

  1. Cancel any active feed responses to that member.

Member requests a feed:

  1. Parse the feed request.
  2. Send a private feed response for that feed to the requesting member with the desired response parameters.


Capabilities:

When a connector connects to a swarm, it sends the capabilities message privately to all members of that swarm. Additionally, once already connected, the connector sends a private capabilities message to each new member that connects to that swarm. The capabilities message contains relevant information regarding what the connected device is capable of producing. Currently, the capabilities message is simply a wrapper around the feeds message, but may contain more information in the future.

Format:
{
    "capabilities": {
        <feeds message>                   
    }
}
Example:
{
    "capabilities" {
        "feeds": [
            "Location",
            "Acceleration"
        ]
    }
}

Feeds:

The feeds message is sent as part of the capabilities message and contains an array of the services that the connected devices provides. Example services are Location and Acceleration.

Format:
{
    "feeds": [
        <feed name 1>,
        <feed name 2>
    ]
}
Example:
{
    "feeds": [
        Location,
        Acceleration
    ]
}

Feed Request:

The feed request message is sent to a connector from applications or devices that are interested in that connector. The capabilities message that is privately sent to them by the connector lets them know what kind of feeds are available. In addition to which feed to request, the type field must be given. The params field is optional. If no parameters are given, the connector will respond with a single feed response message for the desired feed. Possible parameters are frequency, which determines the interval frequency for the connector to send feed responses, and status which may be set to off to tell the connector to stop sending feed responses for that feed.

Format:
{
    "type": <type>,
    "feed": <feed name>,
    "params": {
        <param 1>: <value 1>,
        <param 2>: <value 2>
    }
}
Example:
{
    "type": "get",
    "feed": "Location",
    "params": {
        "frequency": 60  #seconds
    }
}

Feed Response:

The feed response message is send from the connector to a device or application that has sent a feed request to it. It is sent on an interval at the frequency that is given in the feed request or just once if no frequency is given. It contains the name of the feed that is being send and a feed object containing key:value pairs of data.

Format:
{
    "name": <feed name>,
    "feed": {
        <key 1>: <value 1>,
        <key 2>: <value 2>
    }
}
Example:
{
    "name": "Location",
    "feed": {
        "Latitude": "-40.4545",
        "Longitude": "72.482899"
    }
}