Nano-RK

[[Image(slip-stream-car.png)]]

SLIPstream is an emerging standard in sensor networks for IP to sensor node gateway communication. The SLIPstream program allows for terminal style debugging with a transparent bi-directional packet based communication channel.  The SLIPstream server is written in C and should be easily executable on any embedded or desktop Unix based platform.  In its most basic form, the SLIPstream server can act as a terminal program that displays debugging serial messages from a gateway node.  The SLIPstream server also acts as a UDP server that allows PC programs to connect to the socket for datagram communication to a set of SLIP based functions running on the gateway node.  Unlike a simple serial to socket forwarder, the SLIP protocol allows for framing and checksumming of datagram packets going into and out of a sensor node.  Since SLIP packets have special ESC characters, this can co-exist with normal debug messages that transmit ASCII readable text.  UDP packets sent to the SLIPstream server are forwarded on to the node, and any SLIP replies from the node are passed back to the UDP client.  Below is a block diagram showing the components in the architecture:

[[Image(block-diagram.png)]]

SLIPstream uses a modified version of the SLIP (serial line IP) protocol described [http://tools.ietf.org/html/rfc1055 here].  Since we want the system to interact with normal debugging messages, we have added a <START> escape character as well as a checksum and length field.  The maximum transmission unit (MTU) is 127 bytes to match the MTU for the wireless network.  The checksum and size are 7bit values so that they can never be confused with an ESC control sequence.  To avoid synchronization errors, all control codes that appear in the SLIP data payload section are wrapped in escape sequences.  Below is a diagram of the SLIP data format which is used internally by SLIPstream and the Nano-RK slip functions:

[[Image(SLIP-packet.png)]]

There are three main components to SLIPstream.  First there is the SLIPstream server which can be found in the nano-RK/tools/SLIPstream/SLIPstream-server directory.  Second, there is the SLIP module that runs in Nano-RK on the sensor node. This provides your sensor node application with a slip_tx() and slip_rx() function. Lastly, there is a sample UDP client application which would likely be customized for your particular application that can be fond in the nano-RK/tools/SLIPstream/SLIPstream-client directory.

= Nano-RK APIs =

This section describes the Nano-RK related function calls that can be used with SLIPstream.  When adding SLIP to an application, '''it is important to address the following in your nrk_cfg.h''':

 * #define the correct SLIP_PCP_CEILING value

  * This must be set to the priority of the highest priority task that calls printf() or uses the serial port.  This priority is inherited by the task that calls slip_tx() so that no other serial traffic goes into the SLIP packet.  If in doubt, set this to a very high priority.  However, be careful that it is not higher than something important like the network link layer.

 * #define NRK_UART_BUF   1

 * #define MAX_RX_UART_BUF 128

 * Increase NRK_MAX_RESOURCE_CNT by 1

  * This semaphore is used to block multiple tasks from using slip_tx() at the same time.  Typically it is a good idea to keep slip_tx() and slip_rx() localized in one area.

 * SLIP does not increase the task count in the system

{{{

#!c

// This must be greater than or equal to the highest priority task that uses

// the serial port (i.e. print of nrk_kprintf)

#define SLIP_PCP_CEILING                18     

// Enable buffered and signal controlled serial RX

#define NRK_UART_BUF                    1

// Set buffer to MAX slip packet size.

// This could be smaller than 128 if you are careful.

#define MAX_RX_UART_BUF                 128

// Slip uses a single semaphore to control UART access

#define NRK_MAX_RESOURCE_CNT            2

}}}

'''slip_init (stdin, stdout, 0, 0)'''

'''int8_t slip_started ()'''

'''int8_t slip_tx (uint8_t *buf, uint8_t len)'''

'''int8_t slip_rx (uint8_t *buf, uint8_t max_len)'''

= UDP Client APIs =

The following API can be used after including "slipstream.h" in any standard C program running under Unix.  For more information see the [http://www.nanork.org/nano-RK/browser/nano-RK/tools/SLIPstream/SLIPstream-client SLIPstream-client project].  These functions are wrappers around UDP messages.  For an example of using raw UDP see the [http://www.nanork.org/nano-RK/browser/nano-RK/tools/SLIPstream/SLIPstream-client-UDP SLIPstream-client-UDP project].

'''int slipstream_open(char *address,int port,int blocking)'''

'''int slipstream_send(char *buf,int length)'''

'''int slipstream_receive( char *buf)'''

= Testing SLIPstream =

The following section shows how to run the SLIPstream sample program.  This example sends normal printf() statements to the SLIPstream terminal program while periodically sending SLIP messages.  It also echos any received SLIP messages over the normal terminal so that you can verify the reception.  The UDP client program prints out any received SLIP messages and periodically transmits its own SLIP messages that are received and printout out by the sensor node.

'''Sensor Node SLIP sample program'''

'''SLIPstream Server'''

To compile SLIPstream server do the following:

{{{

 user:> cd nano-RK/tools/SLIPstream/SLIPstream-server

 user:~/nano-RK/tools/SLIPstream/SLIPstream-server> make

 gcc -c -o main.o main.c -I.

 gcc -o SLIPstream main.o -I.

 user:~/nano-RK/tools/SLIPstream/SLIPstream-server>

}}}

To test the SLIPstream server type:

{{{

 ./SLIPstream /dev/ttyUSB0 4000

  opening: /dev/ttyUSB0

}}}

In this case, the serial port is /dev/ttyUSB0 and the server is listening on port 4000.

'''SLIPstream Client Sample'''

= Important Notes =

 * FireFly 2 (not 2_2) boards required reduced baudrates to correctly receive data.  At full speed, the CRC will fail and slip_rx() will never return.

 * Make sure to manage flow control going into the boards.  Your PC based UDP program can generate data much faster than the node can consume it.  Typically you should use an application level acknowledge and timeout scheme to deal with flow control.