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

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 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 behaviour is dependant 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 disable or enable caching behaviour.

Actuator-specific parameters

• on (boolean) - turn the component on
• off (boolean) - turn the component off
• blink (boolean) - turn the component on, then off (using "period" parameter)

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. Has effect only on hardware platforms that support 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.

AnalogIn

Parameters:

• all sensor parameters
• channel (integer) - which channel to read. Possible values depend on device.

DigitalIn

Parameters:

• all sensor parameters
• channel (integer) - which channel to read. Possible values depend on device.

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

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 example:

use Print, period 1000, format "hello %s\n", arg1 "world";

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 outputing 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 outputing all sensors by default do not apply to them.

Serial

Serial interface (virtual COM port). Use this for debug ourput, 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 bauds 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 timeslots to avoid 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 - photosyntetically active light sensor analog input channel ID
• ADC_INTERNAL_VOLTAGE - battery voltage analog input channel ID