1. Getting Started Guide © 2012 Carnegie Mellon University

2. 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

3. Sensor Andrew Architecture Sensor Actuator SOX Agent Data Handler Agent Sensor Andrew Web Portal Registration Node xxx_data xxx_meta SOX Agent yyy_data yyy_meta Historical Data Publish Subscribe Register Event Node: UUID_data@server/namespace JID: User-ID@server

4. 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

5. Sensor Andrew Terminology SensorA device that measures a physical quantity. ActuatorA device for moving or controlling a mechanism or system. DeviceA 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). TransducerA 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. JIDA username used to authenticate with the XMPP server Event NodeAn 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). SubscriberAn entity that is allowed to subscribe to a node PublisherAn entity that is allowed to publish items to a node and that is automatically subscribed to the node. AdapterSoftware that converts native transducer values into XMPP messages and vice-versa. AgentAn 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. OwnerAn entity that created a node and is automatically a publisher and subscriber.

6. 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

7. Building SOX Tools (2-2) 3.Compile SOX Library 4.Compile Command Line Tools (in bin directory) 3.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 [-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!

8. 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.

9. 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

10. Registering a Transducer (Web 2-5) Select Register

11. 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

12. 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

13. 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

14. 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 PASSWORD Node created/configured successfully! #./sox_acl_affiliations_query -event USER_test_event_data -u USER@sensor.andrew.cmu.edu -p PASSWORD JIDAffiliation USER@sensor.andrew.cmu.eduowner #

15. Subscribing to an Event Node 1.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 PASSWORD Subscription successful! # # sox_subscriptions_query –u USER@sensor.andrew.cmu.edu –p PASSWORD NodeStatusSubID USER_test_node_datasubscribed5494064A10C8 … #

16. Publishing a Sensor Value 1.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 PASSWORD Publication successful! # # sox_subscribe_listener–u USER@sensor.andrew.cmu.edu –p PASSWORD …

17. Modifying Access Control Properties Coming Soon…

18. SOX Command Line Tools sox_authenticateChecks to see if a JID can authenticate with the server sox_password_changeChanges a user or agents password sox_acl_affilation_queryLists the access control settings for an event node sox_acl_node_configureSets the access control settings for an event node sox_acl_publisher_addProvides another JID publisher access to an event node sox_acl_publisher_removeRemoves another JIDs publisher access to an event node sox_node_createCreates an event node sox_node_deleteDeletes an event node sox_node_registerSends a registration message about a new event node to the systems creation event node. This is used to register a device with a data handler. sox_publish_dataPublishes transducer data to an event node sox_publish_metaPublishes updated meta data to an event node. sox_subscribeSubscribe a JID to an event node sox_unsubscribeUnsubscribe a JID from an event node sox_subscriptions_queryList an event nodes subscriptions sox_subscribe_listenerPrint out any messages for a particular JID

19. Getting More Information XMPP XEPs – http://xmpp.org/xmpp-protocols/xmpp-extensions/ http://xmpp.org/xmpp-protocols/xmpp-extensions/ XMPP PubSub (XEP-0060) – http://xmpp.org/extensions/xep-0060.html http://xmpp.org/extensions/xep-0060.html SOX XEP – http://sensor.andrew.cmu.edu/xep/sox-xep.html http://sensor.andrew.cmu.edu/xep/sox-xep.html Sensor Andrew Wiki – http://sensor.andrew.cmu.edu:9000/wiki/xep http://sensor.andrew.cmu.edu:9000/wiki/xep