03 TinyOS Programming

TinyOS Developers Programming
Topics:
TinyOS Structures
Commands, Events, & Tasks
Configurations, Components, & Modules
Implementation
Application Example
How the pieces fit together
TOS Advanced Flows
TOS Messaging
TinyOS/nesC Programming (Parts 1 and 2)
San Jose / February 9-10, 2005
TinyOS Layers
Application
Configuration
TOS Scheduler (Main)
Legend
User
Application Interfaces
TOS
Application Specific
Components
Library
Components
Commands
HW
Events
TOS Component Interfaces
System Components
Hardware Presentation/Abstraction Layer
Mote Devices
Sensor Devices
2
Mote CPU
Processor
4 to 8 MIPs
8-bit RISC
Memory
4 KB SRAM
-- Variables and data
128 KB Flash -- Code space
Peripherals
Timers: two 8-bit, two 16-bit

ADC: 8 channel 10-bit
Buses: I2C, SPI, UART
Storage
512 KB Flash -- Off-chip serial flash
TinyOS System Components
TOS
Component
Description
ADCM.nc
Interface to the ADC
AMStandard.nc
Active Messages implementation
CRCPacket.nc
CRC packet calculator
ClockC.nc
Timing component
GenericComm.nc
Generic communication stack
FramerM.nc
Serial packetizer -- reliability layer component
I2CPacketC.nc
I2C protocol implementation
LedsC.nc
LED interface
LoggerM.nc
Interface to log data to the off-chip flash
TimerM.nc
Multi-application timer module
UART.nc
UART interface module
VoltageM.nc
Battery voltage measurement component
TinyOS Structure
Configuration
A wiring of Components together
Component
Provides a specific Service

Message Handling, Signal Processing
Implemented in a Module (code)

Wired up of other components in a Configuration
CntToLedsAndRfm Example
Study an Application to see Components, Configurations,
Commands, Events, and Tasks in action
LAB: Auto-generate Documentation
cd tinyos-1.x/contrib/xbow/CntToLedsAndRfm
make mica2 docs
Open with Document file Explorer
C:\tinyos\cygwin\opt\tinyos-1.x\
doc\nesdoc\mica2\apps.cnttoledsandrfm.CntToLedsAndRfm.n
c.app.html
CntToLedsandRfm Wiring
TinyOS Configuration
Connects Components together
Every TOS Application has a single top-level
CONFIGURATION file
A configuration wire connects Components
together through Interfaces
Configuration Template
Tinyos-1.x/tos/lib/IntToRfm.nc
includes IntMsg;
Interface to Components
configuration IntToRfm
Implementation
{ provides {
interface IntOutput;
interface StdControl;
}}
implementation
{ components IntToRfmM, GenericComm as Comm;
IntOutput = IntToRfmM;
as alias
StdControl = IntToRfmM;
IntToRfmM.Send -> Comm.SendMsg[AM_INTMSG];
IntToRfmM.SubControl -> Comm;
}
Wiring to other components
TinyOS Interface Overview
TOS
Interface
Description
ADC.nc
Interface to the ADC
I2C.nc
I2C bus protocol interface
Leds.nc
LED actuation interface
LogData.nc
Interface for logging data to storage device
Radio.nc
Bit level interface for radio hardware
Receive.nc
Generic messaging interface receive
Send.nc
Generic messaging interface send
StdControl.nc
Standard component control interface
Timer.nc
General timer control interface
10
Configuration Syntax
Binds the User to the Providers component via an
Interface:
User.interface -> Provider.interface

myApp.Timer -> FastClocker.Timer
or
myApp.Timer -> FastClocker

Timer interface implied
11
nesC Component Structure

Specification
Declares the services provided

Lists all interfaces the component
uses
Must implement any used event
provides
Must implement any provided command
Alias interfaces as nickname
Component
Specification
provides
Interface_A
uses
Interface_B
Implementation
Frame
Implementation
Functions
Defines internal workings

May include other components and associated
wiring
12
Interface Syntax
Tinyos-1.x/tos/interfaces/timer.nc
includes Timer; // make TIMER_x constants available
interface Timer {
/**
* Start the timer.
* @param type The type of timer to start.
*/
command result_t start(char type, uint32_t interval);
command result_t stop();
event result_t fired();
}
13
Implementation
Defines how the component works.
E.g. What happens on a Start command?

Commands
Events
Allows multiple Implementations for any

