Getting Started Guide

© 2012 Carnegie Mellon University

What is Sensor Andrew?

• Infrastructure to help connect the virtual and physical world• Access, store, control, describe and search sensor data while

maintaining security and privacy• Internet-scale performance and Extensibility

Controllers

Sensors

Legacy Data

Analytics

Visualization

Access

Sensor Andrew Architecture

Sensor

Actuator

SOX Agent

Data HandlerAgent

Sensor Andrew Web Portal

Registration Node

xxx_dataxxx_meta

SOX Agent

yyy_datayyy_meta

Historical Data

Publish

Subscribe

RegisterEvent Node: UUID_data@server/namespace

JID:User-ID@server

Tutorial Overview

1. Building SOX Tools– Compile the Sensor Over XMPP (SOX) library locally which will include a set of command line utilities

for interfacing with Sensor Andrew

2. Registering a Transducer– Either using the Sensor Andrew Portal or with bare command line utilities you can create an event

node that represents a transducer

3. Publishing a Sensor Value– Run a simple agent application that publishes a value to a sensor

4. Subscribing to a Sensor Feed– Run a simple agent application that subscribes to an event node

5. Access Control– Update the access control to your event node

Sensor Andrew TerminologySensor A device that measures a physical quantity.

Actuator A device for moving or controlling a mechanism or system.

Device A grouping of transducers, typically with a single interface (adapter). For example, a sensor node would be a device that could have multiple transducers (light, temperature, humidity etc).

Transducer A device that is a Sensor or Actuator or both. Transducers can also be virtualized, in the sense that they may not necessarily refer to the physical device that is directly measuring or controlling a phenomena, but rather to a software agent that serves as an intermediary.

JID A username used to authenticate with the XMPP server

Event Node An XMPP PubSub entity with a unique address used to represent a device. Event nodes are created by users or agents (JIDs). Each node consists of a UUID_data or UUID_meta. The _data postfix denotes that the event not should be used for data (frequent changes) while _meta is used to represent changes in the meta description of a node (infrequent).

Subscriber An entity that is allowed to subscribe to a node

Publisher An entity that is allowed to publish items to a node and that is automatically subscribed to the node.

Adapter Software that converts native transducer values into XMPP messages and vice-versa.

Agent An XMPP client (application) that consumes or produces data that is not an adapter. For example a piece of software that collects temperature and humidity data to compute dew-point.

Owner An entity that created a node and is automatically a publisher and subscriber.

Building SOX Tools (1-2)

1. Checkout the source

2. Build Libstrophe– libstrophe requires the following:

• OpenSSL (libssl) • libresolv (usually standard) • cURL (libcurl, needs development files curl-devel)

– Typical Package Names: • libcurl4-openssl-dev • check • libssl-dev • libexpat1-dev

# svn checkout svn://sensor.andrew.cmu.edu:/srv/svn/repos/sensor-andrew/sox

# cd sox/libs/libstrophe # ./bootstrap.sh # ./configure # make

Building SOX Tools (2-2)

3. Compile SOX Library

4. Compile Command Line Tools (in bin directory)

5. Simple Test

# cd sox/libs/libc_strophe # make

# cd sox/tools/cmd-line/CLI_strophe# make

# cd bin# ./sox_authenticate Username missing ./sox_authenticate" Command line utility to authenticate a JID Usage: ./sox_authenticate <-u username> <-p password> [-verbose] Usage: ./sox_authenticate -help

-u username = JID to authenticate (give the full JID, i.e. user@domain) -p password = JID user password -help = print this usage and exit -verbose = print info

# ./sox_authenticate -u guest@sensor.andrew.cmu.edu -p guest JID authenticated successfully!

Registering a Transducer

• Option 1: Sensor Andrew Web Portal– Registering a node with the Sensor Andrew web portal will automatically add

the node to a central data manager that will store data an allow for online visualization.

• Option 2: Command Line– It is also possible to create and use event nodes that are not managed by the

web infrastructure. These nodes can always be added later to the web interface for logging, visualization and sharing.

Registering a Transducer (Web 1-5)

• http://sensor.andrew.cmu.edu• Login with you Sensor Andrew JID

– Note, you need to put in the full JID with @sensor.andrew.cmu.edu

