Return to sympathy_doc CVS log

Jump to this file's LXR Page

Up to [CENS] / emstar / devel / sympathy_devel

Added instrumentation for mintRoute. This involved:
   - separating routing-specific code out from sympathy on the sink side
   - getting MintRoute to work (and writing wrapper code for it)
   - instrumenting MintRoute code on the mote side.

Added sink-side wrapper code for surge.

 Changed interface for reporting metrics - now we use a Smetrics_t struct
         instead of just randombly packing data into the packet.

I. Using Sympathy

Code Assumptions (VERY IMPORTANT)
----------------
If the TOSH_DATA_LENGTH field is not big enough, then the neighbor
list does not get sent by the nodes (i.e. for 10 neighbors, usually 
you need 4B * avg_num_neighbors, + 8 (for route+pkt-hdr) for the
data field in the routing packet.
We decided not to just send a partial neighbor list because this is
more misleading. It is better to just receive no neighbors.

Code Location
-------------
1) TinyOS code is located in: 
#define STOS_BASE tos-contrib/sympathy/tos
	Main API file is: STOS_BASE/lib/Sympathy.h

2) Emstar code (which runs on the sympathy-sink) is located in: 
#define SEMSTAR_BASE devel/sympathy_devel
	Main API file is: SEMSTAR_BASE/include/sympathy_dev.h
	Main header file is: SEMSTAR_BASE/include/sympathy.h

Devices Sympathy exports
--------------------------------------
Device files are generally located in: 

/* Defined in tos-contrib/sympathy/tos/lib/Sympathy.h */
#define SSTATUS_BASE  /dev/sympathy/.

If the network is run in simulation, then they will be
located in: /dev/sim/group<id>/node<SINK-ID>/sympathy.

1) Metrics device (SSTATUS_BASE/metrics)
Sympathy provides for each node:
 - neighbor list
 - route to sink
 - statistics on the node (#pkts node has routed, #sympathy
  packets it has transmitted, time it has been awake)
 - statistics on every instrumented component:
   * Sympathy specified statistics: #pkts node has tx, rx, 
  	had to re-tx
   * Component specific statistics (translated by a comonent
    on the sink - see below, and not understood by Sympathy).

2) No data (SSTATUS_BASE/no_data)
If the sink is not receiving any packets from a node, 
it will be reported here. Sympathy will provide its diagnosis
of the issue.

3) Insufficient data (SSTATUS_BASE/insuff_data)
If the sink is receiving some packets from a node, but just not enough,
it will be reported here. Sympathy will provide its diagnosis
of the issue.

4) summary device (SSTATUS_BASE/summary)
Will provide a summary of the status of all failures.

5) command device (SSTATUS_BASE/cmd)
Provides a command interface - at a shell a user can:
  - ping any node in the network: 
      > echo "ping=<node-id> > SSTATUS_BASE/cmd
  - change the metrics period that nodes are flooding metrics: 
      > echo "auto_period=<period-in-seconds> > SSTATUS_BASE/cmd

6) battery device (SSTATUS_BASE/battery)
Accepts updates on battery voltage status of nodes, and
prints the current snapshot of all nodes.

7) component communication device (<path-to-link-devices>/sympathy)
Handles communication between components on the sink and sympathy -
described more below.
     

Emview
------
To use emview with Sympathy, launch emview 
  > obj.i686-linux/emview/emview -G <group-id>
and you should see a visualization of many metrics that
Sympathy collects. Specifically you will see node's neighbor lists, 
routing tables, and their failure status (as diagnoed by Sympathy).

II. Adding new instrumentation to Sympathy

Communication  between sympathy and components on the sink
---------------------------------------------------------------
The SYMPATHY_STATS_DEVICE is a link device which handles several types of
communication between the sympathy-sink and other components on the sink.
The structure of the link_pkt_t.data field depends on the link_pkt_t.type field
(e.g. sympathy_events.c:update_node()), interface located in: sympathy_dev.h

