Tutorial

Installation

• Download and install TinyOS 1.x (>=1.1.19) from TinyOS
• Verify the installation of TinyOS by compling a sample application (e.g.,Blink)
• Download MicroToPSS archive and unpack it in the applications folder of your TinyOS installation.

 
cd <TOS>/apps
tar zxvf utopss-1.0.tar.gz
 

• This will create 'utopss' folder with the MicroToPSS middleware and 'utopssapp' an application template.
• To verify the installation, compile the sample application

 
cd <TOS>/apps/utopssapp
make pc
 

Sample Application using nesC API

Applications can make use of MicroToPSS in two ways: using the nesC or VM API. In this section we describe the nesC API.

The nesC interface, found in <UTOPSS>/PublishSubscribe.nc, is shown here.

 
interface PublishSubscribe {
        command result_t advertise(uint8_t id, Advertisment* a);
        command result_t unadvertise(uint8_t id, Advertisment* a);
        command result_t subscribe(uint8_t id, Subscription* s);
        command result_t unsubscribe(uint8_t id, Subscription* s);

        command result_t publish(uint8_t id, Publication* p);
        event result_t notify(uint8_t id, Publication* p);

        command result_t local_subscribe(uint8_t id, Subscription* s);
}
 

Application uses 'advertise' to tell MicroToPSS about the kind of data it is making available (i.e., data that it is going to send to MicroToPSS using 'publish'). This data is represented as a set of attribute-value pairs ('Publication').

 
struct avpair {
        uint8_t attrib;
        uint16_t value;
};
typedef struct avpair AVPair;

struct publication {
        uint8_t count; /* number of avpairs */
        uint8_t stopByte; /* last valid byte of the avpairs array */
        AVPair avpairs[MAX_AVPAIRS_PER_PUB];
};
typedef struct publication Publication;
  

'Advertisment' is a set of predicates.

 
struct predicate {
        AVPair avpair;
        uint8_t op; /* operator */
};
typedef struct predicate Predicate;

struct subscription {
        uint8_t count;
        Predicate preds[MAX_PREDS_PER_SUB];
};
typedef struct subscription Subscription;
typedef struct subscription Advertisment;
 

Notice that both subscriptions and advertisments have the same structure. However, they differ in the way they are used. Advertisements 'advertise' the data that is going to be 'publish'ed (i.e., every publications needs to satisfy the predicates in the corresponding advertisment). Subscriptons 'subscribe' to data. In other words, any publication that satisfies a subscripton will be delivered to the application using 'notify'. While 'subscriptions' retreive data regardless of where it is published in the network, 'local_subscriptions' retreive only data published locally by the node.

First step in creating a MicroToPSS client is to connect (wire) the client to MicroToPSS.

 
configuration utopssapp {
}
implementation {
        components Main, MicroToPSS, ClientM;
        Main.StdControl -> ClientM.StdControl;
        ClientM.broker -> MicroToPSS.PublishSubscribe;
}
 

Once the client is wired, it can make use of the MicroToPSS nesC interface. The interface requires each client to define a callback 'notify'. This needs to be defined even if the application is not subscribing to anything.

Here's an example of how to use subscriptions/advertisments/publications (ClientM.nc). In this example, the application sends PING data to itself.

  
        /* advertise PING data */
        Advertisment a;
        Publication p;

        a.count = 1;
        a.preds[0].avpair.attribute = TYPE;
        a.preds[0].avpair.value = PING;

        /* every client has a unique id; 6 in this case */
        call broker.advertise(6,&a);
        call broker.subscribe(6,&a); /* ads and subs have the same structure */

        p.count = 2
        p.avpairs[0].attrib = TYPE;
        p.avpairs[0].value = PING;
        p.avpairs[1].attrib = DOOR_STATUS;
        p.avpairs[1].value = DOOR_OPEN;

        call broker.publish(6,&p);    
 

The application will received the publication via the 'notify' callback.

 
event result_t broker.notify(uint8_t id, Publication *p) {

         /* got the publication */

        return SUCCESS;
}
 

While, in this case, the data path as setup by 'subscribe' and 'advertise/publish' is on a single device only, the operations could have been performed on different devices as well. Thus, MicroToPSS transfers data between clients in a way that is transparent to the application (i.e., application does not need to where to find the data, only what data it wants). This is one of the key benefits of data-centric networking.