SEAL Components

Introduction

Most of SEAL application syntax is based on component (sensors, LEDs, output channels etc.) use case descriptions.

The description of a component use case contains the name of the component followed by a list of parameters. For example, the line:

use Beeper, times 10, period 100ms;

tells to use Beeper component for 10 times with 100 millisecond period (i.e. beep for one second with 10Hz on/off frequency).

The next code sample utilizes "when" keyword to Beep when a specific condition is true:

when Random < 10000:
 use Beeper, on;
else:
 use Beeper, off;
end

For this example, the condition depends on output of random number generator. The Random value is constantly changing, so the system will beep at random times.

"New" components can be defined using define statement and functions. Afterwards then can be used like other, regular components. For example:

define MaxHumidity max(take(Humidity, 10));
read MaxHumidity;

defines component MaxHumidity which is equal to the maximum of last 10 (take(..., 10)) humidity sensor readings.

Parameters

A parameter is described by parameter name followed by optional parameter value.

For example, period 1h or on are both valid parameter descriptions.

Parameter value formats

• Integer: a whole number, for example 1, 100, 1234
• Boolean: true/false value, for example True, False
• String: a sequence of ASCII symbols, for example "hello world"
• Time value is an integer with an optional suffix, for example 13min
  • h – hours
  • min – minutes
  • s – seconds
  • ms – milliseconds.
• If no suffix is specified, the value is treated as milliseconds.

If only parameter name is specified, the default value is used. Some parameters (e.g. period) have specific default value; in that case the value is documented in brackets. Others use True or 1 as the default value, depending on type.

Parameters common for all components

• period (time value; default value: 1000ms) – the use/read period
• once (boolean) – use just once.
• times (integer) – use just the number of times (times 1 is the same as once)
• duration (time value) – use just for a specific duration (time period) since first used
• pattern (pattern name) – read/use using a specific time value patter.
• id (integer) – object identifier. Significant only if more than one component with the same name exists in the system.

Sensor-specific parameters

• turnOnOff (boolean) – turn on the sensor before reading and off afterwards. By default the sensors are on whole time. This parameter can be specified, if energy saving is desired.
• cache (boolean) – use cache to store and retrieve sensor values? The default behavior is dependent on sensor reading frequency. If application logic specifies read a sensor less than one second after previous the reading, the value is taken from cache; otherwise the value is read from the physical sensor. cache parameter can be used both to disable and to enable caching.

Actuator-specific parameters

• on (boolean) – turn the component on.
• off (boolean) – turn the component off.
• blink (boolean) – turn the component on (just once!), then off (using period parameter)

If no on/off parameters are specified for actuator use case, the component is periodically toggled: turned on and off, depending on the previous state.

Output-specific parameters

• aggregate (boolean) – if true, then a packet is formed; if no, then values are sent individually. True by default for all, except serial port.
• address (boolean) – if true, then local address is included in the packet. No effect if aggregate is false.
• timestamp (boolean) – if true, then time stamp is included in the packet. No effect if aggregate is false.
• sequenceNumber (boolean) – if true, then a sequence number (monotonically increasing counter) is included in the packet. No effect if aggregate is false.
• file (string) – the name of the file FROM which to output data. Usable only if the hardware platform supports files.
• where (an expression) – for outputs that take their contents from a file: the condition on the contents of the file.

Components

Sensors

Real sensors

Light

Sample light reading.

Parameters: all sensor parameters.

Humidity

Sample air humidity sensor reading.

Parameters: all sensor parameters.

Temperature

Sample air humidity sensor reading.

Parameters: all sensor parameters.

TotalSolarRadiation

Sample total solar radiation sensor. For TelosB, this is the same as Light sensor. Samples visible and infrared ranges (960 nm peak sensitivity wavelength).

Parameters: all sensor parameters.

Availability: only on TelosB.

PhotosyntheticRadiation

Sample photosynthetically active radiation sensor. Samples visible range of light (560 nm peak sensitivity wavelength).

Parameters: all sensor parameters.

Availability: only on TelosB.

AnalogIn

Sample a specific analog input. The values depend on the platform; for TelosB they are in range 0..4095.

Parameters:

• all sensor parameters
• channel (integer) – which channel to read. The possible values depend on hardware platform.

DigitalIn

Sample a specific digital input. The possible input values are 0 and 1.

Parameters:

• all sensor parameters
• channel (integer) – which channel to read. The possible values depend on hardware platform.

Pseudosensors

Constant

Read a constant value.

Parameters:

• all sensor parameters
• value (integer) – the constant value to read.

Counter

Read a monotonically increasing counter.

Parameters: all sensor parameters

Random

Read a random number. By default, numbers in [0..65535] are returned.

Parameters:

• all sensor parameters
• min (integer) – lower bound of returned values
• max (integer) – upper bound of returned values

TimeCounter

Read a monotonically increasing time counter value.

Parameters: all sensor parameters.

Timestamp

