Terra customization: TinyOS Network basic operations

In this page we present a customization, called TerraNet, that is a very light customization using only simple radio communications and sensors operations.

TerraNet - Basic Operations

This Terra customization mainly provides only very basic "send" and "receive" events and local sensors readings. Table 1 presents the current TerraNet events interface and Table 2 presents the functions interface.

The local operations comprises operations to read sensors and residual energy battery, define led's configuration and access input and output devices of the microcontroller. Terra encapsulates all these operations in a component called Local Operations providing them as output events. Timers, on the other hand, are handled directly by the Céu-T language with the await time command.

The SEND() command is a basic send command where only the nodes in the radio range may receive the message. If the field target is set to BROADCAST value, all nodes in the range will receive the message. On the other hand, if this field is set to a specific node identifier, only this node will receive the message (if the node is in the radio range). A SEND_DONE() event indicates that the send request was processed by the radio. The RECEIVE event returns a received message. A variation of the SEND() command is the SEND_ACK() command that requests an acknowledgement from the target mote. In this variation the SEND_DONE_ACK() event return a boolean value indicating the acknowledgement. Additionally, TerraNet implements a simple message queue to support message buffering needs.

The user must define the radio message data structure before create a message variable.


Table 1 - TerraNet Events interface
Description Output event (emit) Input event (await)
Event identifier Argument type Returned type Event identifier Argument type
Set all three leds - The less three significative bits of the argument will set the leds. LEDS ubyte
Set LED0 - Argument can be ON, OFF, or TOGGLE. LED0 ubyte
Set LED1 - Argument can be ON, OFF, or TOGGLE. LED1 ubyte
Set LED2 - Argument can be ON, OFF, or TOGGLE. LED2 ubyte
Temperature Sensor - Requests and receives the sensor value. The received value is a 10bit reading from A/D converter. This is not the physical unit. REQ_TEMP void ushort TEMP void
Luminosity Sensor - Similar to the others sensors. REQ_PHOTO void ushort PHOTO void
Voltage Sensor - Similar to the others sensors. REQ_VOLTS void ushort VOLTS void
Custom event - This is a internal loopback event that allows to pass a integer value. The await command may define or not which value to wait. REQ_CUSTOM_A ubyte ubyte CUSTOM_A void or ubyte
Send radio message - Sends a radioMsg variable (broadcast or to a specific target node). SEND radioMsg ubyte SEND_DONE void or ubyte
Send radio message (with Acknowledgement) - Sends a radioMsg variable to a specific target node requesting an acknowledgment. The confirmation (TRUE or FALSE) is returned in the SEND_DONE_ACK. SEND_ACK radioMsg ubyte SEND_DONE_ACK void or ubyte
Receive radio message - returns a radioMsg variable received by the radio. The argument may be used to wait only a specific message type identifier. radioMsg RECEIVE void or ubyte
Message queue - This event indicates that the msg queue got a new element when it was empty. ubyte Q_READY void
Error trap - Indicates a internal errors like E_DIVZERO and E_IDXOVF, respectively division by zero and array index overflow. ubyte ERROR void or ubyte


Table 2 - TerraNet functions interface
Description Returned type Function name arguments
Return the node identifier ushort getNodeId void
Return a 16bits random number ushort random void
Return the internal timer counter ulong getTime void
Put a radioMsg data into the queue. The message structure is passed as argument. Returns FAIL if the queue is full, otherwise returns SUCCESS. ubyte qPut radioMsg msgVar
Get a radioMsg data from the queue. The message structure is passed as argument. Returns FAIL if the queue is empty, otherwise returns SUCCESS. ubyte qGet radioMsg msgVar
Retur the queue size ubyte qSize void
Clear all queue entries. Always returns SUCCESS. ubyte qClear void
Set the radio transmit power level. Always returns SUCCESS. ubyte setRFPower ubyte level

Table 3 - TerraNet Constant definitions
Constant Value Description
SUCCESS 0 Indicates a Success operation
TRUE 1 A true value
FALSE 0 A false value
ON 1 Set LED ON
OFF 0 Set LED OFF
TOGGLE 2 Set LED with oposite value
BROADCAST 0xffff Define a broadcast message
E_DIVZERO 10 Error event - Division by zero
E_IDXOVF 11 Error event - Array index overflow
E_STKOVF 20 Error event - Stack overflow -- fatal