Registering a Transducer (Web 2-5)

Select “Register”

Register a Transducer (Web 3-5)

Select “TestNode”

Select “Yes” for Create Agents. This will automatically generate two test accounts that you can use.

Click “Next”

Register a Transducer (Web 4-5)

Select a Transducer to add to you device (In this case “Temperature”)

The Transducer(s) will appear here

Click “Save” when you are done

Register a Transducer (Web 5-5)This is your new event node!

This is the ID for data logging. You can pass this to the “sox_publish_data” tool in the next section

After publishing, you can view data here

Create a Transducer (CLT)1. Create an event node (SKIP this page if you used the Web Portal)

– Typically, an event node is created by the web portal data handler and is based on a UUID– It is possible to make your own event node without the web interface– The event node name can be any unique string. For testing purposes, its best to append your user name to it so as

to avoid naming conflicts.

2. Double Check that it was created

# cd sox/tools/cmd-line/CLI_strophe/bin# sox_node_create –event USER_test_event_node_data –u USER@sensor.andrew.cmu.edu –p PASSWORDNode created/configured successfully!

# ./sox_acl_affiliations_query -event USER_test_event_data -u USER@sensor.andrew.cmu.edu -p PASSWORDJID AffiliationUSER@sensor.andrew.cmu.edu owner#

Subscribing to an Event Node1. Subscribe to an event node

– In order for a JID to receive messages published to an event node, it must first subscribe. This subscription is then remembered by the server until the JID explicitly issues an unsubscribe command.

– Lets subscribe to the event node we just created…

2. Double Check that it was added to your subscription list– Note, SubID is a unique descriptor for each subscription

# sox_subscribe –event USER_test_event_node_data –u USER@sensor.andrew.cmu.edu –p PASSWORDSubscription successful!#

# sox_subscriptions_query –u USER@sensor.andrew.cmu.edu –p PASSWORDNode Status

SubIDUSER_test_node_data subscribed 5494064A10C8…#

Publishing a Sensor Value1. Start a subscription listener

– In order to see data once it is published, you can login with the sox_subscribe_listener

2. Publish a value to the event node– Open a new terminal window to run the publisher, so you can see the output on the subscriber listener– We will now publish a value from the command line to your new event node– The “id” parameter is used to link a transducer with an entry in the domain data handler (Registry ID)– If you used the Web Portal, the “Data Event Node” and “Registry ID” should come from the device page

– Each time you publish a message, you should see it appear in the subscribe listener– You can also publish a few messages and look on the Sensor Andrew Portal for data if you registered the device

# sox_publish_data –event USER_test_event_node_data –name “temperature” –value 26 –rawvalue 26 –u USER@sensor.andrew.cmu.edu –p PASSWORDPublication successful!#

# sox_subscribe_listener–u USER@sensor.andrew.cmu.edu –p PASSWORD

…

Modifying Access Control Properties

• Coming Soon…

SOX Command Line Toolssox_authenticate Checks to see if a JID can authenticate with the serversox_password_change Changes a user or agent’s password

sox_acl_affilation_query Lists the access control settings for an event node sox_acl_node_configure Sets the access control settings for an event nodesox_acl_publisher_add Provides another JID publisher access to an event nodesox_acl_publisher_remove Removes another JID’s publisher access to an event node

sox_node_create Creates an event nodesox_node_delete Deletes an event nodesox_node_register Sends a registration message about a new event node to the system’s creation event node. This is used to register a device with a data handler.

sox_publish_data Publishes transducer data to an event nodesox_publish_meta Publishes updated meta data to an event node.

sox_subscribe Subscribe a JID to an event nodesox_unsubscribe Unsubscribe a JID from an event nodesox_subscriptions_query List an event node’s subscriptionssox_subscribe_listener Print out any messages for a particular JID

Getting More Information

• XMPP XEPs– http://xmpp.org/xmpp-protocols/xmpp-extensions/

• XMPP PubSub (XEP-0060)– http://xmpp.org/extensions/xep-0060.html

• SOX XEP– http://sensor.andrew.cmu.edu/xep/sox-xep.html

• Sensor Andrew Wiki– http://sensor.andrew.cmu.edu:9000/wiki/xep