Sensinode Reference Nanostack v1.0.1

  • Published on
    05-Mar-2015

  • View
    69

  • Download
    2

Embed Size (px)

Transcript

NanoStack Reference

NanoStack Reference

v1.0.1

2007 Sensinode Ltd.

1/11

NanoStack Reference

Table of Contents1 Introduction.....................................................................................................................................................3 2 NanoStack Configuration Files.......................................................................................................................3 2.1 FreeRTOS configuration.........................................................................................................................3 2.2 NanoStack configuration.........................................................................................................................3 3 Starting NanoStack.........................................................................................................................................5 4 NanoStack Communication Basics.................................................................................................................7 4.1 Creating a socket.....................................................................................................................................7 4.2 Ports.........................................................................................................................................................7 4.3 Address structure ....................................................................................................................................7 4.4 Receiving.................................................................................................................................................8 4.5 Sending....................................................................................................................................................8 4.6 Control Sockets.......................................................................................................................................9 4.7 Notes on application design....................................................................................................................9 5 NanoStack Run-time Configuration.............................................................................................................10 5.1 Function APIs........................................................................................................................................10 5.2 Routing..................................................................................................................................................10 5.3 Routing errors........................................................................................................................................11 6 Port-specific notes.........................................................................................................................................11 6.1 GCC compiler notes..............................................................................................................................11 6.2 SDCC compiler notes............................................................................................................................11

v1.0.1

2007 Sensinode Ltd.

2/11

NanoStack Reference

Introduction

1 IntroductionThis document is intended to help NanoStack software developer in writing applications and getting NanoStack configured to suit their application requirements. This reference covers NanoStack configuration, FreeRTOS configuration, stack initialization, socket API usage, and run-time configuration. Please also see the Doxygen reference in /NanoStack/Docs for more detailed information on function parameters and data structures.

2 NanoStack Configuration FilesNanoStack has multiple layers of configuration: compile-time preprocessor definitions can be divided into two categories: FreeRTOS configuration and NanoStack protocol stack configuration. NanoStack also has multiple APIs for the run-time configuration of drivers and protocol modules.

2.1

FreeRTOS configuration

The FreeRTOS configuration file is named FreeRTOSConfig.h. It is located in the application directory e.g. /NanoStack/Example/micro_example_u100. Table 1: FreeRTOS relevant parameters.Parameter configCPU_CLOCK_HZ configTICK_RATE_HZ configMINIMAL_STACK_SIZE configTOTAL_HEAP_SIZE Description System clock frequency in Hz System timer tick resolution in Hz Stack minimum size in bytes Size of dynamic memory area Options Default Platform dep. 1000 200 RAM size - 2kB

2.2

NanoStack configuration

The NanoStack configuration file is named app.rules, and is located in the application directory along with Makefile, FreeRTOSConfig.h etc. The app.rules file has defaults for all parameters except MAC_MODE, which always must be set. Binary options use 1 for on and 0 for off. Table 2: General configuration parameters.Parameter STACK_BUFFERS_MAX STACK_BUFFERS_MIN SOCKETS_MAX HAVE_DEBUG HAVE_EVENT_TIMERS HAVE_POWERSAVE Description Upper limit for allocated buffers Minimum amount of allocated buffers Amount of available sockets Enable debugging library on UART Number of available event timers Turn on automatic powersave features (experimental) Options Max 10 Min 4 6 4 4 1 8 0 Default

v1.0.1

2007 Sensinode Ltd.

3/11

NanoStack Reference

NanoStack Configuration Files

Table 3: Module selection.Parameter HAVE_CUDP HAVE_ICMP HAVE_CIPV6 HAVE_ROUTING HAVE_RF_802_15_4 HAVE_SSI HAVE_802_15_4_RAW Description Enable compressed UDP module Enable ICMP module Enable compressed IPV6 module Enable routing functionality Enable full functionality MAC Enable SSI sensor data server Enable minimal MAC (CCA only) Options 1 1 1 1 1 0 0 Default

Table 4: MAC module configuration parameters.Parameter MAC_MODE RX_ON_WHEN_IDLE Description Set the mode of the 802.15.4 MAC Receiver never shuts down Options 0 = Ad-hoc mode 1 = Beacon RFD mode 2 = Beacon FFD mode Default 0

1 7

