TKT-2301 Exercise API

Last updated 28.7.2010

TKT-2301 Exercise API ................................................................................................................................... 1

Installation application ................................................................................................................................. 2

Wireless sensor network exercise message types ........................................................................................ 5

XML interface .............................................................................................................................................. 10

RSS ............................................................................................................................................................... 11

WSNgadget (XML Demo) ............................................................................................................................ 12

C++ WSNExerciseAPI ................................................................................................................................... 14

Installation application

Login

Point your web browser to http://oliivitikli.cs.tut.fi/current/installation

Login with your group number and student number.

My nodes My nodes page shows information about nodes which are assigned to your group. It should look

something like this.

My nodes on map Show all of your groups nodes on map.

All nodes on map Show all nodes in sensor network, download map dumps, show maps with location grids (Grid size is roughly 20m*20m)

Group Show your group members and input your mobile phone number to be used in C++ exercise.

Logout Logout.

Last message from node Time when gateway server has received latest message from this node.

Feed visibility

Changes the visibility of a node in XML and RSS feeds. Hide if not needed.

Battery voltage (node) Latest battery voltage measurement from node itself.

Battery voltage (multimeter) Input your battery voltage measurement results here.

Location Possible values: Mobile node, Show on map, - Show on map: Node has fixed location. Follow link to see node on map.

Description Textual description about the node.

Node assigned to group Time when your group has received this node.

Node returned Time when your group has returned this node.

Battery voltage updated Follow link to see history of battery measurement values you have inputted during course.

Update node location Select the node which location you want to update and choose Set new location

Please notice the non-Finnish date format YYYY-MM-DD HH:MM:SS

Group Group page shows your group members. Here you can input your mobile phone number which is used in

C++ exercise.

Wireless sensor network exercise message types

Overview This document describes different message types available through wireless sensor network exercise

interfaces.

Message Every message consists of following attributes: node ID, message type, message data and timestamp

when message was received by server.

Message containing measurement data may also contains delay attribute. Delay is the time difference in

milliseconds between node sending the message and server receiving it. If delay information is not

available, delay value is -1.

Table 1 Message attributes

Attribute Format Example Notes

Type See table below

Data See table below

Timestamp YYYY-MM-DD HH:MM:SS 2008-07-09 13:02:57

Server time when received message

Delay Integer value in milliseconds 7562 Time difference in milliseconds between node sending the message and server receiving it. Negative value means that the delay value couldn’t be calculated or it didn’t exist.

Table 2 Message types and data.

Type (data) Data range Resolution Example data Unit Notes

TEMPERATURE (t1) -55 – 125 0.1 24.7 Celsius degrees

MULTIPOINT_TEMPERATURE (t1,t2,…,t7)

-55 – 125 0.5 0:24.5, 1:25.0 Celsius degrees *)

PHOTO_DIODE (p1) 0 - ~2700 1 405 Luxes

HUMIDITY (h1) 0 - 100 0.01 34.65 Percent value of relative humidity

ACCELERATION (x, y, z, pitch, roll)

x, y, z: -3072 - 3071 pitch, roll: 0-359

1 299, 49, 916, 3, 18 x,y,z: mg pitch,roll: degrees

*)

BATTERY_VOLTAGE (v1) 3.0 – 4.55 0.01 3.25 Volt

NEIGHBORS (Node ID:RSSI, …)

Node ID: integer RSSI: 0-3

1 4111:3,4009:1 Node ID integer value, RSSI integer value

*)

ROUTE integer 1 4035,4111,8 Node ID integer value *)

MOTION 1 1 1 Message always contains data value 1

CARBON_DIOXIDE 0 - ~2700 1 444 ppm

SOIL_MOISTURE 0-100 0.001 28.102 Percent value of relative soil moisture

ACTIVITY_MONITOR Alarms: 0-3600, Counter: 0-65536

1 329, 3058 Alarms per hour, Alarm counter value

