Connector Spec

Connector Specification

Overview

BUGSwarm-Connector (Connector) is a BUG application designed to showcase the BUGswarm middleware system. The connector uses a combination of ReST web services and XMPP messages to publish information, respond to peer requests, and expose device and status information online.

Connector is designed to be usable by any general purpose Swarm peer but is optimized for the Bug Labs Swarm Management Application (Manager). This web app communicates with connector via XMPP. Any data that is registered or sent to Swarm server by default is meant for consumption by the Manager.

Application

Dependencies

Connector relies on the following libraries and frameworks:

• OSGi R4 : For BUG services, device access, and web configuration interface.
• Jackson : For JSON handling
• Smack/Smackx : For XMPP support
• Json.simple : for JSON handling (soon to be removed)
• Touge : for ReST client

Architecture

Connector deploys as a single OSGi bundle. It relies on an OSGi framework to call start() on its Activator class. It is an event-based application that listens for events from:

• The Configuration Admin Service : for local configuration changes via the web user interface.
• The OSGi Service Registry : for changes to services and hardware state.
• The Swarm XMPP server: for messages from peers.

Additionally, if active, Connector polls Swarm server for the set of member swarms via the ReST interface.

Connector Events

Connector Starts

Connector will register the identity configuration web page with the local web server and load the stored identity configuration. If the identity information is missing or invalid the connector will then go into a passive mode.

Connector Identity Configuration Changes

A basic web interface will be present via the BUG web server that will allow a user to set the identity information. When the 'ACTIVATE' button on the webform is triggered the Connector bundle will receive an event. Once Connector receives valid identity information, it will initialize a connection with the Swarm Server.

Connector Connects to Swarm Server

The connector initializes itself with the Swarm server in the following steps:

1. Determines if a resource id has already been set. Resource IDs are server generated. If a resource id is not available, a server request is made to generate one. Once generated the id is stored persistently so next the next time Connector starts the resource id will be reused.
2. Create XMPP session with Swarm server.
3. Retrieve list of all member swarms via rest call, see Connector Joins Swarm section.
4. Register with OSGi service registry to receive events.

If any of these steps fail, the Connector returns to a passive state until a new identity-change event occurs.

Connector Disconnects from Swarm Server

When the Connector shuts down the following actions are taken:

1. Cancel any frequency-enabled Feed requests.
2. Unregister for OSGi events.
3. Send anti presence to member swarms via XMPP.
4. Close XMPP session with Swarm server.

Connector Joins a Swarm

1. Send XMPP presence to swarm and register to receive presence, public and private message events.
2. Send Capabilities feed as public message to Swarm.

Connector Leaves Swarm

1. Send XMPP anti presence to Swarm, notifying peers of leaving.
2. Cancel any active Frequency-enabled Feed requests associated with the Swarm.

Local BUG Feed Updated

New Feed created on BUG

Feed destroyed on BUG

New Peer Joins Swarm

1. Connector created private chat session with new peer.
2. Connector sends Capabilities feed to new peer.
3. Private chat session remains open until peer or connector leave Swarm.

Peer Leaves Swarm

Peer Requests Feed

Example of a feed request for Location feed.

{
    "type": "get",
    "feed": "Location"
}

Example that causes Connector to send the Location feed every 20 seconds.

{
    "type": "get",
    "feed": "Location",
    "params": {
        "frequency": 20
    }
}

Message Types

Capabilities Message

This message is intended for the Management UI, and is only send from Connector peers running on BUG devices. It is a top-level description of the BUG device's current state.

{
    "capabilities": {
        <feed message>,
        <modules message>
    }
}

An example of the Capabilities feed:

{
    "capabilities": {
        "feeds": [
            "VonHippel"
        ],
        "modules": {
            "slot2": "vonhippel"
        }
    }
}

Feeds Message

This message lists the names of available feeds on a given device.

{
	"feeds": [
	            "Feed x",
	            "Feed y",
	            ...
	        ]
}

Modules Message

This message summaries the currently attached BUG modules on the device.

{
    "modules": {
        "<slotid>": "<module name>"
    }
}

Feed request message

A feed request is a request from another peer on a member swarm for a local device feed. The peer discovers the feed names based on the Capabilities message. The feed request message always originates from another peer.

{
	"type": "get",
	"feed": "<feed name>"
}

Additionally peers can add parameters to the request. Connector-specific parameters that are handled:

• frequency: specify that the request should be executed at an interval (unit is seconds) until the peer leaves the swarm or explicitly stopped.
• status: when the value is "off", the request means that any previous frequency-based feed requests should be cancelled for the parameters passed.

A feed with parameters:

{
    "type": "get",
    "feed": "<feed name>",
    "parameters": {
        "<name>": <value>,
        ...
    }
}

A feed request with a frequency of 1 minute:

{
    'type': 'get',
    'feed': 'Location',
    'params': {
        'frequency': 60,        
    }
}

A feed request to specify a previous ongoing request should be cancelled:

{
    'type': 'get',
    'feed': 'Location',
    'params': {
        'status': 'off',        
    }
}

Feed response message

Terms

• Management UI : The web application used to manage and view BUG devices on a Swarm server. Serves as the primary internal application for BUGswarm.
• BUG : The Bug Labs' BUG device.
• Feed : A named set of key/value pairs. Keys are Strings and values may be various serializable types.
• XMPP : A messaging oriented middleware used in BUGswarm.