03 tinyos programming

7/25/2019 03 TinyOS Programming

1/56

San Jose / February 9-10, 2005TinyOS/nesC Programming (Parts 1 and 2) 1

TinyOS DeveloperTinyOS Developers Programmings Programming

Topics:

TinyOS Structures Commands, Events, & Tasks

Configurations, Components, & Modules

Implementation

Application Example

How the pieces fit together

TOS Advanced Flows

TOS Messaging


2/56

TinyOS/nesC Programming (Parts 1 and 2) 2 San Jose / February 9-10, 2005

TinyOS LayersTinyOS Layers

Hardware Presentation/Abstraction Layer

Mote Devices Sensor Devices

TOS Scheduler (Main)

System Components

Library

Components TOS Component Interfaces

Application

Configuration

Application Specific

Components

Application Interfaces

EventsCommands

Legend

User

TOS

HW


3/56


Mote CPUMote 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


4/56TinyOS/nesC Programming (Parts 1 and 2) 4 San Jose / February 9-10, 2005

TOSTinyOS System ComponentsTinyOS System Components

Component Description

ADCM.nc Interface to the ADC

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

AMStandard.nc Active Messages implementation

CRCPacket.nc CRC packet calculator

VoltageM.nc Battery voltage measurement component



TinyOS StructureTinyOS 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 ExampleCntToLedsAndRfm Example

Study an Application to see Components, Configurations,Commands, Events, and Tasks in action

LAB: Auto-generate Documentation cd tinyos-1.x/contrib/xbow/CntToLedsAndRfmmake mica2 docs

Open with Document file Explorer

C:\tinyos\cygwin\opt\tinyos-1.x\doc\nesdoc\mica2\apps.cnttoledsandrfm.CntToLedsAndRfm.nc.app.html


7/56


CntToLedsandRfmCntToLedsandRfm WiringWiring


8/56


TinyOS ConfigurationTinyOS Configuration

Connects Components together

Every TOS Application has a single top-level

CONFIGURATION file A configuration wire connects Components

together through Interfaces


9/56


Configuration TemplateConfiguration Template

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;

}

Tinyos-1.x/tos/lib/IntToRfm.nc

Interface to Components

Implementation

as alias

Wiring to other components


10/56


TOSTinyOS Interface OverviewTinyOS Interface Overview

Interface Description

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

ADC.nc Interface to the ADC

I2C.nc I2C bus protocol interface

Leds.nc LED actuation interface

Timer.nc General timer control interface


11/56


Configuration SyntaxConfiguration Syntax

Binds the User to the Providers component via an

Interface:

User.interface > Provider.interface

myApp.Timer -> FastClocker.Timer

or

myApp.Timer -> FastClockerTimer interface implied


12/56


nesC Component StructurenesC 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

Implementation Defines internal workings May include other components and associated

wiring

Component

Frame

Functions

provides

Specification

Implementation

uses

Interface_A

Interface_B


13/56


Interface SyntaxInterface Syntax

includes Timer; // make TIMER_x constants availableinterface 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();

}

Tinyos-1.x/tos/interfaces/timer.nc


14/56


ImplementationImplementation

Defines how the component works. E.g. What happens on a Start command?

Allows multiple Implementations for anyInterface E.g. Radio

MICA2 vs. MICAz implementations

Multiple interfaces 1: Control (start, stop)

2. Data flow (send, receive)

Interface_A Interface_B

Interface_C

FrameFunctions

Component Implementation

Commands

Events

Events

Commands


15/56


Implementation RequirementsImplementation Requirements

All Commands & Events declared as provided in

the INTERFACE section must be implemented.

Two Sections1. Module: Declares Interfaces Provided and Used

2. Implementation: Program code


16/56


Module SyntaxModule Syntax

module Counter {provides {interface StdControl; }

uses {interface Timer;interface IntOutput; }}