SOUND_PRESSURE 65-100 0.0001 71.6829 Decibels

BUTTON_PRESS 1,2 - 2 ID(s) of pressed button(s)

*) Each separate data value has same data range and resolution.

Message types

TEMPERATURE

This message type contains measurement data from temperature sensor. Data is presented in Celsius

degrees. Note that only pocket nodes use TEMPERATURE packets in this course implementation. All

fixed nodes use MULTIPOINT_TEMPERATURE instead.

Example data: 24.5

MULTIPOINT_TEMPERATURE

This message type contains measurement data from multiple temperature sensors. Data is presented in

Celsius degrees.

Message contains data in temperature sensor number, temperature value pairs. (sensor number : value,

sensor number : value, …)

Minimum amount of temperature sensors is 1 and maximum amount is 8. Data value with sensor

number zero is from the on-board sensor and rest sensor numbers (1 through 7) are from external

temperature sensors.

Example data: 0:24.5, 1:25.0, 3:26.0, 5:21.5

PHOTO_DIODE

This message type contains measurement data from photodiode. Data is presented in luxes.

Example data: 510

HUMIDITY

This message type contains measurement data (relative humidity) from humidity sensor. Data is

presented in percents.

Example data: 34.65

ACCELERATION

This message type contains measurement data from acceleration sensor. Acceleration sensor measures

following data: acceleration in x, y and z-components, pitch and roll. Acceleration is presented in mg,

where g refers to the acceleration of gravitation on earth. Pitch means accelerometers up/down tilt and

roll means accelerometers left/right tilt. Pitch and roll are presented in degrees.

Message data order: acceleration in x, y and z-components, pitch and roll

Example data: 299, 49, 916, 3, 18

BATTERY_VOLTAGE

This message type contains diagnostics data (battery voltage) from node itself. Data is presented in

volts.

Example data: 3.26

NEIGHBORS

This message type contains information about neighbor nodes. Node reports IDs of the nodes it detects

around itself. In other words, node IDs in this message indicates neighbor nodes that sender of this

message has detected. Node also reports the RSSI (Received Signal Strength Indication) values. RSSI

value is presented in four different levels (0-3) 3 meaning strong signal level and 0 meaning weak signal

level.

Message contains data in node ID, RSSI pairs. (Node ID:RSSI, Node ID:RSSI, …)

Example data: 304:1, 8:0, 4111:2

ROUTE

This message type contains information about the current route from node to the gateway server

through the sensor network. Every node (excluding the sender node itself) that handles the message

adds its own ID into the message.

In example below data message is sent by node 4111 and is propagated through nodes 4129, 4009 and

304. In other words, data contains node IDs in that order which was the order when message travelled

through the sensor network (from sender node to node 4129, next from 4129 to 4009 and so on).

Minimum amount of node IDs in this message is 1 and maximum amount is 6.

Example Data: 4129, 4009, 304

MOTION

This message type is sent when node has some kind of motion sensor and motion is detected. Message

data always contains data value 1.

Example Data: 1

CARBON_DIOXIDE

This message type contains carbon dioxide measurement value from carbon dioxide sensor. Data is

presented is ppm (parts per million).

Example Data: 456

SOIL_MOISTURE

This message type contains measurement data (relative soil moisture) from soil moisture sensor. Data is

presented in percents.

Example data: 28.102

ACTIVITY_MONITOR

This message type is sent when node has some kind of motion sensor and activity monitor is installed

into node. Message data contains two values: Alarms per hour and alarm counter value.

Activity monitor reports the estimated amount of alarms per hour. The estimation is based on the

amount of alarms detected during the last measurement interval. Activity monitor also reports the total

amount of alarms detected since the node was started or counter overflowed.

Example data: 392, 3058

SOUND_PRESSURE

This message type is sent when node has sound pressure level sensor (SPL). Data is presented in

decibels. Note that values below 68 are not correct sound pressure levels due sensitivity of the sensor.

