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.
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.
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.
{ "capabilities": { <feeds message> } }
{ "capabilities" { "feeds": [ "Location", "Acceleration" ] } }
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
.
{ "feeds": [ <feed name 1>, <feed name 2> ] }
{ "feeds": [ Location, Acceleration ] }
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.
{ "type": <type>, "feed": <feed name>, "params": { <param 1>: <value 1>, <param 2>: <value 2> } }
{ "type": "get", "feed": "Location", "params": { "frequency": 60 #seconds } }
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.
{ "name": <feed name>, "feed": { <key 1>: <value 1>, <key 2>: <value 2> } }
{ "name": "Location", "feed": { "Latitude": "-40.4545", "Longitude": "72.482899" } }