Dive Into Swift Fox_v0.80.0 - mszczodrak/swift-fox GitHub Wiki

At this moment, please make sure that you have installed:

1. Fennec Fox
2. Swift Fox

We will start with looking into a simple program that will blink LED.

configuration hello { blink(1, 500)     # Application layer module
        nullNet()       # Network layer module
        nullMac()       # MAC layer module
        nullRadio()     # Radio layer module
        }
start hello

You can look at the details of the Swift Fox syntax here, however, at this moment we only introduce the necessary minimum requirements. This code says that we want to run a process that we call hello. The hello process runs with a protocols stack consisting of the blink application, nullNet network protocol, nullMac MAC protocol and nullRadio radio driver. As the modules' names suggest, nullNet, nullMac, and nullRadio are all empty modules, that simply fill the protocol layers without providing any communication support, because the blink application does not need any communication support.

The blink application module takes two parameters: 1 and 500. There are few ways of learning what these parameters mean. First, we can look into the documentation of this module. The blink module is part of the Fennec Fox standard library, and its documentation can be found here, inside of the module blink implementation. When the module documentation is not available, we need to figure out the meaning of the module parameters. First, we look into the definitions of all the Fennec Fox modules, which are located in Fennec Fox, under /src/support/sfc/fennec.sfl. In this file, we can find the following lines:

use application blink $(FENNEC_FOX_LIB)/Application/tests/Blink ( 
        uint8_t led=1, 
        uint16_t delay=1024 )

which say that there is a Fennec Fox module, that runs as application. This module is called by Swift Fox as blink, and the module code is located in the Fennec Fox, under Application/tests/Blink. This module takes two parameters called led and delay, and their default values are 1 and 1024, respectively. So, if our Swift Fox program would call blink() instead of blink(1, 500), the actual code would execute the blink with parameters 1 and 1024, which has the same meaning as if we would call blink as blink(1, 1024).

So, let's quickly see the Swift Fox program in actions. Save the following code in a file called hello.sfp:

configuration hello { blink(1, 500)     # Application layer module
        nullNet()       # Network layer module
        nullMac()       # MAC layer module
        nullRadio()     # Radio layer module
        }
start hello

This program can be compiled by invoking the Swift Fox Compilers (sfc), as follows:

user@linux $ sfc hello.sfp
user@linux $

More information about the Swift Fox compilation can be found here.

After successful compilation, the hello.sfp is combined with the Fennec Fox modules and is ready to be compiled together with TinyOS to create an embedded firmware. This compilation step is mote-platform dependent, and one should follow the Fennec Fox compilation instructions. For quick example, to compile and install the hello.sfp program on a telosB mote, one would run the following command:

user@linux $ fennec telosb install

For Zolertia Z1 mote, the complete sequence of compiling the Swift Fox program, and then compiling the Fennec Fox platform together with the TinyOS, would require the following steps:

user@linux $ sfc hello.sfp
user@linux $ fennec z1 install

Each Swift Fox program consists of the following sections:

1. Process declarations
2. Network state declarations
3. Event declarations
4. Policy declarations
5. The initial state declaration

The following is an example of a process declaration:

configuration hello { blink(1, 500)     # Application layer module
        nullNet()       # Network layer module
        nullMac()       # MAC layer module
        nullRadio()     # Radio layer module
        }

Here, configuration is the keyword starting a statement that declares a new process. In this example, the process is named hello. This process runs blink applications, on top of the empty network protocol, empty MAC protocol and empty Radio driver. Each process must declare all four modules running on the four layers of the Fennec Fox network protocol stack. Therefore, when no module should run on a given layer, we fill those layers with null modules.

Swift Fox is a programming language under development since Fall 2009. It aims to be background compatible with the past versions since its origin, and therefore it has some naming/keyword redundancies. In Swift Fox, we can declare a process using not only the configuration keyword, but also using conf, process, and proc.

The network process declaration syntax is the following:

[configuration|conf|process|proc] <proc_name> { <application_module_name>( <application_module_parameters> ) 
        <network_module_name>( <network_module_parameters> )
        <mac_module_name>( <mac_module_parameters> )
        <radio_module_name>( <radio_module_parameters> )
}

At run-time, a network running with Fennec Fox is associated with a state. A state specifies the network protocols that should be running when the network enters the state. A network can run none, one, or multiple network processes.

The following is an example of a network state that runs no processes:

state empty_state { }

and the following is an example of a network state running with the hello process declared above:

state welcome { hello }

where state is the keyword starting the statement declaring a new network state, followed by the name of the state, which here is welcome, and followed by a list of the processes names. In this example, the state consists of one processes called hello.

The following is the network state declaration syntax:

state <state_name> { <process_name>* }

Each Swift Fox program must conclude with the initial state statement. This statements says which of the multiple states the network can be in, should be the first, right after motes are powered on.

The following is an example of a initial state statement.

start welcome

This statement consists of the start keyword, followed by the name of the network state, which in this example is welcome. The initial state declaration has this syntax:

start <state_name>