implementation {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

Tinyos-1.x/tos/lib/counter.nc

Frame memory variableFrame memory variable


17/56


nesC Filename ConventionnesC 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


18/56


TOS Process CategoriesTOS 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


19/56


TinyOS Process FlowTinyOS Process Flow

Two level scheduling: events and tasks

Scheduler is simple FIFO

A task cannot preempt another task Events preempt tasks (higher priority)

main {

while(1) {

while(more_tasks)schedule_task;

sleep;

}

} Hardware

Interrupts

ev

ents

commands

FIFO

TasksPOST

Preempt

Time

commands


20/56


Tiny OS KernelTiny OS Kernel

TASK#1

TASK#2

TASK#3

TASK#n

TASK QUE

TASK(m)

if Que !Empty:

execute TASK

Task Return

TOS KERNEL SCHEDULER

EVENTHandler

Command(s)

Call Command(B)

Return

ISR

Event Return

ADC

TIMER1

UART0

SPI

INT0

INTERRUPT

VECTORs

Command(s)

Call Command(A)

Return

IFTASK QUE

EMPTY

thenSLEEP

SLEEP

(Interrupts Enabled)

No TASKS pending

TIMER0 Time OutWakeup

INTERRUP

T

INTERRUPT


21/56


Commands and EventsCommands 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 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

Component3

Interface

Interface

Functions

signal event1

call command1

Component2


22/56


CommandsCommands

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);

}



23/56


EventsEvents

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;}



24/56


TasksTasks

Declared before they are invoked

No parameters (use Frame variables)