MAX_PENDING_BUFFER_COUNT Size of the MAC pending queue

Table 5: Routing module configuration parameters.Parameter MAX_NEIGHBOR_COUNT MAX_ROUTE_INFO_COUNT Description Maximum nr. of children/neighbors Maximum nr. of stored routes Options 20 15 Default

Table 6: RF driver configuration parameters.Parameter RF_DEFAULT_POWER RF_DEFAULT_CHANNEL HAVE_RF_LED Description Transmit power (in percent) Default RF channel Enable RF activity led Options 0 - 100 11 - 25 0 = off U100: 1 = green, 2 = red 100 18 0 Default

Table 7: UART driver configuration parameters.Parameter HAVE_UARTx UARTx_RX_BUFFER_SIZE UARTx_TX_BUFFER_SIZE Description Support for UART x enabled Size of UART x receive buffer Size of UART x transmit buffer Options Default platform dep. 8 128

Table 8: Debugging library configuration.v1.0.12007 Sensinode Ltd.

4/11

NanoStack ReferenceParameter DEBUG_RX_LEN DEBUG_TX_LEN Description Size of UART RX buffer Size of UART TX buffer

NanoStack Configuration FilesOptions 8 64 Default

Table 9: Debugging selection.Parameter HAVE_DEBUG Description Turn on debugging, must be enabled to use other debug options below Protocol core tracing Socket API tracing CIPV6 protocol tracing CIPV6 control socket tracing CUDP Protocol tracing Routing module tracing Network manager tracing MAC module tracing RF driver tracing Limited RF driver trace: RX only 1-wire driver tracing Options 0 Default

STACK_DEBUG SOCKET_DEBUG CIPV6_DEBUG CIPV6_CONTROL_DEBUG CUDP_DEBUG ROUTING_DEBUG NWK_CONFIG_DEBUG RF_802_15_4_DEBUG CC2420_DEBUG CC2420_DEBUG_RSSI B1W_DEBUG

0 0 0 0 0 0 0 0 0 0 0

Selecting many tracing sections simultaneously may affect system timings and severely compromise correct protocol functionality.

3 Starting NanoStackAn application based on NanoStack is started in 4 phases:

HW initialization Creating initial tasks Starting the FreeRTOS scheduler Starting NanoStack

HW initialization is performed by the bus_init() function, which is included in /Platform under the correct platform directory. The function typically contains only essential initialization steps, such as configuring the system clock source. Additional initialization may be performed in the main() function in cases where the application does not do all its initialization via driver modules. If the debug library is used, the debug_init(speed) call should be done right after calling bus_init() in the main() function. The main() function is also responsible of initial application task creation. Platform hardware initialization:bus_init();

Example of task creation:static void application_task( void *pvParameters );

Inside the main() function:v1.0.12007 Sensinode Ltd.

5/11

NanoStack Reference

Starting NanoStackNULL );