Interface
E.g. Radio
MICA2 vs. MICAz implementations
Multiple interfaces
Interface_A
Component Implementation
Functions
1: Control (start, stop)

2. Data flow (send, receive)
Interface_B
Frame
Interface_C
Commands
14
Events
Implementation Requirements
All Commands & Events declared as provided in
the INTERFACE section must be implemented.
Two Sections
1. Module: Declares Interfaces Provided and Used

2. Implementation: Program code
15
Module Syntax
Tinyos-1.x/tos/lib/counter.nc
module Counter {
provides {
interface StdControl; }
uses {
interface Timer;
interface IntOutput; }}
implementation {
Frame
Frame memory
memory variable
variable
int state;
command result_t StdControl.start() {
return call Timer.start(TIMER_REPEAT, 250); }
event result_t IntOutput.outputComplete(result_t success){
if(success == 0) state --;
return SUCCESS; }
}//implementation
16
nesC Filename Convention

Configuration (aka wiring)
myApp.nc at Top Level

myComponentC.nc at lower levels
Interfaces
myComponent.nc
Implementation
Modules - myComponentM.nc
Configurations myComponentC.nc
17
TOS Process Categories

Events
Time Critical
Interrupts cause Events (Timer, ADC, Sensors)
Small / short duration
Suspend Tasks
Tasks
Time Flexible
Run sequentially by TOS Scheduler
Run to completion wrt other Tasks
Interruptible
18
TinyOS Process Flow

Two level scheduling: events and tasks
Scheduler is simple FIFO
A task cannot preempt another task
Events preempt tasks (higher priority)
Preempt
POST
events
main {
while(1) {
while(more_tasks)
schedule_task;
sleep;
}
}
Tasks
FIFO
commands
commands
Interrupts
Time
Hardware
19
Tiny OS Kernel
INTERRUPT
TOS KERNEL SCHEDULER

TASK QUE
TASK#1
TASK#2
TASK#3
IF
TASK QUE
EMPTY
then
SLEEP
INTERRUPT
VECTORs
ADC
TIMER0 Time Out

Wakeup
ISR
TIMER1
EVENT
Handler
UART0
SPI
if Que !Empty:
execute TASK
TASK#n
INT0
Call Command(B)
Return
Event Return
Task Return
No TASKS pending
Command(s)
TASK(m)
Call Command(A)
Return
Command(s)
20
INTERRUPT
SLEEP
(Interrupts Enabled)
Commands and Events

Component1
Event
signal keyword triggers an event

Flows upward to wired component(s)
Issued to higher level: provides callback
A C callback function
Control returns to signaling component
Command
Functions
signal event1
call command1
call keyword executes a command