Read UNIX timestamp value (in seconds). If the clock of the system is synchronized with the real clock, real time is returned. If no, the seconds since system's start are returned.

Parameters: all sensor parameters.

Uptime

Read UNIX timestamp value (in seconds) since system's start.

Parameters: all sensor parameters

Actuators

An actuator use case can explicitly specify the action (for example, on or off). Nevertheless, usually the default action is sufficient. For example, for LED the default action is toggle: turn the LED on if it was off, and turn it off if it was on.

LED

Control the default LED.

Parameters: all actuator parameters.

RedLed

Control the red LED, if the system has one.

Parameters: all actuator parameters.

GreenLed

Control the green LED, if the system has one.

Parameters: all actuator parameters.

BlueLed

Control the blue LED, if the system has one.

Parameters: all actuator parameters.

Beeper

Control the beeper, if the system has one.

Parameters: all actuator parameters.

AnalogOut

Control a specific analog output channel.

Parameters:

• all actuator parameters
• channel (integer) – which channel use. Possible values depend on device.

Warning: not implemented at the moment!

DigitalOut

Control a specific digital output channel.

Parameters:

• all actuator parameters
• channel (integer) – which channel use. Possible values depend on device.

Print

Control a specific digital output channel.

Parameters:

• all actuator parameters
• format (string) – the format to use (printf-like).
• arg1 (depends on format) – first argument to format string.
• arg2...arg9 (depends on format) – other arguments to format string.

Usage examples:

use Print, period 1000, format "example %d: hello %s\n", arg1 1, arg2 "world";

// print with a specific and default format string
use Print, format "light: %d", arg1 Light;
use Print, arg1 Light;
use Print, arg1 Light, arg2 Humidity;

// print to specific mediums
use Print, format "hello world!";
use Print, format "hello world!", out Serial;
use Print, format "hello world!", out Radio;

Note: use of Print is NOT required to output e.g. typical system values. Do something like this instead:

 read Light; read Humidity;
 output Serial;
 // or this:
 // output Serial (Light, Humidity);

For debugging, specific output medium can also be specified directly after read statement:

// print to specific mediums - without "Print"!
read Light, out Radio;
read Light, out Serial;

Outputs

After sensor values are read and processed, they can be sent to base station, disseminated in the network, or stored locally on SD card, flash chip, or a file system.

Output use cases describe what to do with the data. For example, the statement:

output Radio;

instructs the system to sent sensor data after reading out to radio.

By default, the outputs activate outputting all sensors. If only a specific sensors are desired, they can be filtered by names. For example:

read Light;  read Humidity;  read Temperature;
output Radio (Humidity, Temperature);

instructs the system to sent Humidity and Temperature sensor data out to radio (but not Light sensor data!).

Special kind of outputs are those that take their contents from file. They are usually activated when an event happens (e.g. query is received from the network). The rules about outputting all sensors by default do not apply to them.

Serial

Serial interface (virtual COM port). Use this for debug output, for example, to print out sensor values:

read Light;
output Serial;

The code of this example reads light sensor values and prints them locally.

Parameters:

• all output parameters (aggregate is false by default)
• baudrate (integer; default value: 38400) – serial interface data rate in baud per second. One of 9600, 38400, 57600, 115200.

Radio

Raw radio output.

Parameters: all output parameters (address is true by default)

Network

Network output.

Parameters:

• all output parameters
• protocol (string; default value: "NULL") – name of MAC protocol to use. One of "NULL", "CSMA", "CSMA_ACK", "SAD".
  • NULL – no MAC protocol is used.
  • CSMA – Carrier Sense Multiple Access, a protocol that samples the medium before sending out data, and reschedules the sending in case it is busy.
  • CSMA_ACK – CSMA with reliable delivery (acknowledgements).
  • SAD – more advanced protocol that uses time slot allocation to avoid packet collisions.
• routing (string; default value: "DV") – name of routing protocol to use. One of "DV" and "SAD".
  • DV – distance vector; the node can be in one of roles "data source", "base station", and "forwarder".
  • SAD – protocol for the SAD application; more advanced distance vector protocol with additional "collector" role.

SdCard

Output to SD card, if the system has one.

Parameters: all output parameters

File

Output to a file, if the device supports file system.

Parameters:

• all output parameters
• filename (string) – the name of the file to write
• binary (boolean) – use binary data format? Opposite of "text"
• text (boolean) – use CSV (comma separated value, ASCII only) data format? Opposite of "binary"

Other syntax elements

C variables

The MansOS C variables can be accessed using variables.<name> syntax.

Example variables:

• localAddress – the network address of the mote (2 bytes)

C constants

The MansOS C constants can be accessed using constants.<name> syntax.

Example constants:

• ADC_LIGHT_TOTAL – total light sensor analog input channel ID
• ADC_LIGHT_PHOTOSYNTHETIC – photosynthetically active light sensor analog input channel ID
• ADC_INTERNAL_VOLTAGE – battery voltage analog input channel ID