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.

Terms

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

Application

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

1. For each attached member swarm with at least one other participant, send Feed Response message.

New Feed created on BUG

1. For each attached member swarm with at least one other participant, send Capabilities feed as public message.

Feed destroyed on BUG

1. For each attached member swarm with at least one other participant, send Capabilities feed as public message.
2. Remove any frequency-based feed requests.

New Peer Joins Swarm

1. Connector created private chat session with new peer.
2. Connector sends Capabilities feed to new peer as a private message.

Peer Leaves Swarm

1. Remove any frequency-based feed requests.

Peer Requests Feed

1. Parse feed message.
2. Load feed from local registry.
3. Serialize feed into JSON with Feed Response format.
4. Send feed via private message to requester.

BUG Module Attached or Removed

1. Connector receives OSGi event, waits 2 seconds during which all subsequent events are ignored.
2. Connector creates Capabilities feed.
3. Connector sends Capabilities feed to all member swarms.

Connector Message Types

The 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"
        }
    }
}

The Feeds Message

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

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

The Modules Message

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

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

The 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'     
    }
}

The Feed Response Message

This is the response sent by a connector for a request from another peer.

{ 'name': "" 'feed': { "": , ... } }

An example of a feed response from the device-stats plugin:

{
    "feed": {
        "users": "2 users",
        "wifi.status": "down",
        "battery.current": "0",
        "uptime": "08:01:23 up  8:01",
        "battery.temp": "-413",
        "storage.rootfs.used": "474172",
        "swap.available": "0",
        "wifi.signal": "0",
        "swap.used": "0",
        "wifi.packets.rx": "0",
        "ram.used": "176185344",
        "ram.available": "58769408",
        "wifi.noise": "0",
        "battery.status": "Full",
        "battery.present": "1",
        "battery.capacity": "100",
        "wifi.packets.tx": "0",
        "ram.total": "234954752",
        "swap.total": "0",
        "storage.rootfs.available": "1329628",
        "load": "0.05",
        "battery.voltage": "65531",
        "storage.rootfs.total": "1900332"
    },
    "name": "bugswarm-devicestats"
}

Java Package Source Information

com.buglabs.bug.swarm.connector

This is where the connector itself lives, and classes that it needs that don't fall within the packages below.

com.buglabs.bug.swarm.connector.osgi

Classes relating to the OSGi-facet of the connector. This includes the Activator which controls the lifecycle of the application, and OSGiHelper which gathers relevant OSGi-service references and events for the connector.

com.buglabs.bug.swarm.connector.ui

Classes relating to the web UI on BUG used to configure the user identity for swarm. This includes a servlet and ServiceTracker code to bind to the HTTPService.

com.buglabs.bug.swarm.connector.model

Model classes used internally in connector.

com.buglabs.bug.swarm.connector.xmpp

Classes relating to the XMPP API for swarm server. This includes a specialized Java client API that wraps a general XMPP client API.

com.buglabs.bug.swarm.connector.test

JUnit test classes, mock objects and support classes.