MansOS tutorial

Getting MansOS

See MansOS installation guide. For the purposes of this tutorial, you will need:

• MansOS sources. The recommended way is to checking them out from SVN by using command

svn co http://mansos.net/svn/mansos/ mansos

• Development tools, such as msp430-gcc compiler or avr-gcc compiler, with tools and libraries
• Common UNIX command line tools, such as make
• A working Python installation
• At least one mote (Tmote Sky, Arduino, Epic mote, SADmote etc.) on which to run the application
  • Even if no motes are available, you can try out MansOS using built-in simulation platform "pc" (a simulator of sensor motes and their communication)

Building and running your first application

MansOS comes with a set of demo applications. It's a good start to check these first. Go to directory mansos/apps/demo and browse the applications! You may want to start with Blink application - the simplest one. For each application, the code is in the main.c file, it is a plain C code source.

Change location in MansOS root directory to mansos/apps/demo/Blink. Also other application examples are available.

Now compile the application and program it in the device.

For users of Tmote Sky:

make telosb upload

For users of Arduino:

make atmega upload

For users of SADmote:

make telosb upload-msp430

For testing the application in the simulator:

make pc run

The first argument to make program is the platform for which to build. The second argument is all these case if "upload" command, which means "take the produced binary code and program it on a mote".

See MansOS platforms documentation for a more detailed description of different hardware platforms.

See MansOS building documentation for a more detailed description of make targets.

After programming is complete, the mote should now periodically (one change per second) turn one of its LEDs on and off.

The upload command by default tries to upload the application to serial port /dev/ttyUSB0. If your mote is attached to another one, change BSLPORT environmental variable to specify the correct port. For example:

$ export BSLPORT=/dev/ttyUSB1
$ make telosb upload
...
./../../../mos/make/scripts/tos-bsl --telosb -c "/dev/ttyUSB1" -r -e -I -p ./build/telosb/image.ihex

To see to which port the mote is attached you can use motelist utility:

$ motelist
Reference  Device           Description
---------- ---------------- ---------------------------------------------
M4AOQGBQ   /dev/ttyUSB0     Moteiv tmote sky

Debugging an application

Printf-style debugging is the most commonly used form of debugging for WSN motes.

MansOS provides several macros for this:

• PRINTF(format, arguments): analogue of printf() function;
• PRINT(string): just print the string passed as argument; smaller executable size is the one benefit of this version, when compared to PRINTF();
• PRINTLN(string): print the string passed as argument with newline character appended.

By default, output from these macros is sent to serial port.

To see one of these macros in action, change directory to mansos/apps/demo/CounterToSerial, compile and upload the application.

Listening to serial port

To observe the output a program capable to listening the serial port is required. If you don't know what to use, try:

• On Linux or MAC: minicom
• On Windows: putty

Use 38400 as baudrate setting, 8 bits, 1 stopbit, parity none, flow control turned off. Here is a complete minicom configuration file for reference:

pu port             /dev/ttyUSB0
pu baudrate         38400
pu bits             8
pu parity           N
pu stopbits         1
pu rtscts           No 

Configure minicom/putty so that it listens to the serial port a mote is attached (/dev/ttyUSB0 for minicom by default). Compile and upload the CounterToSerial application, and launch minicom:

$ minicom
Welcome to minicom 2.4

OPTIONS: I18n 
Compiled on Jan 25 2010, 06:49:09.
Port /dev/ttyUSB0

Press CTRL-A Z for help on special keys                    
                                                           
counter = 1                                                
counter = 2                                                
counter = 3
counter = 4
...

MansOS also comes with a python script for serial port monitoring: mos/pc/tools/dumpserial/dumpser.py . You can run it as an application. By default, it tries to open port /dev/ttyUSB0 with 38400 baudrate (default serial port speed for MansOS applications). You can open other port by specifying it as a command line argument, for example:

$ mansos/pc/tools/dumpserial/dumpser.py /dev/tty.usbserial-ABCDEFGH

Alternatives to serial port output

Alternatively the printed characters can be sent on air by using radio transceiver. To enable this option, add this line:

CONST_DPRINT_TO_RADIO=1

to application's configuration file. In this case, no output to serial port will be produced. You will need another mote which listens to radio and forwards all messages received to its serial port, i.e. acts as a proxy.

Another alternative: the printed characters can be sent to LCD terminal, if one is attached to the mote.

Analysis of a MansOS application

Let's analyze the CounterToSerial application. There are three files in directory mansos/apps/demo/CounterToSerial:

• main.c - C source file, contains application-specific code
• Makefile - this file is used by GNU make. MansOS make system internally uses so-called "targets" of Makefiles to build the application for different architectures and upload it to different motes. This file specifies:
  • The name of the executable
  • Names of all C source files (application-specific files only)