Flows down the configuration hierarchy
Issued to lower level: uses library code
Just a C function call - parameters on stack
Control returns to caller
Component2
Interface
21
Interface
Component3
Commands
Implemented under the keyword command
Invoked/called by call syntax
call InterfaceName.CommandName(params)
command result_t StdControl.start() {
return call Timer.start(TIMER_REPEAT, 250);
}
22
Events
Initiated by a signal.
Handled with an Event Handler
event result_t Send.sendDone(TOS_MsgPtr msg,result_t success) {
if (pending && msg == &data){
pending = FALSE;
signal IntOutput.outputComplete(success);}
return SUCCESS;
}
23
Tasks
Declared before they are invoked
No parameters (use Frame variables)
Tinyos-1.x/tos/system/TimerM.nc
task void HandleFire() {
if (mState) {
for (i=0;i<NUM_TIMERS;i++) {
post signalOneTimer();
}//HandleFire
async event result_t Clock.fire() {
post HandleFire();
return SUCCESS;
}
24
TinyOS Tasks
Time flexible
Run sequentially by TOS Scheduler
synchronous first in, first out, (FIFO) Schedule
Run to completion with respect to other Tasks

Interrupted by Events
25
TinyOS Scheduler
Scheduler is a simple first in, first out scheme
TinyOS STATE
TinyOS Task First-in First-Out Queue & Scheduler
Sleep
Sleep
TASK3
TASK1
TASK2
TASK3
HPL TinyOS Layer APP
POST T3
POST T2
TASK1
EVENT 2
POST Task1
TASK 1
TASK2
T3
TASK2
TASK3
T3
COMP 2
E3
EVENT 1
COMP 1
TOSH_SIGNAL ISR
INTERRUPT
Time
26
Shared States and atomic

Updates to shared state are allowed:
Sync
Only in synchronous code (e.g., tasks)
Atomic block
atomic {
//code is atomic can not be interrupted
ApplicationState = NewState;
atomic is a macro that disables all interrupts for

duration of the block {}
Be careful: atomic may impact Node performance
27
atomic Syntax
command result_t Timer.stop[uint8_t id]() {
if (id>=NUM_TIMERS) return FAIL;
if (mState&(0x1L<<id)) { // if the timer is running
atomic mState &= ~(0x1L<<id);
if (!mState) {
setIntervalFlag = 1;
}
return SUCCESS;
}
return FAIL; //timer not running
}
28
async vs. sync

async Code
Code that is reachable from at least one Interrupt Handler
sync Code
Command, Events, or Tasks only reachable from Tasks
Any update to shared state (memory) that is

reachable from async is a potential data race.
nesC reports a compile-time error for any command
or event that is async and that was not declared with
async.
This ensures that code that was not written to execute
safely in an interrupt handler is not called inadvertently.

29
async Syntax
async attribute used to indicate command or event
is part of an asynchronous flow

async processes are decoupled by posting a task
A task is always synchronous
tinyos-1.x/tos/system/TimerM.nc
async event result_t Clock.fire() {
post HandleFire();
return SUCCESS;
}
30
The
The post
post task
task decouples
decouples
the
the async
async event
event
TOS Rules
Hardware Event handler Commands and Events
must be declared with the async keyword
Indicates that this code may execute asynchronously to

Tasks and other processes.
nesC will check & warn if states (variables) could be
affected (races)
Races are avoided by
accessing shared data exclusively within Tasks

Because Tasks cant interrupt each other
Use atomic statement to access shared variables
31
TOS Architecture Review

Events vs. Tasks
Configurations
Components
Component1
Component2
Interface
Implementation
Interface
Functions
signal event1
Modules
Provides, uses
call command1
Interface
Component3
32
TinyOS Programming & Messaging

TinyOS Programming
Split Phase Operations

Parameterized Interfaces
Wiring Fan-In & Fan-Out
TOS Messaging
Groups, Addresses
Active Messaging
Wireless Communication
33
Split Phase Request & Done Sequence
Component1
commandA {
call Comp2.goCmdX;
//continue
return SUCCESS}
Event handler
event cmdXDone{
//process result
return SUCCESS}
Commands initiate an
operation
Continue/idle
Event indicates
completion
Component2
goCmdX{
post task1();
return SUCCESS}
Task1{
//do stuff
signal cmdXDone();
return SUCCESS}
TOS Scheduler
34
Split Phase Use

Variable Duration processes
Hardware I/O Operations
ADC Start Conversion > Data Ready
Slow devices
Flash Memory Write Buffer > Done
Asynchronous or Complex Processes
Send a Message to Communications Stack and continue

with operations until .sendDone
35
Split Phase Example: Client Side

Tinyos-1.x/lib/Counters/Counter.nc
event result_t Timer.fired()
{
state++;
return call IntOutput.output(state);
}
Phase
Phase 11 Start
Start the
the output
output
operation
operation
event result_t IntOutput.outputComplete(result_t success)

{
Phase
Phase 22 output
output is
is complete
complete
if(success == 0) state --;
return SUCCESS;
}
Counter.IntOutput -> IntToRfm;
36
Split Phase Example: Server Side

Tinyos-1.x/lib/Counters/IntToRfmM.nc
command result_t IntOutput.output(uint16_t value) {
IntMsg *message = (IntMsg *)data.data;
Phase
Phase 11 Start
Start the
the output
output
if (!pending){
operation
operation
pending = TRUE;
message->val = value;
atomic { message->src = TOS_LOCAL_ADDRESS;}
if (call Send.send(TOS_BCAST_ADDR, sizeof(IntMsg), &data))
return SUCCESS;
pending = FALSE;}
return FAIL;
}
event result_t Send.sendDone(TOS_MsgPtr msg, result_t success) {
if (pending && msg == &data){
pending = FALSE;
signal IntOutput.outputComplete(success);}
return SUCCESS;
Phase
Phase 22 output
output is
is complete
complete
}
37
Multiple Users of a Component
One Timer component but many Users with different Event

time requirements
When a Timer fires which component should be
signaled?
How does TinyOS handle this ?
Multiple Instantiations of a Components Interface

Parameter specifies the specific Instance
38
A parameterized interface allows a component to
provide multiple instances of an interface
Parameterization (index) is set by a compile-time
value
provides interface Timer[uint8_t id];
Total number of Instances permitted may be limited

by Implementation
39
Unique Instances
How to make sure your instance Parameter is not
used by some one else?
unique(astring)
generates a unique 8-bit identifier from the string given as
an argument.
Multiple Components using
timer[unique("Timer")]
are each guaranteed to get a signal associated with their
specific timer settings.
All Components must use the same string
40
Timer Parameter Interface Wiring

Provides
Provides aa Parameterized
Parameterized Interface
Interface
Tinyos-1.x/apps/CntToLedsandRfm.nc
configuration CntToLedsAndRfm {
}
implementation {
components Main, Counter, IntToLeds,
IntToRfm, TimerC;
module TimerM {
provides interface Timer[uint8_t id];
provides interface StdControl;
uses {
interface Leds;
interface Clock;
interface PowerManagement;
}
}
Main.StdControl -> Counter.StdControl;

Main.StdControl -> IntToLeds.StdControl;
Main.StdControl -> IntToRfm.StdControl;
Main.StdControl -> TimerC.StdControl;
Counter.Timer->TimerC.Timer[unique("Timer")];
IntToLeds <- Counter.IntOutput;
implementation {
uint32_t mState;
uint8_t queue_size;
uint8_t queue[NUM_TIMERS];
Instantiates
Instantiates the
the Timer
Timer number
number uniquely
uniquely
41
Fan-Out
Component is wired to multiple Destinations
Commands and Events will flow between all
connected components
Order is not guaranteed
Tinyos-1.x/apps/CntToLedsAndRfm.nc
configuration CntToLedsAndRfm {
}
implementation {
components Main, Counter, IntToLeds, IntToRfm, TimerC;
Counter.IntOutput -> IntToLeds;
42
Communicating between Nodes

Message Flow
1. Fill a Message buffer with Data to send
2. Specify node address to receive the message
3. Specify Message Type (AM Number)
4. Lock Message buffer during .send operation
Buffering the incoming message
5. Processing the message on reception
43
Group IDs and Addresses

Nodes only communicate within a common Group ID
Assigned in Makelocal or MakeXbowlocal
Node addresses, <#>, must be unique

Assigned in install.<#>
Reserved node addresses

Broadcast
UART Channel
0xFF
0x7E
44
TOS Radio & UART Messages

Information passed between Motes use a standard
message format
Messages include
Destination Address
Group ID
Message Type
Routes to Receivers appropriate Message Handler
Message Size and Data
45
TOSmsg (tinyos-1.x/tos/types/am.h)
#define TOSH_DATA_LENGTH 29
typedef struct TOS_Msg{
uint16_t addr;
uint8_t type;
uint8_t group;
uint8_t length;
int8_t data[TOSH_DATA_LENGTH];
uint16_t crc;
TOS
TOS Message
Message 36
36 Bytes
Bytes
//Extra
uint16_t strength;
uint8_t ack;
uint16_t time;
uint8_t sendSecurityMode;
uint8_t receiveSecurityMode;
} TOS_Msg;
46
Extension
Extension passed
passed from
from MAC
MAC layer
layer
77 bytes
bytes
TOSMsg Supplemental info

Ack: Transmission Acknowledge by Receiver
Strength:
RSSI on Receive
LowPowerRadioStack: Determines PowerMode / Preamble
size on Transmit
47
Active Messaging Flow

TOS Msg[AM#]
Application
Senders TOS Message

specifies AM# (Message
Type)& Destination Address
Receivers Message filtered
for GroupID & Node Address
Routed by AM handlers
parameterized interface to
appropriate Message Event
handler
AM
RADIO
STACK
TX
RX
RADIO
STACK
Generic
Comm
AM
signal[m](TOSMsg) signal[n]
AM Handler
#m
48
Generic
Comm
AM Handler
#n
signal[p]
AM Handler
#m
Active Message: A Parameterized Interface

Tinyos-1.x/tos/lib/Counters/IntToRfm.nc
includes IntMsg;
configuration IntToRfm
{ provides {
interface IntOutput;
interface StdControl;
}}
implementation
{ components IntToRfmM, GenericComm as Comm;
IntOutput = IntToRfmM;
StdControl = IntToRfmM;
IntToRfmM.Send -> Comm.SendMsg[AM_INTMSG];
IntToRfmM.SubControl -> Comm;
Active Message ID
defined in IntMsg.h
49
Message Buffer Exchange

TX Side
AM Component gets ownership
of TXBuffer until Signals
Transmission has completed
TX Component
.send(&TXBuffer)
.sendDone(&TXBuffer)
RX Side
Event Handler gets RXBuffer.
Returns a buffer for next RX
message.
Signal.Rcv(&RXBuffer)
RX
Event Handler
50
AM Component
AM Component
return (&RXBuffer)
TOS Message Buffers

Buffer Ownership alternates between Application and
Messaging Layers
Buffers are allocated at COMPILE time
Send Message (split phase)
AM Layer owns the TX buffer once called

User must NOT modify buffer until .sendDone Event from
AM Layer
Receive Event
AM Layer passes a RX Message buffer pointer

User must return a valid free buffer pointer for the next
Received message
51
Sending a Message
IntToRfmM.nc
The
bool pending;
The buffer
buffer is
is now
now busy
busy
struct TOS_Msg data;
/* ... */
command result_t IntOutput.output(uint16_t value) {
IntMsg *message = (IntMsg *)data.data;
if (!pending) {
pending = TRUE;
message->val = value;
TXBuffer
TXBuffer pointer
pointer
atomic {
message->src = TOS_LOCAL_ADDRESS;
}
if(call Send.send(TOS_BCAST_ADDR, sizeof(IntMsg),&data))
return SUCCESS;
pending = FALSE; //request failed /
return FAIL;
Destination
Destination address
address
}
52
AMStandard: Receiving Messages

TOS_MsgPtr received(TOS_MsgPtr packet){
uint16_t addr = TOS_LOCAL_ADDRESS;
counter++;
if (packet->crc == 1 &&
packet->group == TOS_AM_GROUP &&
(packet->addr == TOS_BCAST_ADDR ||
packet->addr == addr)){
Check
Check GroupID,
GroupID, Node
Node Address
Address
uint8_t type = packet->type;
TOS_MsgPtr tmp;
tmp = signal receiveMsg.receive[type](packet);
if (tmp) packet = tmp;
}//if valid packet
Signal
Signal the
the assigned
assigned AM
AM Handler
Handler
return packet;}
Use
Use the
the returned
returned buffer
buffer for
for next
next Msg
Msg
53
Application Layer Active Message Handler
event TOS_MsgPtr ReceiveIntMsg.receive(TOS_MsgPtr pTOS) {

IntMsg *message = (IntMsg *)pTOS->data;
call IntOutput.output(message->val);
Typecast
Typecast the
the Buffer
Buffer
return pTOS;
}
IntOutput now has a private copy of val
IntOutput now has a private copy of val
Return
Return the
the Buffer
Buffer to
to GenericComm
GenericComm
54
TinyOS Review
Split phase processes
Indeterminate duration
Parallelism
Parameterized interfaces
Active messages
Routing
Message structure
Buffers
Groups and node IDs
55
End of TinyOS Developers Programming
56

03 TinyOS Programming

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

03 TinyOS Programming

Încărcat de

Drepturi de autor:

Formate disponibile

TinyOS Developers Programming

San Jose / February 9-10, 2005

TOS Scheduler (Main)

TOS Component Interfaces

San Jose / February 9-10, 2005

Timers: two 8-bit, two 16-bit

512 KB Flash -- Off-chip serial flash

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS System Components

Interface to the ADC

Active Messages implementation

CRC packet calculator

Generic communication stack

Serial packetizer -- reliability layer component

I2C protocol implementation

Interface to log data to the off-chip flash

Multi-application timer module

UART interface module

Battery voltage measurement component

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

A wiring of Components together

Provides a specific Service

Implemented in a Module (code)

San Jose / February 9-10, 2005

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS Interface Overview

Interface to the ADC

I2C bus protocol interface

LED actuation interface

Interface for logging data to storage device

Bit level interface for radio hardware

Generic messaging interface receive

Generic messaging interface send

Standard component control interface

General timer control interface

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

User.interface -> Provider.interface

myApp.Timer -> FastClocker

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

nesC Component Structure

Declares the services provided

Alias interfaces as nickname

Defines internal workings

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

TinyOS/nesC Programming (Parts 1 and 2)

San Jose / February 9-10, 2005

E.g. What happens on a Start command?

Allows multiple Implementations for any

1: Control (start, stop)

San Jose / February 9-10, 2005

1. Module: Declares Interfaces Provided and Used

TinyOS/nesC Programming (Parts 1 and 2)