1 I. Using Sympathy
2
3 Code Assumptions (VERY IMPORTANT)
4 ----------------
5 If the TOSH_DATA_LENGTH field is not big enough, then the neighbor
6 list does not get sent by the nodes (i.e. for 10 neighbors, usually
7 you need 4B * avg_num_neighbors, + 8 (for route+pkt-hdr) for the
8 data field in the routing packet.
9 We decided not to just send a partial neighbor list because this is
10 more misleading. It is better to just receive no neighbors.
11
12 Code Location
13 -------------
14 1) TinyOS code is located in:
15 #define STOS_BASE tos-contrib/sympathy/tos
16 Main API file is: STOS_BASE/lib/Sympathy.h
17
18 2) Emstar code (which runs on the sympathy-sink) is located in:
19 #define SEMSTAR_BASE devel/sympathy_devel
20 Main API file is: SEMSTAR_BASE/include/sympathy_dev.h
21 Main header file is: SEMSTAR_BASE/include/sympathy.h
22
23 Devices Sympathy exports
24 --------------------------------------
25 Device files are generally located in:
26
27 /* Defined in tos-contrib/sympathy/tos/lib/Sympathy.h */
28 #define SSTATUS_BASE /dev/sympathy/.
29
30 If the network is run in simulation, then they will be
31 located in: /dev/sim/group<id>/node<SINK-ID>/sympathy.
32
33 1) Metrics device (SSTATUS_BASE/metrics)
34 Sympathy provides for each node:
35 - neighbor list
36 - route to sink
37 - statistics on the node (#pkts node has routed, #sympathy
38 packets it has transmitted, time it has been awake)
39 - statistics on every instrumented component:
40 * Sympathy specified statistics: #pkts node has tx, rx,
41 had to re-tx
42 * Component specific statistics (translated by a comonent
43 on the sink - see below, and not understood by Sympathy).
44
45 2) No data (SSTATUS_BASE/no_data)
46 If the sink is not receiving any packets from a node,
47 it will be reported here. Sympathy will provide its diagnosis
48 of the issue.
49
50 3) Insufficient data (SSTATUS_BASE/insuff_data)
51 If the sink is receiving some packets from a node, but just not enough,
52 it will be reported here. Sympathy will provide its diagnosis
53 of the issue.
54
55 4) summary device (SSTATUS_BASE/summary)
56 Will provide a summary of the status of all failures.
57
58 5) command device (SSTATUS_BASE/cmd)
59 Provides a command interface - at a shell a user can:
60 - ping any node in the network:
61 > echo "ping=<node-id> > SSTATUS_BASE/cmd
62 - change the metrics period that nodes are flooding metrics:
63 > echo "auto_period=<period-in-seconds> > SSTATUS_BASE/cmd
64
65 6) battery device (SSTATUS_BASE/battery)
66 Accepts updates on battery voltage status of nodes, and
67 prints the current snapshot of all nodes.
68
69 7) component communication device (<path-to-link-devices>/sympathy)
70 Handles communication between components on the sink and sympathy -
71 described more below.
72
73
74 Emview
75 ------
76 To use emview with Sympathy, launch emview
77 > obj.i686-linux/emview/emview -G <group-id>
78 and you should see a visualization of many metrics that
79 Sympathy collects. Specifically you will see node's neighbor lists,
80 routing tables, and their failure status (as diagnoed by Sympathy).
81
82 II. Adding new instrumentation to Sympathy
83
84 Communication between sympathy and components on the sink
85 ---------------------------------------------------------------
86 The SYMPATHY_STATS_DEVICE is a link device which handles several types of
87 communication between the sympathy-sink and other components on the sink.
88 The structure of the link_pkt_t.data field depends on the link_pkt_t.type field
89 (e.g. sympathy_events.c:update_node()), interface located in: sympathy_dev.h
90
91 1) Components send updates to sympathy (e.g. if they have received a packet, or
92 expect to receive more packets, and want sympathy to know about this), with
93 link_pkt_t.type == SSINK_UPDATE, and link_pkt_t.data points
94 to a sympathy_status_info_t.
95
96 2) When the sink wants a component to translate a generic_stats packet it
97 has received from a node - from binary to ascii
98 link_pkt_t.type == SCOMP_STATS, and link_pkt_t.data points
99 to the component-specific binary provided by the node.
100 (See sympathy_print_status.c:status_receive())
101
102 3) When components translate a packet from binary to ascii -
103 link_pkt_t.type == SCOMP_ASCII_STATS, and link_pkt_t.data points
104 to a buf_t.
105 (See sympathy_print_status.c:send_stats_pkt())
106
107 Instrumenting components on the nodes
108 ------------------------------------
109 If a designer wants statistics to be sent about a specific component on
110 a node, they need to instrument this component by exposing an interface, and
111 storing information...
112
113 ** Counters on components SHOULD NOT be cleared. Sympathy will handle
114 all counter roll-over (either due to reboot or roll-over).
115
116 Interfaces to Export on the Motes
117 ---------------------------------
118 Text in parentheses following the line is approximation of code needed to
119 add in order to add the instrumentation.
120 The module must provide the following interfaces:
121
122 I. Mote code
123 A. SGetPacketMetrics - any time a packet is received/routed by routing layer
124 - SgetPacketMetrics.receivedPacket(Saddr_t node, uint16_t strength); (1 line)
125 - SgetPacketMetrics.routedPacket(Saddr_t node, uint16_t strength); (1 line)
126 - SgetPacketMetrics.packetTxFailed(Saddr_t node); (4 line)
127 in SendMsg.sendDone() {
128 if (msg->ack == 0 && msg->addr != TOS_BCAST_ADDR &&
129 msg->addr != TOS_UART_ADDR) {
130 signal SGetPacketMetrics.packetTxFailed(msg->addr);
131 }
132 B. RadioDebugNBI - to provide neighbor list
133 - command uint8_t RadioDebugNBI.getNeighborList (uint8_t *buf) (16 lines)
134 C. GetNextHop - to get routing table info
135 - command uint8_t GetNextHop.getNexthop(Snext_hop_t *next_hop,
136 uint8_t max_sinks){ (10 lines)
137 D. NodeI - interface so Sympathy can send/receive packets from routing
138 layer. (54 lines)
139
140 F. Adding Sympathy to highest level wiring file:
141 - Add SympathyC (1 line)
142 - Wire interfaces for SympathyC ( ?? lines)
143 - Provide Sympathy with send/rx interfaces
144
145 II. Sink code
146 A. Adding interface for sink to get neighbors from routing layer
147 B. Add interface so Sympathy can send out control packets
148
149 Translating "Generic" stats (example: sympathy_print_stats.c)
150 ---------------------------
151 Generic stats are component-specific statistics transmitted to the sink
152 (so Sympathy has no knowledge of their format). Once they arrive at the sink,
153 a component on the sink must translate these statistics. So, Sympathy will
154 send these stats on SYMPATHY_STATS_DEVICE, with a link_pkt_t.type = SCOMP_STATS.
155
156 Once the component gets it (example in sympathy_print_stats.c - it prints
157 stats for the generic stats coming from mDTN), it checks the type of the
158 link_pkt_t struct for the specific component that this struct is for (i.e.
159 SCOMP_STATS1-4), and if it is destined for that component, the component
160 looks at the stats, translates them into ascii, and sends a packet out
161 with dst.id=LINK_BROADCAST, sypmathy_update_t.type = SCOMP_ASCII_STATS,
162 and src=src of node that indicated in the packet sent by sympathy_sink.
163
164 III. Checking if Sympathy is working
165
166 0) Sympathy contains self-checking mechanisms, so the sink will
167 complain if it is not getting sympathy metrics from certain nodes.
168
169 1) Run your network in simulation, and run
170 emview to get a visualization.
171 (to run emview: run obj.i686-linux/emview/emview -G <group-id>
172 Check the sympathy metrics provided in the metrics device and
173 make sure they match what you see in emview.
174
175 2) Run with motes, and launch emview to get a visualization. Check:
176 * all your motes appear in sympathy metrics file, and in emview
177 * turn a mote off, and make sure this failure is reported in the no_data
178 device file.
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.