Contiki Shell
Contents
Introduction
The Contiki Shell is an interactive on-mote UNIX-style shell that allows for text‐based interaction with a sensor node or a network of sensor nodes through a set of commands that can be executed on a UNIX like command line terminal. It has features such as piping data, run in background, file system interaction, network commands, sensor measurement commands and system commands. The shell can be accessed either over a serial USB connection or over a network using Telnet.
Below are the various instances of shells provided in Contiki:
1) example-shell: This shell can be compiled only for the native target, but not on Tmote Sky due to the firmware image size limitation on the Tmote Sky.
2) sky-shell: This shell is a thinned out version, which can be compiled on Tmote Sky nodes, allowing the firmware image to fit the Tmote Sky memory.
3) sky-shell-exec: This shell is a further thinned out version and has features such as the exec command allowing to load and execute ELF files.
4) sky-shell-webserver: This is a shell that features the command sky-all-data, allowing to collect different sensor measurements and network statistics from a Tmote Sky mote.
In this tutorial, we will run the shell over a USB serial connection and will focus on example-shell, sky-shell provided in Contiki source.
Objective
At the end of this tutorial, goal is to make you at ease with the Contiki shell.
I fell in love with the Contiki Shell, I hope at the end you will too :)
You will learn
In this tutorial you will learn about the following topics:
1) How to get a Contiki Serial Shell up and running on Tmote sky nodes.
2) Various Contiki Shell Commands, their usage and Contiki shell programming.
3) How to create your own Shell Commands.
4) How to create your own Shell for Contiki through an example project.
5) You get to execute various fun examples and understand the Contiki shell along the way.
6) Last, but not least, where all the source code for Contiki is located and a code walkthrough.
Sounds exciting ? Game for it ? Let's begin then!
Source Code and Example Projects
Let's figure out where the source code for shell is in Contiki
This folder has all the source and headers for the Contiki Shell
~/contiki-2.7/apps/shell
This folder has the example-shell project
~/contiki-2.7/examples/example-shell
This folder has the sky-shell project
~/contiki-2.7/examples/sky-shell
How to Compile and Install a Contiki shell ?
example-shell is a Comprehensive Shell and can be used for initial development.
Pros: It's compiled on the native target, so you have the flexibility of developing your own shell commands and include it in the shell for further testing. Since, there's no stringent memory constraints on native targets, this project is useful for initial development phase.
Cons: Since this shell has comprehensive set of shell commands, it increases the memory footprint of the firmware and hence can't be compiled on Tmote Sky motes.
Navigate to this path to find the example-shell project : ~/contiki-2.7/examples/example-shell
example-shell.c is the shell file in this project.
*** Each shell_xx_init() adds a set of features to shell, hence if you run out of space while compiling try removing these. ***
These shell_xx_init() are located in contiki-2.7/apps/shell/ in files like shell-filename.c. You can explore the source code to check for what features they come with and what's in it, to make our lives simpler.
/*---------------------------------------------------------------------------*/
PROCESS(example_shell_process, "Contiki shell");
AUTOSTART_PROCESSES(&example_shell_process);
/*---------------------------------------------------------------------------*/
PROCESS_THREAD(example_shell_process, ev, data)
{
PROCESS_BEGIN();
serial_shell_init();
shell_base64_init();
shell_blink_init();
/*shell_checkpoint_init();*/
/*shell_coffee_init();*/
shell_download_init();
/*shell_exec_init();*/
shell_file_init();
shell_httpd_init();
shell_irc_init();
shell_netfile_init();
/*shell_ping_init();*/ /* uIP ping */
shell_power_init();
/*shell_profile_init();*/
shell_ps_init();
/*shell_reboot_init();*/
shell_rime_debug_init();
shell_rime_netcmd_init();
shell_rime_ping_init(); /* Rime ping */
shell_rime_sendcmd_init();
shell_rime_sniff_init();
shell_rime_init();
/*shell_rsh_init();*/
shell_run_init();
shell_sendtest_init();
/*shell_sky_init();*/
shell_tcpsend_init();
shell_text_init();
shell_time_init();
shell_udpsend_init();
shell_vars_init();
shell_wget_init();
PROCESS_END();
}As we see above some of the shell_xx_init() are already commented out, this done on the pretext that these features are not supported on native target.
Compiling and installing the Contiki shell on native target
cd contiki-2.7/examples/example-shell make
Run the Contiki Shell on native target
./example-shell.native
After running the Contiki Shell, you will see the Contiki Shell prompt
user@instant-contiki:~/contiki-2.7/examples/example-shell$ ./example-shell.native Contiki 2.7 started Rime started with address 2.1 MAC nullmac RDC nullrdc NETWORK Rime 2.1: Contiki>
Punch in help on the Contiki Shell prompt to see all the available shell commands in Contiki shell.
help
You can now run any supported shell commands
For example, running echo hello will echo the <text> back on the shell prompt.
2.1: Contiki> echo hello hello 2.1: Contiki>
sky-shell is a thinned out version of Contiki Shell for Tmote Sky motes.
Navigate to this path to find the sky-shell project : ~/contiki-2.7/examples/sky-shell
sky-shell.c is the shell file in this project
*** Each shell_xx_init() adds a set of features to shell, hence if you run out of space on the mote try removing these. ***
/*---------------------------------------------------------------------------*/
PROCESS(sky_shell_process, "Sky Contiki shell");
AUTOSTART_PROCESSES(&sky_shell_process);
/*---------------------------------------------------------------------------*/
#define WITH_PERIODIC_DEBUG 0
#if WITH_PERIODIC_DEBUG
static struct ctimer debug_timer;
static void
periodic_debug(void *ptr)
{
ctimer_set(&debug_timer, 20 * CLOCK_SECOND, periodic_debug, NULL);
collect_print_stats();
}
#endif /* WITH_PERIODIC_DEBUG */
/*---------------------------------------------------------------------------*/
PROCESS_THREAD(sky_shell_process, ev, data)
{
PROCESS_BEGIN();
#if WITH_PERIODIC_DEBUG
ctimer_set(&debug_timer, 20 * CLOCK_SECOND, periodic_debug, NULL);
#endif /* WITH_PERIODIC_DEBUG */
serial_shell_init();
shell_blink_init();
/* shell_file_init();
shell_coffee_init();*/
/* shell_download_init();
shell_rime_sendcmd_init();*/
/* shell_ps_init();*/
shell_reboot_init();
shell_rime_init();
shell_rime_netcmd_init();
/* shell_rime_ping_init();
shell_rime_debug_init();
shell_rime_debug_runicast_init();*/
/* shell_rime_sniff_init();*/
shell_sky_init();
shell_power_init();
shell_powertrace_init();
/* shell_base64_init();*/
shell_text_init();
shell_time_init();
/* shell_checkpoint_init();*/
/* shell_sendtest_init();*/
shell_rime_unicast_init();
shell_collect_view_init();
#if DEBUG_SNIFFERS
rime_sniffer_add(&s);
#endif /* DEBUG_SNIFFERS */
PROCESS_END();
}
/*---------------------------------------------------------------------------*/As we see above some of the shell_xx_init() are already commented out, this done on the pretext that these features if supported will overflow the Tmote Sky memory and the Code will not compile.
Hence, commented out shell_xx_init() which corresponds to specific set of shell commands, will not be available in this shell
Note: However, if we require any shell_xx_init() features, we can uncomment them but we need to make sure the code compiles such that the sky mote memory doesn't overflow.
Compiling and uploading the Contiki Sky Shell on sky motes
To install a shell on the a node, go to the sky-shell, connect a TMote sky to your computer and upload the shell application on the node.
cd contiki-2.7/examples/sky-shell make TARGET=sky sky-shell.upload savetarget
Wait for the compilation and uploading to finish.
To connect to the shell over the USB port, run:
You can now login to the node with the command
make login
Press the return key to get a shell prompt.
After running the Contiki Shell, you will see the Contiki Sky Shell prompt
user@instant-contiki:~/contiki-2.7/examples/sky-shell$ make login using saved target 'sky' ../../tools/sky/serialdump-linux -b115200 /dev/ttyUSB0 connecting to /dev/ttyUSB0 (115200) [OK] SEND 1 bytes 5.0: Contiki>
Punch in help on the Contiki Shell prompt to see all the available shell commands in Contiki shell.
help
You can now run any supported shell commands
For example, running echo hello will echo the <text> back on the shell prompt.
5.0: Contiki> echo hello SEND 11 bytes hello 5.0: Contiki>
Modify sky-shell project for this tutorial
Replace the sky-shell.c file with the following version of sky-shell.c file
Please copy the below source code into the sky-shell.c file
/*
* Copyright (c) 2008, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*
*/
/**
* \file
* Tmote Sky-specific Contiki shell
* \author
* Adam Dunkels <adam@sics.se>
*/
#include "contiki.h"
#include "shell.h"
#include "serial-shell.h"
#include "collect-view.h"
#include "net/rime.h"
/*---------------------------------------------------------------------------*/
PROCESS(sky_shell_process, "Sky Contiki shell");
AUTOSTART_PROCESSES(&sky_shell_process);
/*---------------------------------------------------------------------------*/
#define WITH_PERIODIC_DEBUG 0
#if WITH_PERIODIC_DEBUG
static struct ctimer debug_timer;
static void
periodic_debug(void *ptr)
{
ctimer_set(&debug_timer, 20 * CLOCK_SECOND, periodic_debug, NULL);
collect_print_stats();
}
#endif /* WITH_PERIODIC_DEBUG */
/*---------------------------------------------------------------------------*/
PROCESS_THREAD(sky_shell_process, ev, data)
{
PROCESS_BEGIN();
#if WITH_PERIODIC_DEBUG
ctimer_set(&debug_timer, 20 * CLOCK_SECOND, periodic_debug, NULL);
#endif /* WITH_PERIODIC_DEBUG */
serial_shell_init();
shell_blink_init();
shell_file_init();
shell_ps_init();
shell_reboot_init();
shell_sky_init();
shell_power_init();
shell_powertrace_init();
shell_text_init();
shell_time_init();
shell_collect_view_init();
#if DEBUG_SNIFFERS
rime_sniffer_add(&s);
#endif /* DEBUG_SNIFFERS */
PROCESS_END();
}
/*---------------------------------------------------------------------------*/This will create a sky shell with features or shell commands that we will go through in the next section
Please compile the sky-shell project and upload the sky-shell.upload to the Sky mote and Login to the mote as explained in previous section
If successful you should be able to see the following and get a Contiki shell prompt
user@instant-contiki:~/contiki-2.7/examples/sky-shell$ make TARGET=sky sky-shell.upload savetarget
AR contiki-sky.a
CC sky-shell.c
CC ../../platform/sky/./contiki-sky-main.c
LD sky-shell.sky
msp430-objcopy sky-shell.sky -O ihex sky-shell.ihex
make IHEXFILE=sky-shell.ihex sky-reset sky-upload
make[1]: Entering directory `/home/user/contiki-2.7/examples/sky-shell'
make -k -j 20 sky-reset-sequence
make[2]: Entering directory `/home/user/contiki-2.7/examples/sky-shell'
../../tools/sky/msp430-bsl-linux --telosb -c /dev/ttyUSB0 -r
MSP430 Bootstrap Loader Version: 1.39-telos-7
Use -h for help
Reset device ...
Done
make[2]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell'
make -j 20 sky-upload-sequence
make[2]: Entering directory `/home/user/contiki-2.7/examples/sky-shell'
+++++ Erasing /dev/ttyUSB0
MSP430 Bootstrap Loader Version: 1.39-telos-7
Use -h for help
Mass Erase...
Transmit default password ...
+++++ Programming /dev/ttyUSB0
MSP430 Bootstrap Loader Version: 1.39-telos-7
Invoking BSL...
Transmit default password ...
Current bootstrap loader version: 1.61 (Device ID: f16c)
Changing baudrate to 38400 ...
Program ...
45722 bytes programmed.
+++++ Resetting /dev/ttyUSB0
MSP430 Bootstrap Loader Version: 1.39-telos-7
Use -h for help
Reset device ...
Done
make[2]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell'
make[1]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell'
saving Makefile.target
rm sky-shell.co obj_sky/contiki-sky-main.o sky-shell.ihex
user@instant-contiki:~/contiki-2.7/examples/sky-shell$ make login
using saved target 'sky'
../../tools/sky/serialdump-linux -b115200 /dev/ttyUSB0
connecting to /dev/ttyUSB0 (115200) [OK]
+�{/#+�3++�&�
SEND 1 bytes
5.0: Contiki>
If you don't end up getting the above set of messages on the comand prompt and end up getting the set of messages on command prompt as shown below, then your setup has not been successful
user@instant-contiki:~/contiki-2.7/examples/sky-shell$ make TARGET=sky sky-shell.upload savetarget msp430-objcopy sky-shell.sky -O ihex sky-shell.ihex make IHEXFILE=sky-shell.ihex sky-reset sky-upload make[1]: Entering directory `/home/user/contiki-2.7/examples/sky-shell' make -k -j 20 sky-reset-sequence make[2]: Entering directory `/home/user/contiki-2.7/examples/sky-shell' Done make[2]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell' make -j 20 sky-upload-sequence make[2]: Entering directory `/home/user/contiki-2.7/examples/sky-shell' Done make[2]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell' make[1]: Leaving directory `/home/user/contiki-2.7/examples/sky-shell' saving Makefile.target rm sky-shell.ihex user@instant-contiki:~/contiki-2.7/examples/sky-shell$
This indicates that your Tmote Sky mote is disconnected!!!
Make sure that your Tmote Sky mote is connected and try compiling again and it should work this time :) Did you heave a sigh there?
I did! When I figured out what was going wrong.
Nevertheless, we are All Set and Good to Launch now :) :)
Contiki Shell Commands, their usage and Contiki shell programming
Ready to dive in ?
Everyone needs help at some point in time, don't we? So let's punch in help on the Contiki Sky Shell to figure out what all shell commands are at our disposal and we will take them head on, one at a time :)
You should see a list of all available shell commands as shown below:
5.0: Contiki> help SEND 5 bytes Available commands: ?: shows this help append <filename>: append to file binprint: print binary data in decimal format blink [num]: blink LEDs ([num] times) collect-view-data: sensor data, power consumption, network stats echo <text>: print <text> energy: print energy profile exit: exit shell hd: print binary data in hexadecimal format help: shows this help kill <command>: stop a specific command killall: stop all running commands ls: list files nodeid: set node ID null: discard input power: print power profile powerconv: convert power profile to human readable output powertrace [interval]: turn powertracing on or off, with reporting interval <interval> ps: list all running processes quit: exit shell randwait <maxtime> <command>: wait for a random time before running a command read <filename> [offset] [block size]: read from a file, with the offset and the block size as options reboot: reboot the system repeat <num> <time> <command>: run a command every <time> seconds rfchannel <channel>: change CC2420 radio channel (11 - 26) rm <filename>: remove the file named filename sense: print out sensor data senseconv: convert 'sense' data to human readable format size: print the size of the input time [seconds]: output time in binary format, or set time in seconds since 1970 timestamp: prepend a timestamp to data txpower <power>: change CC2420 transmission power (0 - 31) write <filename>: write to file 5.0: Contiki>
Lets, go ahead and do the simplest first! echo :)
5.0: Contiki> echo howdy contiki shell? SEND 20 bytes SEND 6 bytes howdy contiki shell? 5.0: Contiki>
Contiki Shell Commands
1) Time related Shell commands time [seconds]: output time in binary format, or set time in seconds since 1970. repeat <num> : run a command every time seconds. randwait <maxtime> <command>: wait for a random time before running a command. timestamp: prepend a timestamp to data.
shell-time.c : This file holds all the time related shell commands. You can find the source file in this path ~/contiki-2.7/apps/shell shell_time_init(): This function is used to register time related shell commands with the Contiki Shell.