• config - application-specific configuration file. This file specifies:
  • MansOS components to include and exclude from the application
  • Compile time constants. A constant defined in this file using "CONST_xxx=y" syntax is visible to C preprocessor as xxx=y
  • MCU model, upload baudrate, CPU frequency (CPU_MHZ variable) etc. This file is eventually processed by GNU make - this means that all variables and syntax supported in Makefile is also supported in this file.

File main.c (comments removed):

1: #include "stdmansos.h"
2: 
3: void appMain(void)
4: {
5:     uint8_t counter = 1;
6:     while(1)
7:     {
8:         PRINTF("counter = %u\n", counter++);
9:         toggleRedLed();
10:        mdelay(1000);
11:    }
12: }

Line #1: Include stdmansos.h file, which in turn includes support for majority of MansOS user API

Line #3: Define appMain() function. This function must be present in every MansOS application, in the same way every standalone C program requires main() function to be present. (An exception of this rule regarding MansOS: when USE_KERNELMAIN option is set to n, the usual C rule requiring main() is in power.)

Line #5: Declare a local 8-bit variable called "counter" and initialize it to 1.

Line #6 - #11: The main loop of the program.

Line #8: Print the value of the counter.

Line #9: Change status of the red LED. If it was turned off, it will be turned on, and vice versa.

Line #10: Delay for one second or 1000 milliseconds. If energy efficiency is required, msleep() should be used instead.

Makefile (a fragment):

...
# Sources are all project source files, excluding MansOS files
SOURCES = main.c

# Module is the name of the main module built by this makefile
APPMOD = CounterToSerial
...
ifndef MOSROOT
  MOSROOT = $(PROJDIR)/../../..
endif
...

You should pay attention only to this fragment of the Makefile.

SOURCES is a variable which tells the names of all application-specific source files. For most applications, only one is sufficient.

APPMOD is the name of the application. The name is of no great significance; a generic name like "App" could be used as well.

MOSROOT must contain the path to MansOS root, either relative or absolute. It is an important variable! If MOSROOT is not specified correctly, the application is not going to compile.

config

For CounterToSerial application, the configuration file is empty.

For majority of non-trivial applications, the configuration file needs to be tuned, either by enabling some MansOS options disabled by default, or by disabling option enabled by default - either because your hardware platform does not have these options of for optimization purposes.

For example, humidity sensor support is disabled by default. If the application includes C code that reads the humidity sensor, configuration file must have the line:

USE_HUMIDITY=y

See MansOS configuration options for list of all supported configuration options.

MansOS shell

MansOS comes with a PC command line tool that can be used to control and reprogram the motes in the network, either via serial port or wirelessly.

The shell tool is located under mansos/pc/shell.

The shell features these commands:

ls                              -- list all motes
led (red|green|blue) [on|off]   -- control LEDs
sense                           -- read sensor values
get <OID>                       -- get a specific OID value from all motes
set <OID> <type> <value>        -- set a specific OID to <value>
select [<address>]              -- select a specific mote (no args for broadcast)
load [<file>]                   -- load an ihex file (no args for clear existing)
program [<address>]             -- upload code (from ihex file) on a specific mote
reboot                          -- reboot mote
quit                            -- exit program
help                            -- show this help

To use the shell, support on mote side is required as well. In particular, USE_SMP must be enabled in configuration file. If run-time reprogramming is going to be used, then USE_REPROGRAMMING should be enabled as well.

MansOS contains a few demo examples that can be used in conjunction with the shell. They are located under mansos/apps/tests/SmpTest. Compile and upload them as any other applications; then launch the shell tool on your PC and try it out for yourself.

FAQ

Q. What can be done using MansOS?

A. See the feature list.

Q. How to turn on and off different features of MansOS?

A. The core MansOS can be customized in application-specific way. To turn on an option, use configuration files. Note that most of commonly used options are already turned on by default (such as LEDs, printing to serial port, radio, ADC etc.).

Turning off an option is not normally required. MansOS build system can automatically detect that an option is not used, and prune all code that is related to this option from the final executable. You only need to disable some option in the configuration file in cases when this "smart linking" does not give the expected results, or when a more advanced control over that options is required.

Q. Can MansOS be used just as a library?

A. The philosophy of MansOS includes the idea that "you don't need to pay for what you don't use".

Using MansOS as opposed to writing a program from scratch doesn't entail any additional overhead, because in MansOS the user is not required to enable any of advanced operating system features he doesn't need. Neither parallel execution, scheduler, dynamic memory management, nor any other of MansOS services are mandatory.

For example, the user can disable all advanced algorithms and features by using the configuration file of the application.

Even if that is not enough, then MansOS can be used just as a library or even just as a development environment that provides various tools for compiling and uploading applications.

In fact, a "MansOS application" is not required to have any system code at all. The user can specify USE_KERNELMAIN=n in application configuration file and write his own main() function. If you are going to try this, you may wish to look in mansos/mos/kernel/kernelmain.c to see how system is initialized in the default case to get some ideas what you might need.