1) Components send updates to sympathy (e.g. if they have received a packet, or
expect to receive more packets, and want sympathy to know about this), with
link_pkt_t.type == SSINK_UPDATE, and link_pkt_t.data points
to a sympathy_status_info_t.

2) When the sink wants a component to translate a generic_stats packet it
has received from a node - from binary to ascii 
link_pkt_t.type == SCOMP_STATS, and link_pkt_t.data points
to the component-specific binary provided by the node.
(See sympathy_print_status.c:status_receive())

3) When components translate a packet from binary to ascii - 
link_pkt_t.type == SCOMP_ASCII_STATS, and link_pkt_t.data points
to a buf_t.
(See sympathy_print_status.c:send_stats_pkt())

Instrumenting components on the nodes
------------------------------------
If a designer wants statistics to be sent about a specific component on
a node, they need to instrument this component by exposing an interface, and
storing information...

** Counters on components SHOULD NOT be cleared. Sympathy will handle
all counter roll-over (either due to reboot or roll-over).

Interfaces to Export on the Motes
---------------------------------
Text in parentheses following the line is approximation of code needed to
add in order to add the instrumentation.
The module must provide the following interfaces:

I. Mote code
A. SGetPacketMetrics - any time a packet is received/routed by routing layer
  - SgetPacketMetrics.receivedPacket(Saddr_t node, uint16_t strength); (1 line)
  - SgetPacketMetrics.routedPacket(Saddr_t node, uint16_t strength); (1 line)
  - SgetPacketMetrics.packetTxFailed(Saddr_t node); (4 line)
  	in SendMsg.sendDone() {	
	    if (msg->ack == 0 && msg->addr != TOS_BCAST_ADDR &&
	        msg->addr != TOS_UART_ADDR) {
	      	     signal SGetPacketMetrics.packetTxFailed(msg->addr);
	    }
B. RadioDebugNBI - to provide neighbor list
    - command uint8_t RadioDebugNBI.getNeighborList (uint8_t *buf)  (16 lines)
C. GetNextHop - to get routing table info
    - command uint8_t GetNextHop.getNexthop(Snext_hop_t *next_hop, 
    		uint8_t max_sinks){		(10 lines)
D. NodeI - interface so Sympathy can send/receive packets from routing
	layer. (54 lines)

F. Adding Sympathy to highest level wiring file:
  - Add SympathyC  (1 line)
  - Wire interfaces for SympathyC ( ?? lines)
  	- Provide Sympathy with send/rx interfaces

II. Sink code
A. Adding interface for sink to get neighbors from routing layer
B. Add interface so Sympathy can send out control packets

Translating "Generic" stats (example: sympathy_print_stats.c)
---------------------------
Generic stats are component-specific statistics transmitted to the sink
(so Sympathy has no knowledge of their format). Once they arrive at the sink,
a component on the sink must translate these statistics. So, Sympathy will
send these stats on SYMPATHY_STATS_DEVICE, with a link_pkt_t.type = SCOMP_STATS.

Once the component gets it (example in sympathy_print_stats.c - it prints 
stats for the generic stats coming from mDTN), it checks the type of the 
link_pkt_t struct for the specific component that this struct is for (i.e.
SCOMP_STATS1-4), and if it is destined for that component, the component
looks at the stats, translates them into ascii, and sends a packet out
with dst.id=LINK_BROADCAST, sypmathy_update_t.type = SCOMP_ASCII_STATS,
and src=src of node that indicated in the packet sent by sympathy_sink.

III. Checking if Sympathy is working

0) Sympathy contains self-checking mechanisms, so the sink will
complain if it is not getting sympathy metrics from certain nodes.

1) Run your network in simulation, and run
emview to get a visualization. 
(to run emview: run obj.i686-linux/emview/emview -G <group-id>
Check the sympathy metrics provided in the metrics device and
make sure they match what you see in emview. 

2) Run with motes, and launch emview to get a visualization.  Check:
   * all your motes appear in sympathy metrics file, and in emview
   * turn a mote off, and make sure this failure is reported in the no_data
      device file.