FlockLab Tutorial 2: Getting Started and Serial Service
Run your first image on FlockLab. Learn how to configure and set up a test and how to receive test results from FlockLab. See how the serial service can be set up and used.
The "Hello World!" app
The "Hello World!" app is a TinyOS image that runs on Tmote Sky nodes. It has a single purpose: on startup, it writes "Hello World!" to the serial line.
You can download the source code for apps, pre-compiled images and the test configurations for all tutorials from here. The app for this tutorial can be found in the folder 'flocklab_tinyos/apps/tutorials/2_HelloWorld'.
After having downloaded the source code, have a look at it. As you can see, there is no additional code needed to instrument the app for FlockLab. You can either compile the app yourself or use the pre-compiled image in 'build/telosb/main.exe'.
The test configuration
Take now a look at the FlockLab configuration XML which can be found in 'FlockLab_Testconfiguration.xml'. Besides the XML processing instructions there is an element '<testConf>' which is a wrapper for the whole test configuration. The attribute 'xsi:schemaLocation' specifies the location of the XML schema against which all test configurations are validated. If you like, you can download the XML schema and validate your test configurations (e.g. with the Linux tool xmllint). However, validation can be done directly from within the FlockLab web interface.
The XML element '<generalConf>' is mandatory for every test. It defines the name of a test (with an optional description), when the test is to be carried out and whether or not results should be sent to the user by email. For this test, we define with the block
that the test should be carried out as soon as possible in the first available slot of the testbed and that the test has a duration of 10 seconds. If you wanted to start the test at a specific point in time, you can use the '<scheduleAbsolute>' element. Please see the XML documentation for further details.
We further specify with the element
that test results should be sent by email to us once the test is finished. It has to be noted that this only works with tests that generate a small number of results as for more comprehensive tests, the data would be too big to be sent by email. Tests results are always (regardless of their size) available to download from the Flocklab web interface and the WebDAV directory.
The next (mandatory) element is 'targetConf'. This element defines the target images to be used. There are basically two possibilities to specify target images (with exceptions for the IBM Moterunner OS):
'dbImageId': used to reference images already uploaded to the FlockLab database.
'embeddedImageId': with this element, images can be embedded directly into the test configuration XML (see tutorial 3). The image is then uploaded into the Flocklab database and assigned a Image ID (which then can be used to reference the image in a further test using the element 'dbImageId').
Other elements of '<targetConf>' are '<obsIds>' which defines the list of observers to use for the test (a list of available observer IDs can be found in the web interface under 'FlockLab Status') and '<voltage>' which is the voltage on which the targets should run (1.8V to 3.3V in 0.1V steps). For this tutorial we use the same image for every observer but it is of course possible to use different images for different observers which implies the use of several '<targetConf>' blocks. Please note that since we do not know the ID of the image yet, the element '<dbImageId>' contains the value 'CHANGEME' which is invalid.
The remaining elements in the test configuration XML define the services that are to be used. Since the "Hello World!" app just prints a string, the only service we want to use for this tutorial is the serial service which is configured in the block 'serialConf'. We define that we expect to receive ASCII strings over the serial port of the Tmote at a baudrate of 115200. Note that there can be again different 'serialConf' blocks for different observers.
Now that we understand the test configuration XML, let's get ready to run the test.
Uploading target images
The first thing we have to do to run a test is to upload the target image that is being used in this tutorial:
Log into the FlockLab web interface and navigate to 'Manage Images'. You are now presented a list of all the target images that you uploaded so far.
Click 'add new test image' to insert the tutorials' image.
Fill in the required fields:
'Image File (ELF)': The image file (has to be an ELF file - for TinyOS this is the *.exe) is the target image that you compiled (or downloaded with the tutorial archive).
'Name': Fill in an appropriate name for the image, e.g. "Hello world".
'Description': This is an optional field which allows to write some more text about the image than the 'name' field allows. Fill in an appropriate description of the image, e.g. "Hello world app as used in the FlockLab tutorial 2".
'OS'. Choose 'TinyOS' from the list.
'Platform': Choose 'Tmote' from the list.
Now you can upload the image by clicking 'Upload image'. The image is checked against the OS and platform that you specified and if everything went smoothly, a message confirms the upload and the image appears in the list of uploaded images. Note the 'ID' of the image as we will need to specify it in the test configuration XML later.
Now that the image has been uploaded, we can finally run the test.
Verifying and uploading test configuration
Open the test configuration XML ('FlockLab_Testconfiguration.xml') and set the element '<dbImageId>' to the ID that you noted earlier.
Provide the test configuration XML and click 'Validate' to start the validation.
If you filled in the correct image ID in the first step, a message should appear stating that the validation was successfull. Otherwise, you are presented the line numbers and error types to help you find and correct errors.
Now click 'Create test' to create a test directly from within the validation menu. Alternatively, you can navigate to 'manage Tests' and add the test configuration from there.
Once the test is created, you are presented a list of all the past, current and future tests that you registered. The test from this tutorial should be in the list too and ready to run as soon as possible. the field 'Start' indicates the time for which your tests is scheduled. the icons in the field 'State' give some information on the status of your test (if you move your mouse over the icon you should be able to see some more information in the appearing bubble).
if you navigate to the calendar (either by clicking 'Full calendar' in the navigation or by clicking the mini calendar) you are able to see your test marked in red. If there are tests from other users, they are marked with green bars to indicate the occupancy of the testbed. Note that there are 2 additional bars (marked in orange) right before and after your test. Theses bars indicate the time needed by the testbed to set up your test and clean up afterwards. During this time, the testbed is reserved exclusively for your test.
Running a test
Everything you have to do now, is to wait. As soon as your test has been set up, you will receive an email informing you of the success of the setup process or alternatively any warnings or errors that occurred.
Once the test has finished, you will receive another email with the same information about the cleanup process of your test. As soon as the test results are processed (for the test in this tutorial this will take very little time but for tests with e.g. power profiling it can take quite a long time) you will get another email with your test results attached as a *.tar.gz archive.
Interpreting test results
Unpack the archive that you got by email (you can alternatively download it from the web interface by clicking the download icon in the test overview). You will find the following files in it:
'serial.csv': This file contains all the data that was received by the serial service.
'powerprofiling.csv': This file contains all power measurements which were taken by the power profiling service.
'powerprofilingstats.csv': This file contains statistics about the power measurements. This file is for people that are not interested in the exact power measurements but rather in the average power consumption per node.
'gpiotracing.csv': This file contains all the data that was received by the GPIO tracing service.
'gpioactuation.csv': This file contains all the data that was received by the GPIO actuation service.
'errorlog.csv': This file contains all the errors that occurred when running the test.
For this tutorial, there should only be data in the serial and GPIO actuation files. The serial service CSV should contain one line per observer with the received text ("Hello World!"). The GPIO actuation contains two lines per observer stating the time at which the observer was turned on (test start) and off (test stop) respectively. Since we specified a test duration of 10 seconds, the timestamps for every observer should be 10 seconds away.
Deleting tests and images
The last step in this tutorial is to delete the test configuration (and thus the test results) and the corresponding target image. Note that if you do not delete tests, they will be stored for some time (check your individual retention time in the web interface under 'User account') before they are deleted automatically. Also note that deleted tests cannot be restored.
To delete a target image, all tests that use this image have to be deleted first. Thus, the following procedure is to be used:
Click the trash icon next to the test that you want to delete.
Confirm the removal. If you click the checkbox for image removal, the image will be directly remove (if it is not used in another test).
If you didn't delete the image in the previous step, navigate to 'Manage Images' and click the trash icon next to the image to delete. Note that images which are used in tests don't have the trash icon but rather a crossed circle.
The test and its results as well as the target image are now completely removed from FlockLab.
Notes on the Serial Service
The serial service works both ways: a node can send data to an observer, but you can also send data to the node during runtime of the test. For every observer used in a test, a TCP port is opened on the FlockLab server whymper.ee.ethz.ch. You can now connect to theses ports using appropriate tools (e.g. netcat or ncat). You can then send data to the node and you will also receive everything that the node sends over its serial interface. In the test results file for the serial service, all data that you send to the node will be denoted with a w, data sent by the node will be denoted with an r. Note that only one connection can be made to any observer and that access to the port is restricted to the IP address specified in the test configuration XML. The ports opened on the FlockLab server whymper.ee.ethz.ch are calculated as:
Port(TCP) = 50100 + ObserverID
You can thus connect to e.g. Observer 001 using ncat by issuing the following command:
ncat whymper.ee.ethz.ch 50101
Note that all communication between these ports and the respective observers is transparent, meaning that neither the observer nor you as a test user will notice the intermediate software - this allows you to use e.g. the TinyOS serial forwarder without restrictions.