SEAL Components
Contents
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 asonce
) - 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.
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