NanoStack Manual. NanoStack Manual. v Sensinode Ltd. 1/16

Transcription

1 NanoStack Manual v Sensinode Ltd. 1/16

2 Table of Contents 1 Introduction Supporting documentation NanoStack Directory Structure Installation NanoStack FreeRTOS The Stack IEEE LoWPAN NanoMesh Simple Sensor Interface (SSI) nrp Building NanoStack Required tools Creating applications NanoStack PC Tools nroute nroute daemon nrp nroute client interface Client applications nping SSI browser Wireshark support Creating custom applications Example applications v1.0.1 Release Notes Change log v > v Change log v > v Known issues...14 Appendix A: nroute Config Table...15 v Sensinode Ltd. 2/16

3 Introduction 1 Introduction This manual describes NanoStack 1 operation and tools for personal computer platforms. NanoStack is a flexible 6LoWPAN protocol stack for wireless sensing and control using low power devices. The architecture is made up of the NanoStack framework which runs on the embedded wireless nodes, and drivers and tools for accessing the wireless nodes from a PC. This manual covers the functionality and use of NanoStack and its PC tools. For detailed programming information see the NanoStack Reference Manual. Figure 1: The NanoStack architecture. 1.1 Supporting documentation The following sources of information will assist you in using this manual. NanoStack Reference NanoStack Doxygen Reference (in /Docs) Sensinode nrp Specification Sensinode Micro and Nano data sheets 6LoWPAN IETF specifications SSI specification C programming references Make and gcc or sdcc documentation 1 NanoStack is a trademark of Sensinode Ltd. v Sensinode Ltd. 3/16

4 NanoStack Directory Structure 2 NanoStack Directory Structure NanoStack FreeRTOS Common includes modules Docs Platform micro nano Examples Tools Contrib FreeRTOS v4.x (installed separately) NanoStack Common headers Protocol modules Doxygen reference Platform specific drivers Sensinode Micro Series support Sensinode Nano Series support Application examples PC tools for NanoStack 3 rd party contributions 3 Installation Installation instructions are found in the install readme files located in the root directory of the NanoStack source. If you have purchased a Sensinode Devkit, please see the included Quickstart Guide for detailed installation instructions from the included CD-ROM. 4 NanoStack NanoStack is a flexible 6LoWPAN protocol stack with a full IEEE implementation. NanoStack includes 6LoWPAN IPv6 and UDP implementations, ICMP, the IEEE MAC, and the SSI sensor protocol. Custom protocols can be added to NanoStack as protocol elements. NanoMesh multihop forwarding provides automatic multihop capabilities. NanoStack is built on FreeRTOS, an open-source realtime microcontroller operating system. NanoStack provides access to data communications for applications through an easy-to-use Socket interface. The socket interface model is widely used in computer communications, especially in POSIXcompliant systems. Sockets are also a very useful concept for embedded systems. The NanoStack API follows closely the POSIX API and adds memory management features for flexible buffer operations. NanoStack supports both Linux and Windows (Cygwin) development environments using open source tools (gcc, make, sdcc etc.). NanoStack can be used also in GCC and SDCC environments under native windows. Other compilers can be used, but require porting efforts as many embedded compilers use non-standard C constructs. Detailed information on using NanoStack and the Socket API are provided in the NanoStack Reference. v Sensinode Ltd. 4/16