Example data: 74.1122

BUTTON_PRESS

This message is sent when node’s buttons are pressed. Used only for mobile nodes in this course

implementation. Data contains IDs of the buttons that were pressed (mobile nodes have two buttons, so

values 1 and 2 are possible)

Example data: 1, 2

XML interface

Overview

This document describes the sensor network exercise XML interface. XML interface is automatically

generated XML file containing sensor network data from last few minutes.

XML interface URL:

http://oliivitikli.cs.tut.fi/current/generate/wsn.xml

XML structure

Messages are written between <messages></messages> -tags. Every message is surrounded with

<message></message> -tags.

Message contains information about the node ID of the node which sent the message, timestamp when

the message was received by gateway server, delay between node sending the message and gateway

server receiving it, message type information and message data.

How Node ID, delay, type and time are stored in XML is self-explanatory (see example). Delay is

presented in milliseconds, timestamp is presented in following format: YYYY-MM-DD HH:MM:SS

Data is stored between <data></data> -tags. Data is separated at every colon and comma. Every

individual value is stored between <value></value>-tags. For example NEIGHBORS message with data

304:0, 4111:2 becomes:

<data>

<value>304</value>

<value>0</value>

<value>4111</value>

<value>2</value>

</data>

XML example

<?xml version="1.0" encoding="ISO-8859-1"?>

<messages>

<message>

<nodeid>4111</nodeid>

<time>2008-06-24 11:44:06</time>

<delay>-1</delay>

<type>NEIGHBORS</type>

<data>

<value>304</value>

<value>0</value>

</data>

</message>

<message>

<nodeid>4111</nodeid>

<time>2008-06-24 11:44:12</time>

<delay>-1</delay>

<type>ACCELERATION</type>

<data>

<value>150</value>

<value>106</value>

<value>-1057</value>

<value>174</value>

<value>171</value>

</data>

</message>

</messages>

RSS Latest sensor network data is also available as RSS feed. Data inside RSS feed has pre-formatted

messages from every node in network. You can view RSS feed in multiple ways. Simplest way is to point

your web browser to http://oliivitikli.cs.tut.fi/current/generate/wsnrss-0.92.xml

You can filter the RSS feed by giving parameters, for example, receiving BATTERY_VOLTAGE messages

from node 499:

http://oliivitikli.cs.tut.fi/current/generate/wsnrss-0.92.xml?nodeid=499&msgtype=BATTERY_VOLTAGE

You can also use any other RSS feed reader. For Microsoft Windows there is, for example, SharpReader.

For Linux you can try Liferea or Akregator.

WSNgadget (XML Demo) WSNgadget is gadget designed to be used in Microsoft Windows Vista Sidebar. It’s also possible to

install the Vista Sidebar in Windows XP; however Service Pack 3 and third-party software is needed.

More info can be found using Google. Search for “Windows Vista RTM Sidebar for XP”. Keep in mind

that using vista sidebar in your Windows XP machine is not official feature and you do that at your own

risk!

Installing gadget should be pretty straightforward: point your web browser to

http://oliivitikli.cs.tut.fi/current/WSNgadget.gadget

Windows will display following dialog:

Clicking install button will install the gadget. Installed gadget should appear into the sidebar, if it doesn’t

choose Add gadgets (right-clicking on the sidebar or choosing the ‘+’ symbol on the sidebar).

Installed gadget should look something like this:

You need to change the options, so that the gadget knows which data to display:

(This is just an example, actually node 333 doesn’t exist in this network)

C++ WSNExerciseAPI

Overview WSNExerciseAPI is wireless sensor network interface intended to be used in exercises on course TKT-

2300. Interface has methods to receive real time data from wireless sensor network. This document

describes interface from user’s point of view.

Constructor

WSNExerciseAPI();

No parameters for constructor. However the constructor will terminate, if the locations.csv file is

missing. You can download the locations.csv file from