task void HandleFire() {if (mState) {

for (i=0;i


25/56


TinyOS TasksTinyOS 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


26/56


TinyOS SchedulerTinyOS Scheduler

Scheduler is a simple first in, first out scheme

E3

TOSH_SIGNAL ISR

COMP 1

EVENT 1

TASK 1

COMP 2

EVENT 2

TASK2

TASK2

TASK3

T3

TinyOS Task First-in First-Out Queue & Scheduler

TASK1

POST Task1

TASK1

POST T2POST T3

TASK2TASK3

TASK3

SleepSleep

INTERRUPT

TinyOS STATE

HPL

Tiny

OS

LayerA

PP

Time

T3


27/56


Shared States andShared States and tomitomi

Updates to shared state are allowed:

SyncOnly in synchronous code (e.g., tasks)

Atomic blockatomic {

//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


28/56


atomic Syntaxatomic Syntax

command result_t Timer.stop[uint8_t id]() {

if (id>=NUM_TIMERS) return FAIL;if (mState&(0x1L


29/56


asyncasyncvs. syncvs. 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.


30/56


asyncasync SyntaxSyntax

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

async event result_t Clock.fire() {post HandleFire();return SUCCESS;

}

tinyos-1.x/tos/system/TimerM.nc

The post task decouplesthe async event

The post task decouplesthe async event


31/56


TOS RulesTOS 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


32/56


TOS Architecture ReviewTOS Architecture Review

Events vs. Tasks

Configurations

Components Interface

Implementation

Modules Provides, uses

Component1

Component3

Interface

Interface

Functions

signal event1

call command1

Component2


33/56


TinyOS Programming & MessagingTinyOS Programming & Messaging

TinyOS Programming Split Phase Operations

Parameterized Interfaces

Wiring Fan-In & Fan-Out

TOS Messaging

Groups, Addresses Active Messaging

Wireless Communication


34/56


Split Phase Request & Done SequenceSplit Phase Request & Done Sequence

Event handler

Component1

goCmdX{

post task1();return SUCCESS}

commandA {call Comp2.goCmdX;//continuereturn SUCCESS}

Commands initiate an

operation

Continue/idle

Event indicates

completion

Task1{

//do stuffsignal cmdXDone();return SUCCESS}

event cmdXDone{//process resultreturn SUCCESS}

TOS Scheduler

Component2


35/56


Split Phase UseSplit 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


36/56


Split Phase Example: Client SideSplit Phase Example: Client Side

event result_t Timer.fired()

{ state++;return call IntOutput.output(state);

}

event result_t IntOutput.outputComplete(result_t success){if(success == 0) state --;return SUCCESS;

}

Tinyos-1.x/lib/Counters/Counter.ncPhase 1 Start the output

operation

Phase 1 Start the output

operation

Phase 2 output is completePhase 2 output is complete

Counter.IntOutput -> IntToRfm;


37/56


Split Phase Example: Server SideSplit Phase Example: Server Side

command result_t IntOutput.output(uint16_t value) {IntMsg *message = (IntMsg *)data.data;if (!pending){

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;}

Tinyos-1.x/lib/Counters/IntToRfmM.nc


operation


operation

Phase 2 output is completePhase 2 output is complete


38/56


Parameterized InterfacesParameterized Interfaces

Multiple Users of a Component One Timer component but many Users with different Event

time requirements

When a Timer fires which component should besignaled?

How does TinyOS handle this ? Multiple Instantiations of a Components

Interface

Parameter specifies the specific Instance


39/56


Parameterized InterfacesParameterized Interfaces

A parameterized interface allows a component to

provide multiple instances of an interface

Parameterization (index) is set by a compile-timevalue

provides interface Timer[uint8_t id];

Total number of Instances permitted may be limited

by Implementation


40/56


Unique InstancesUnique 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

Ti P I f Wi i


41/56


Timer Parameter Interface WiringTimer Parameter Interface Wiring

Provides a Parameterized Interface

module TimerM {

provides interface Timer[uint8_t id];provides interface StdControl;

uses {

interface Leds;

interface Clock;

interface PowerManagement;

}}

implementation {

uint32_t mState;

uint8_t queue_size;

uint8_t queue[NUM_TIMERS];

Tinyos-1.x/tos/system/TimerM.nc

configuration CntToLedsAndRfm {

}implementation {components Main, Counter, IntToLeds,

IntToRfm, TimerC;

Main.StdControl -> Counter.StdControl;Main.StdControl -> IntToLeds.StdControl;

Main.StdControl -> IntToRfm.StdControl;Main.StdControl -> TimerC.StdControl;Counter.Timer->TimerC.Timer[unique( Timer )];

IntToLeds IntToRfm;

}

Tinyos-1.x/apps/CntToLedsandRfm.nc

Instantiates the Timer number uniquelyInstantiates the Timer number uniquely

Provides a Parameterized Interface

FF OO t


42/56


FanFan--OutOut

Component is wired to multiple Destinations Commands and Events will flow between all

connected components

Order is not guaranteed

configuration CntToLedsAndRfm {}implementation {components Main, Counter, IntToLeds, IntToRfm, TimerC;

Counter.IntOutput -> IntToLeds;Counter.IntOutput -> IntToRfm;

}

Tinyos-1.x/apps/CntToLedsAndRfm.nc

C i ti b t N dC i ti g b t N d


43/56


Communicating between NodesCommunicating between Nodes

Message Flow

1. Fill a Message buffer with Data to send2. 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

G ID d AddG ID d Add


44/56


Group IDs and AddressesGroup 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 0xFF

UART Channel 0x7E

TOS R di & UART M gTOS Radio & UART Messages


45/56


TOS Radio & UART MessagesTOS Radio & UART Messages

Information passed between Motes use a standardmessage format

Messages include Destination Address

Group ID

Message Type

Routes to Receivers appropriate Message Handler

Message Size and Data

TOSmsgTOSmsg ( i(ti 1 / / / h)1 /t /t / h)


46/56


TOSmsgTOSmsg (tinyos(tinyos--1.x/tos/types/am.h)1.x/tos/types/am.h)

#define TOSH_DATA_LENGTH 29typedef struct TOS_Msg{uint16_t addr;uint8_t type;uint8_t group;uint8_t length;int8_t data[TOSH_DATA_LENGTH];

uint16_t crc;//Extrauint16_t strength;uint8_t ack;

uint16_t time;uint8_t sendSecurityMode;uint8_t receiveSecurityMode;

} TOS_Msg;

TOS Message 36 BytesTOS Message 36 Bytes

Extension passed from MAC layer7 bytes

Extension passed from MAC layer

7 bytes

TOSMsgTOSMsg Supplemental infoSupplemental info


47/56


TOSMsgTOSMsg Supplemental infoSupplemental info

Ack: Transmission Acknowledge by Receiver

Strength: RSSI on Receive

LowPowerRadioStack: Determines PowerMode / Preamble

size on Transmit

Active Messaging FlowActive Messaging Flow


48/56


Active Messaging FlowActive Messaging Flow

Senders TOS Message

specifies AM# (MessageType)& Destination Address

Receivers Message filtered

for GroupID & Node Address

Routed by AM handlers

parameterized interface to

appropriate Message Event

handler

AM Handler#m

signal[m](TOSMsg)

RX

RADIO

STACK

AM Handler#n

signal[n]

AM Handler#m

signal[p]

RADIO

STACKTX

Application Generic

Comm

AM

TOS Msg[AM#]

Generic

Comm

AM

Active Message: A Parameterized InterfaceActive Message: A Parameterized Interface


49/56


Active Message: A Parameterized InterfaceActive Message: A Parameterized Interface

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;

}

Tinyos-1.x/tos/lib/Counters/IntToRfm.nc

Active Message ID

defined in IntMsg.h

Message Buffer ExchangeMessage Buffer Exchange


50/56


Message Buffer ExchangeMessage Buffer Exchange

TX Side

AM Component gets ownershipof TXBuffer until SignalsTransmission has completed

TX Component

AM Component.sendDone(&TXBuffer)

.send(&TXBuffer)

AM Component

RXEvent Handler

return (&RXBuffer)

Signal.Rcv(&RXBuffer) RX Side

Event Handler gets RXBuffer.Returns a buffer for next RX

message.

TOS Message BuffersTOS Message Buffers


51/56


TOS Message BuffersTOS Message Buffers

Buffer Ownership alternates between Application andMessaging 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

Sending a MessageSending a Message


52/56


Sending a MessageSending a Message

IntToRfmM.nc

bool pending;struct TOS_Msg data;

/* ... */command result_t IntOutput.output(uint16_t value) {IntMsg *message = (IntMsg *)data.data;if (!pending) {

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; //request failed return FAIL;}

TXBuffer pointerTXBuffer pointer

Destination addressDestination address

The buffer is now busyThe buffer is now busy

AMStandardAMStandard: Receiving Messages: Receiving Messages


53/56


AMStandardAMStandard: Receiving Messages: Receiving Messages

TOS_MsgPtrreceived(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)){

uint8_t type = packet->type;TOS_MsgPtr tmp;tmp= signal receiveMsg.receive[type](packet);if (tmp) packet = tmp;

}//if valid packet

return packet;}

Check GroupID, Node AddressCheck GroupID, Node Address

Signal the assigned AM HandlerSignal the assigned AM Handler

Use the returned buffer for next MsgUse the returned buffer for next Msg

Application Layer Active Message HandlerApplication Layer Active Message Handler


54/56


Application Layer Active Message HandlerApplication Layer Active Message Handler

event TOS_MsgPtr ReceiveIntMsg.receive(TOS_MsgPtr pTOS) {

IntMsg*message = (IntMsg*)pTOS->data;call IntOutput.output(message->val);return pTOS;

}

Typecast the BufferTypecast the Buffer

IntOutput now has a private copy of valIntOutput now has a private copy of val

Return the Buffer to GenericCommReturn the Buffer to GenericComm

TinyOS ReviewTinyOS Review


55/56


TinyOS Reviewy

Split phase processes Indeterminate duration

Parallelism

Parameterized interfaces

Active messages Routing

Message structure

Buffers

Groups and node IDs


56/56

San Jose / February 9-10, 2005TinyOS/nesC Programming (Parts 1 and 2) 56

End ofEnd of TinyOS Developers ProgrammingTinyOS Developers Programming

03 tinyos programming

Documents