5 NanoStack Figure 2: The internal components of the NanoStack architecture. 4.1 FreeRTOS NanoStack is built upon a stable, portable real-time operating system called FreeRTOS 2. FreeRTOS provides a microkernel with a scheduler, microcontroller specific-code, memory allocation, queues, and semaphores along with system timer functionality. FreeRTOS is portable to a large variety of processor architectures and compilers. For a detailed description of FreeRTOS features, platforms and API documentation, visit the FreeRTOS website at ( NanoStack uses FreeRTOS timing facilities and implements some extensions, such as asynchronous timer service in addition to the basic FreeRTOS API. The FreeRTOS source tree used by NanoStack is not modified, so the user is free to upgrade the FreeRTOS version without the need for update patches for the source code. However a small modification is needed for use with the Nano series. 4.2 The Stack NanoStack is executed as a single task in the FreeRTOS environment. This allows reduced RAM usage and provides an effective way of flow control: protocol modules are always executed sequentially. Stack usage analysis is also simplified, as the protocol modules do not use direct function calls between each other. The main stack loop is responsible for module handler execution. Buffers move along a single buffer queue, which ensures that the user application is not blocked during protocol stack operation. 2 FreeRTOS is a trademark of Richard Barry. v Sensinode Ltd. 5/16

6 NanoStack Figure 3: NanoStack internal components IEEE The IEEE standard specifies a wireless interface meant for wireless embedded applications, such as building automation, industrial automation and other sensing and tracking purposes. The standard is very flexible, allowing from ad-hoc mesh networks to infrastructure based tree topologies. Theoretically up to 64 thousand devices are possible in an topology. The 2.4 GHz physical layer provides a 250 kbps data rate and 15 channels. The IEEE standard is used by both the ZigBee networking stack and 6LoWPAN IP networking. The standard is however independent from the ZigBee special interest group. See the IEEE working group ( and standard for more information. NanoStack currently has built-in radio chip drivers for TI CC2420 and CC2430 radios. These radios implement part of the IEEE standard in hardware. The rest of the IEEE standard is implemented inside NanoStack LoWPAN 6LoWPAN is an IETF specification (RFC 4944) allowing the compressed use of IPv6 and UDP standards over IEEE networks. Normally IPv6 and UDP headers take a lot of space, 6LoWPAN compresses the headers down to a fraction of that, making it ideal for use in wireless sensor networks. In reality 6LoWPAN uses standard UDP and IPv6 applying an adaptation layer. See the IETF 6LoWPAN working group ( and Sensinode 6lowpan tutorials for more information. The NanoStack implementation of 6LoWPAN follows the standard specification RFC An interop testing example used for showing compatibility between 6LoWPAN implementations is included. v Sensinode Ltd. 6/16

7 NanoStack Figure 4: Header size example. 6lowp an Application UDP/ICMP IPv6 LoWPAN MAC PHY ZigBe e Application ZigBee App ZigBee Nwk MAC PHY ZDO IEEE Standard Figure 5: 6lowpan vs. ZigBee stack comparison NanoMesh NanoMesh is Sensinode's forwarding technique for extending a 6LoWPAN network to cover multiple hops. NanoMesh uses the mesh-header feature of 6LoWPAN, implementing a hop-by-hop forwarding algorithm. Unlike ad-hoc mesh routing algorithms such as AODV, NanoMesh does not do explicit route discovery and path setup. Instead the algorithm uses a combination of overhearing and limited flooding to make forwarding decisions. The algorithm makes use of the built-in neighbor and routing table features of NanoStack. NanoMesh supports self healing and the discovery of gateways. For limited size networks (2-3 hops) with fast mobility or topology changes, NanoMesh is an excellent technique Simple Sensor Interface (SSI) The SSI protocol is a generic protocol for discovering and accessing sensors within a sensor network. It provides a way of grouping sensor values such as multiple axes of a single sensor instance, a unified way of describing data formats and unit descriptions. See the SSI specification nrp nrp, the nroute Protocol is used in communication between a host PC and a serial device to allow PC v Sensinode Ltd. 7/16

8 NanoStack access to the local sensor network for network monitoring, system diagnosis and data collection purposes. nrp is discussed in detail in the Sensinode nroute Protocol Specification. nrp is also used in communications between PC tools and nroute over TCP sockets. 4.3 Building NanoStack NanoStack applications are built as follows using the command line in Linux or Cygwin: enter the application directory check Makefile and app.rules for NanoStack options check FreeRTOSConfig.h for FreeRTOS configuration make or make binary will compile the specific application make bsl (Micro Series) or make program (Nano Series) to upload software to the target MCU using USB or serial bootstrap programming. The bootstrap loader option for selecting correct serial port should be added in the app.rules file. Note that the programmer for Nano is included in /Tools/nano_programmer. Type make in this directory to compile the executable. The example make files for Nano use this utility to program Nano devices. Detailed information on configuring NanoStack can be found from the NanoStack Reference Required tools The following tools are required to build and program the example applications: Micro Series (MSP430 processor): msp430-gcc version or later msp430-binutils version with MSP430F1611 support patches or later msp430-libc msp430-bsl Nano Series (CC processor): sdcc version or later with large-stack-auto library Common: GNU make (any recent version) GNU textutils (grep, cat, ls, echo) touch shell (basic shells under Linux, cygwin bash under Windows) A Cygwin distribution must be installed to use Windows tools 4.4 Creating applications The most straightforward way is to take a basic example (micro_example_u100 or nano_example_n120) and copy the directory: v Sensinode Ltd. 8/16

9 NanoStack cp -r micro_example_u100 my_first_application cd my_first_application then edit Makefile: APP=my_first_application and modify app.rules and Makefile for required additional options. Then proceed by editing main.c and to which you can add your own additional source files to SRC += variable in the Makefile 5 NanoStack PC Tools Wireless sensor network application development, debugging, administration, and data mining all benefit from access to these networks from standard PCs. NanoStack comes with a suite of tools for PCs enable interaction with wireless sensor nodes, and examples for creating custom applications. By plugging a USB node into the USB port of a PC, the node receives supply power, and makes a serial port available (with the FTDI USB driver installed). Communication to the wireless network occurs over this serial port using nrp (nroute Protocol). The NanoStack PC tools suite has two main components: the nroute gateway daemon and the different client applications. The purpose of nroute is to enable applications (local or remote) to get data from nodes using a dongle node. Each application can configure nroute to relay data only from specific nodes using a flexible set of parameters. Examples are gives for building these applications, and for creating new custom client applications. 5.1 nroute nroute daemon The nroute daemon (nrouted from now on) is a multi threaded daemon that gives the user a simple interface to the sensor nodes using a dedicated gateway node. The daemon enables the user both to send/receive data and configuration packets from/to the nodes. nrouted sets up a concurrent TCP server which listens for connections to a specified port. The server can be set up to accept connections either from only one interface or from all the interfaces in the system. A remote or local application (depending on which interfaces were configured) can now establish a connection to the nrouted server. If the client application wants to receive data from a node it must first send a nrp nroute configuration packet which the nroute will then process. The nrp nroute configuration packet contains all the necessary information for nrouted to be able to determine which packets the application wants to receive. The nrouted will store all the configurations from different client applications and use them when it receives a nrp packet from the dongle node. Even without this the client application can send nrp packets to nrouted which will relay them to the to the desired node. nrouted will also set up a thread which polls the serial interface with predefined time intervals and upon receiving a valid nrp packet processes it. nroute can be started as a daemon by supplying a [-d] command line parameter to it. Without the parameter nroute will start as an ordinary user space program that can be stopped with a ctrl+c signal. The daemon mode requires root privileges to function properly../nrouted -d v Sensinode Ltd. 9/16

10 NanoStack PC Tools nrouted does most of its logging (if logging is enabled) into a dedicated log file that can be defined in the nrouted.conf. Although the use of this log file requires that quite many steps in the initialization of the nrouted must succeed (e.g. configuration file parsing) the initial logging is done to system logs. In *NIX machines this can be for example /var/log/messages. So if nrouted for example exits before truncating the old log file this is a good place to look for information about what went wrong. The nroute configuration information is stored in a file named nrouted.conf which must be located on *NIX machines in the directory where the nrouted binary is located. If the configuration file is not found from there the program will exit. On Windows machines the file must also be located in the directory where the nrouted binary is located. The configuration file has a [KEYWORD]=[VALUE] structure with each line containing only one keyword-value pair. Any line starting with a hash sign (#) is considered a comment and is not processed in any way. Same line must not contain both comments and a keyword-value pair. All the valid keywords and their descriptions are shown in Appendix nrp The nroute Protocol (nrp) has been defined to be a highly flexible and expandable protocol that yet has a packet format which is simple to create and parse. Due to the high flexibility of the protocol it is used to pass data packets, configuration packets and even MCU debugging information between the nroute daemon on the PC and USB dongle nodes. An overview of nrp and exact packet format description can be found from the Sensinode nrp Specification document nroute client interface The nrouted client interface uses packet formats defined in the nrp Specification document. nroute provides the interface for remote applications to configure nroute to relay data only from selected nodes send arbitrary data to nodes receive arbitrary data from nodes request configuration information from nroute 5.2 Client applications In this section we will take a closer look at the three example client application that use nrouted. There is one general network tool called nping and a data viewing/browsing tool, the SSI browser nping nping (short for nanoping) is a version of normal ping *NIX command that uses the nrouted daemon to ping sensor nodes. The nping application has the default nroute daemon IP address and port number built in ( :21870). These both can be overridden using command line arguments. Although the nping has only a limited subset of the functionality of its *NIX counterparts it still is a very useful tool in administrating a sensor network. The maximum payload is limited to 64 octets. The nping protocol is defined to use the standard UDP echo protocol on port 7. After nping has been started by issuing for example a command./nping -c 3 03:24 v Sensinode Ltd. 10/16

11 NanoStack PC Tools it first creates a TCP socket and tries to connect to the nroute daemon which can be changed by the -S option. If this is successful nping will try to configure nroute to relay all nping traffic from the address 03:24 to nping. If this is successful nping will then start to ping the target with appropriate nudp packets. Because the option -c 3 was used, nping will only send three nping packets. nping supports both 16-bit and 64-bit MAC addresses along with broadcast addresses SSI browser The Simple Sensor Interface (SSI) browser is a SSI protocol compliant tool which can be used to examine and view the services/sensor data provided by a Sensinode. The SSI browser (as do nping and nhttp client) relies on nrouted to provide access to the wireless sensor network. The SSI protocol is a very flexible method to pass sensor data and descriptions of the data with low overhead. The SSI-Browser client is run with the following command./ssi-browser FE:54:EB:DA:4B:34:ED:23 As with the nping client, -s can be used to specify the TCP port of the nroute daemon. The SSI-Browser will use nroute and the USB Dongle Node to discover all sensors for the node with that MAC address and periodically request and display all sensor values. 5.3 Wireshark support Wireshark and libpcap with IEEE Sensinode support is available as a separate package at A new feature in NanoStack is the support of the Wireshark open-source protocol analyzer ( The Sensinode Wireshark solution is made up of a microcontroller application for Micro.2420+Micro.USB called micro_libpcap, libpcap and Wireshark. micro_libpcap provides a direct radio interface for all radio traffic. libpcap runs on the PC and accesses the USB serial port collecting all traffic. Wireshark with IEEE support then uses libpcap to display all network activity. 5.4 Creating custom applications Creating custom applications that can use the interface provided by nrouted might seem quite complicated at first sight but is actually extremely straightforward. At the moment writing such an application is relatively easy but a potentially slightly tedious task. This will be made much easier in the near future as the NanoStack releases will soon include a separate library that contains definitions, macros and functions that are commonly needed in nroute client applications. Nevertheless we will now go through the main steps that are required to create a functional custom nroute client application. The steps below assume that the application wants to send data to sensor node and also to receive data from it. With some knowledge from UNIX sockets and C programming it is quite easy to follow these steps and look through for example the source code of the nping tool. It is also recommendable to have the nrp specification at hand to be able to decipher the different packet types and Tags. We also assume that there is some custom application running on the sensor node and that the programmer knows which port numbers this application uses to send nudp packets. v Sensinode Ltd. 11/16

12 NanoStack PC Tools 1. The first step is to decide the filters which will be used to configure nrouted. The user can for example configure the nrouted to forward all data arriving to a specific port. 2. The first step in writing the actual code is to create a TCP socket and to connect to a running nroute daemon. 3. After the TCP connection is successfully done the time is to prepare a configuration packet according the rules that were decided in step Send the nrouted configuration packet, wait for reply and process it when received. If reply indicated that everything is ok, then nrouted is ready to forward packets. 5. Now the program can send data to a sensor node by creating a valid packet and simply writing it to the socket. 6. If the sensor node application should answer to the packet somehow, the nroute client application can now wait and try to read from the socket. When deciding the configuration for nrouted the programmer should keep in mind the possible limitations that the nroute implementation has. 5.5 Example applications NanoStack has 5 example applications in the NanoStack/Examples directory. To use an example plug the device to be programmed into the Devboard, go to the example directory of choice and type make bsl. Micro series nodes can be programmed also through the Micro.USB board. NanoRouter N600 can be programmed through its USB interface directly. The same programmer is used for programming all, and is invoked by make bsl. nano_example_n120: A basic example of using NanoStack on the Nano Series with an interactive terminal (press 'h' for help). nano_skeleton: Minimalistic skeleton to use in getting started with new apps. nano_sensor_n710: provides an example of using the SSI server module with the N710 NanoSensor device, and how to use the LEDs, buttons and sensors. nano_usb_n600: provides UART access to the radio for nroute running on a PC: receives and transmits MAC packets allowing PC tools to access devices. micro_example_u100: A basic example of using NanoStack on the Micro Series with an interactive terminal (press 'h' for help). micro_skeleton: Minimalistic skeleton to use in getting started with new apps. micro_usb_u600: provides UART access to the radio for nroute running on a PC: receives and transmits MAC packets allowing PC tools to access devices. micro_sensorio_a500: provides an example of using the SSI server module. Sensor values are provided by the sensor example board: illumination, temperature, buttons and LED states are provided. Compatible with SSI-Browser from the PC tools. micro_led_control_a500: provides an example of using two nodes to control the LEDs of the other using buttons. Requires the Sensor Example A500 board on both nodes. micro_compass_u510: offers the same functionality as the micro_sensorio_a500 application using sensor information from the Micro.Compass U510 board. v Sensinode Ltd. 12/16

13 NanoStack PC Tools micro_beacon_client: provides a 6LoWPAN protocol stack with running in beacon-enable client mode. Example includes use of the NWK-MANAGER module which handles PAN discover and association. Uses an interactive terminal (press 'h' for help). micro_beacon_coordinator: provides a 6LoWPAN protocol stack with running in beaconenable coordinator mode. Example starts a PAN-network using the NWK-MANAGER module. Uses an interactive terminal (press 'h' for help). micro_gateway: provides a 6LoWPAN protocol stack with running in beacon-enable gateway mode. Coordinators form a multihop network and can discover routes to gateways using NanoMesh. micro_6lowpan_interop: an application which tests the required features for 6LoWPAN interoperability between vendors using an interactive terminal (press 'h' for help). Supports Level 0 and Level 1 (draft-hui-6lowpan-interop-00). micro_libpcap: for use with Wireshark and libpcap tools. micro_libpcap is programmed to a Micro.USB node and provides a direct radio interface to libpcap running on the PC side. 6 v1.0.1 Release Notes This section gives an overview of major release notes. 6.1 Change log v > v Simplification of the NanoStack initialization routines, now supporting a default option using NULL as a parameter to stack_start(). 2. Radio driver performance improvements, both for Micro and Nano. 3. Full Nano Series device support. 4. New MAC implementation for Nano. 6.2 Change log v > v LoWPAN improved for interoperability levels 0 and NanoMesh improvements are included in this release including self-healing and the use of ICMP messages. 7. ICMP echo, router solicitation and router advertisements are supported. 8. Nano support included in the release, including basic and 6LoWPAN/UDP/ICMP modules. 9. app.rules configuration simplified considerably. 10. stack_start() function added to explicitly configure NanoStack at run-time. 11. Initial Wireshark support is added. 12. Code optimized in all modules for more compact ROM/RAM usage. v Sensinode Ltd. 13/16

14 v1.0.1 Release Notes 6.3 Known issues 1. SDCC/8051 produces inefficient code size because of pointer use by FreeRTOS. For this reason not all and 6lowpan features fit into a build. Issue will be improved during NanoStack 1.X releases and completely fixed in NanoStack 2.X with a static scheduler. 2. 6LoWPAN fragmentation/reassembly is not yet supported in this release. 3. IEEE guaranteed time slots not supported in this release. 4. IEEE superframe support in beta status. v Sensinode Ltd. 14/16

15 Appendix A: nroute Config Table Appendix A: nroute Config Table v Sensinode Ltd. 15/16

16 Appendix A: nroute Config Table WORKDIR KEYWORD DESCRIPTION RANGE DATATYPE EXAMPLE/NOTES SERIALPORT SERIALBUFSIZE TCPADDR TCPPORT TCPMAXCONN TCPALLOWMULTI USELOGGING LOGLEVEL LOGFILE LOGSTATS STATFILE STATINTERVAL The directory where nroute will store log files etc. The device file that can be used to access the Gateway node. The number of nrp packets that the nroute will be able to buffer. The local IP address where the TCP server will be bound. The port number that the TCP server will be listening to. The number of concurrent TCP connections that the server will accept. Whether to allow multiple TCP connections from same remote IP address. This defines if logging is used. Amount of logging information. The name (and path) of the log file. This parameter defines if statistics logging is used. The file name (and path) where to store the statistics. The time interval how often the statistics are updated into the stat file. Any directory where the user that started nroute has write permissions. Any character device file that the user has permission to read&write. In theory this is limited only by the amount of physical memory of the machine but because of acceptable latencies <20 should be used. Any local network interface that has an IPv4 address. Character string. Character string. Integer Character string /var/tmp/nroute /dev/ttyusb Integer Integer The upper limit is there only because of the internal datatype (unsigned char) that is used to store the variable value. [0,1] Integer 0: only one connection per address. 1: multiple connections allowed [0,1] Integer 0: logging disabled. 1: logging enabled [0,1,2] Integer 0: only minimal log output. 1: medium output. 2: extensive log output (debugging). Use lvl. 2 with caution. Any directory where the user has write permissions. Character string If the file already exists, the file will be truncated (i.e. all the existing data will be deleted). [0,1] Integer NOTE: The statistics logging functionality is due in next release. Any directory where the user has write permissions. Character string. NOTE: The statistics logging functionality is due in next release. [1-255] Integer NOTE: The statistics logging functionality is due in next release. The units used are seconds. v Sensinode Ltd. 16/16