http://oliivitikli.cs.tut.fi/current/locationquery/locations.csv

or more easily by typing “make updatelocations” in the folder you extracted the WSNExerciseAPI.

DataPacket struct struct DataPacket { int nodeid; std::string formattedTime; std::string type; std::vector< double > data; int unixtime; int delay; };

int nodeid;

This integer contains the node ID of the node which sent the last message.

std::string formattedTime;

This string contains latest message reception time as preformatted text. (Time has following format:

YYYY-MM-DD HH:MM:SS)

std::string type;

This string contains the type of the latest message. See message types for further details about the

messages.

std::vector< double > data;

This vector contains the data of the latest message as double values. ( For example NEIGHBORS message

containing data 304:1,8:0,4111:2 will be cut at every comma and colon and pushed into vector as

separated values. Resulting example vector is [304, 1, 8, 0, 4111, 2]).

int unixtime;

This integer contains latest message reception time in seconds from the beginning of the 1970’s.

int delay;

This integer contains the time delay between node sending the message and server receiving the

message. Delay is presented in milliseconds. Only packets with types TEMPERATURE, HUMIDITY,

PHOTO_DIODE, CARBON_DIOXIDE, ACCELERATION, SOIL_MOISTURE and SOUND_PRESSURE contain

delay information. Negative value means that the delay is invalid or it doesn’t exist.

Public methods

DataPacket waitForData();

This method waits for data from sensor network and blocks until data is available. Method returns

DataPacket struct which contains the data of the latest message.

std::string getFloor( int node );

This method returns floor of the requested node. Floor name refers to maps available at course website.

Empty string means that requested information was not found.

Parameter: integer node ID of the node whose location you are interested in.

std::pair< double, double > getXY( int node );

This method returns coordinate (X, Y) -pair of requested node location. X and Y coordinates are

presented in meters from upper left corner of the map indicated by getFloor method. Negative

coordinate values mean that there was no information available.

Parameter: integer node ID of the node whose location you are interested in.

void sendEmail( std::string address, std::string subject, std::string message );

This method sends e-mail messages. You can use this to send warnings, etc. Sending e-mail messages is

possible only to your official tut.fi domain e-mail address.

Parameters:

address: string containing valid e-mail address.

subject: string containing e-mail message subject.

message: string containing message body.

Notice that address, subject or message can’t contain control characters or extended ascii (characters

between 0x0 and 0x1F or greater than 0x7F). Sending message with illegal characters will not go

through. Also notice that method has limiter to prevent spamming (10 messages / minute or so). Excess

of this limit will close the connection to the server.

void sendSMS( std::string number, std::string message );

This method sends SMS messages. You can use this to send warnings, etc. You can only send SMS to the

numbers inputted using the Installation web application.

Parameters:

number: string containing target mobile phone number (use following format: 0401234567).

message: string containing message body (160 characters max).

Notice that sent messages are logged and sending interval is limited (10 messages / minute or so).

Excess of this limit will close the connection to the server. Also notice that message can’t contain control

characters or extended ascii (characters between 0x0 and 0x1F or greater than 0x7F). Sending message

with illegal characters will not go through.

void sendCommand( int nodeid, int command );

This method sends predefined commands to nodes.

Parameters:

nodeid: This must be a mobile node id, meaning that only ID’s 2500-2599 are accepted. Any

other value gives an exception.

command: Available commands are NODE_COMMAND_LED_GREEN_ON,

NODE_COMMAND_LED_GREEN_OFF, NODE_COMMAND_LED_RED_ON,

NODE_COMMAND_LED_RED_OFF, which are used to control mobile nodes’ leds, and

NODE_COMMAND_REBOOT that boots the node.

Above commands are declared as constants in the header file. All other values for parameter

“command” are illegal. Trying to use sendCommand with illegal value for parameter “command” will not

go through and it will be ignored. Also notice that method has limiter to prevent spamming (10

messages / minute or so). Excess of this limit will close the connection to the server.