xTaskCreate( application_task, "App", , , ,

Starting scheduler in the main() function:vTaskStartScheduler();

In this phase execution continues in your application task (or the task with the highest priority, in case you created multiple tasks in main() function). NanoStack is started by the stack_start() function. This function initializes all resources required by the protocol stack core and the RF driver. No NanoStack API calls may be called before the stack_start() function has been executed. The function must be executed inside the application task. If NULL is passed as a parameter stack_start() uses default values for the current MAC mode defined in app.rules.typedef struct { log_dev_type_t uint8_t uint8_t uint8_t uint8_t uint8_t uint8_t } stack_init_t; type; channel; pan_id[2]; short_address[2]; use_sw_mac; mac_address[8]; pending_ttl_time;

The type field specifies one of the following operation modes: AD_HOC_DEVICE BEACON_ENABLE_CLIENT BEACON_ENABLE_COORDINATOR BEACON_ENABLE_GATEWAY Device in ad-hoc mode A client in a coordinated network Network coordinator/router Gateway device, gathering data from coordinators

Valid values for channel are 11-26. The PAN ID and MAC address fields are used to setdevice address for coordinator and gateway devices. Set use_sw_mac to 0 and the MAC address is set automatically, or 1 to set it manually. The pending_ttl_time specifies the time a coordinator will store a data packet for a child device. The time is in multiples of 15 seconds, the default value is 5. A task, such as the application task, runs in an endless for loop. It is important that this for loop spends most of its time sleeping so that the scheduler can handle other tasks. Sleeping occurs when blocking on a queue or semaphore (socket_read() blocks on a queue), or by explicitly calling vTaskDelay() or vTaskDelayUntil(). Simple example skeleton of an application task:static void application_task( void *pvParameters ) { socket_t *app_socket; sockaddr_t sa; buffer_t *buf = 0; debug_init(115200); /*debug functions may be called now*/ debug("Start NanoStack.\r\n"); if(stack_start(NULL)==START_SUCCESS) { debug("Start OK.\r\n"); } app_socket = socket(MODULE_CUDP, 0); sa.port = 253; socket_bind(app_socket, &sa); /*listen to port 253*/ for(;;) { /*wait for packets, timeout 1 second*/ buf = socket_read(app_socket, 1000); if (buf) { /*data received*/

v1.0.1

2007 Sensinode Ltd.

6/11

NanoStack Reference...process data... socket_buffer_free(buf); } } }

Starting NanoStack

/*free buffer*/

See /Examples/micro_beacon_gateway for an example of manually setting all the start_init structure for use with a FFD device acting as a gateway.

4 NanoStack Communication BasicsNanoStack communication features are accessed via the Socket API. The example application code in Chapter 3 contains an example of a basic receiver application.

4.1

Creating a socket

A socket is created by the socket() function call which has 2 parameters: 1. Protocol type: what protocol this socket is going to use, e.g. MODULE_CUDP 2. Handler function: if you prefer implementing reception in a callback fashion, insert your handler function pointer here. A null pointer means callback is not used. After the socket has been created, you can specify additional protocol multiplexer (port number) by calling socket_bind(), again with 2 parameters: 1. Pointer to your socket (returned by call to socket() previously) 2. Pointer to a sockaddr_t struct, containing the port number in the port field If you are about to use your socket only for sending or expect your peer to respond with your address (most client-type applications), calling bind is not necessary. A random port will be allocated when first packet is sent.

4.2

Ports

Port ranges in NanoStack are used identically to ports in any TCP/IP stack. When using UDP in uncompressed mode, the 16-bit port range from 5-65536. When using UDP in compressed mode ports are restricted to a 4-bit range from 61616-61631 as in the 6LoWPAN specification. Ports 1-4 are reserved for use with control sockets.

4.3

Address structure

The address structure used by the Socket API is called sockaddr_t and includes the following fields:typedef struct { addrtype_t address_t uint16_t } sockaddr_t; addr_type; address; port; /*!< Type of address */ /*!< Source or destination address */ /*!< Source or destination port */

The addr_type field defines what kind of address in included, and port field is defined above. The following address types are defined. ADDR_NONE ADDR_802_15_4_LONG ADDR_802_15_4_SHORTv1.0.1

No address 64-bit 802.15.4 address 16-bit 802.15.4 address2007 Sensinode Ltd.

7/11

NanoStack Reference

NanoStack Communication Basics

ADDR_802_15_4_PAN_SHORT ADDR_802_15_4_PAN_LONG ADDR_SHORT ADDR_PAN ADDR_DATA ADDR_BROADCAST ADDR_COORDINATOR

16-bit PAN with 16-bit 802.15.4 address 16-bit PAN with 64-bit 802.15.4 address 8-bit address in octet 0 16-bit PAN-id Attribute-based data-centric query Broadcast address Coordinator address only for Beacon enable mode

4.4

Receiving

Receiving data from a socket has 2 options: 1. using socket_read() 2. using a callback function, given as a parameter to socket() The socket_read() function returns a pointer to a buffer_t structure (data received) or 0 (timed out). The function has 2 parameters: 1. Pointer to your socket (returned by call to socket() previously) 2. Timeout value in milliseconds (a value of 0 can be used to poll the socket) All received buffers must be freed using socket_buffer_free() once the data has been handled. The buffer may also be re-used for sending data: in this case the buffer must not be freed. In case of callback reception, the user has to implement a handler function with the following return type and parameters:portCHAR my_handler_function_name(buffer_t *buffer)

example of a callback function:portCHAR my_handler_function_name(buffer_t *buffer) { /* parse and handle received data here */ /* free buffer */ socket_buffer_free(buffer); return pdTRUE; }

The handler function should never block. The function is called from the protocol stack task: if the function blocks, the protocol core (and dri...