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 (FILE *input_stream, FILE *output_stream, uint8_t echo_flag, uint8_t delay_ms)'''

This function will setup SLIP on the sensor node.  The ''input_stream'' and ''output_stream'' set the file descriptors that

should be used for input and output.  By default, these should be set to "stdin" and "stdout".  The ''echo_flag'' is currently not used, but in the future it will set if automatic echoing should be enabled.  The ''delay_ms'' parameter sets a delay that can be used between individual byte transmissions being sent by the board.  Below is a typical slip_init() call:

{{{

#!c

slip_init (stdin, stdout, 0, 0);

}}}

'''int8_t slip_started ()'''

This function returns 1 once slip has started and 0 if slip has not yet been configured.  This can be used to synchronize tasks that are waiting for another task to call slip_init().  For example:

{{{

#!c

while (slip_started () != 1) nrk_wait_until_next_period ();

}}}

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

This function will transmit the buffer indicated by ''buf'' of length ''len'' using the SLIP protocol.  NRK_OK is returned upon success.  NRK_ERROR is returned if an internal error occured. 

{{{

#!c

// Remember not to declare large buffers locally

uint8_t slip_tx_buf[MAX_SLIP_BUF];

...

sprintf (slip_tx_buf, "Hello %d", cnt);

len = strlen (slip_tx_buf);

slip_tx (slip_tx_buf, len);

}}}

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

This function will block until a slip message has been received and passes the checksum.  The application must pass a buffer ''buf'' with a max length ''max_len'' that it wishes to be filled with any incoming slip data. NRK_OK is returned upon success. NRK_ERROR can be returned if a packet is received, but the checksum fails.

{{{

#!c

int8_t v;

// Remember not to declare large buffers inside functions. (protect your stack)

uint8_t slip_rx_buf[MAX_SLIP_BUF];

...

v = slip_rx (slip_rx_buf, MAX_SLIP_BUF);

 if (v > 0) {

     nrk_kprintf (PSTR ("Task got data: "));

     for (i = 0; i < v; i++)

        printf ("%c", slip_rx_buf[i]);

     printf ("\r\n");

     }

else

     nrk_kprintf (PSTR ("Task data failed\r\n"));

}}}

= 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].

'''Note: After opening a connection, a slipstream_send() is required before any data can be received.'''[[BR]]

This is required because until the server receives a message from the client it has no way of knowing where to send reply packets. This packet could simply be ignored by the node.

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

This function opens up a DATAGRAM socket to the given ''address'' string and UDP ''port''. Setting ''blocking'' to 1 makes future calls to slipstream_send() and slipstream_receive() block until they have received data.  Setting ''blocking'' to 0 makes both functions non-blocking.  Here is an example of opening a non-blocking connection on the localhost machine port 4000:

{{{

#!c

int v;

v=slipstream_open("127.0.0.1",4000,1);

}}}

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

Once a connection is opened data must first be sent to the server so that the reply address of the client is known.  This function sends a buffer ''buf'' of size ''length'' to the SLIPstream server program that then forwards the data to the sensor node.

{{{

#!c

    sprintf (buffer, "This is a sample slip string: Count %d\n", cnt);

    v=slipstream_send(buffer,strlen(buffer));

    if (v == 0) printf( "Error sending\n" );

}}}

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

This function takes a pointer to a buffer where it stores incoming slip messages.  The function returns the size of the message, or 0 if no data is available.  In the non-blocking mode of operation, this function will return 0 if no data is present.

{{{

#!c

  v=slipstream_receive( buffer );

    if (v > 0) {

      printf ("Got: ");

      for (i = 0; i < v; i++)

        printf ("%c", buffer[i]);

      printf ("\n");

    }

}}}

= 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 using printf() 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.  Try starting the components in the order described below.

'''Sensor Node SLIP sample program'''

To compile and download the sample SLIPstream application that runs on the FireFly node:

{{{

  user:> cd nano-RK/projects/basic_SLIPstream

  user:~/nano-RK/projects/basic_SLIPstream> make clean

  ...

  user:~/nano-RK/projects/basic_SLIPstream> make

  ...

  Size after:

  main.elf  :

  section     size      addr

  .data        162   8389120

  .text      19740         0

  .bss        1074   8389282

  .stab      48984         0

  .stabstr   19310         0

  Total      89270

  Errors: none

  Platform: firefly2_2

  -------- end --------

  user:~/nano-RK/projects/basic_SLIPstream> make 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.

If the programmed node is running you should see something like this printed out by the server:

{{{

  Starting up...

  Task3 PID=3

  Task2 PID=2

  Task2 cnt=0

  My node's address is 0

  Task1 PID=1

  Task3

  Task2 cnt=1

  Task2 cnt=2

  Task2 cnt=3

  Task2 cnt=4

  Task2 cnt=5

  Task2 cnt=6

  Task2 cnt=7

  Task2 cnt=8

  Task2 cnt=9

  ...

}}}

'''SLIPstream Client Sample'''

To compile SLIPstream sample client do the following:

{{{

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

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

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

 gcc -c -o slipstream.o slipstream.c -I.

 gcc -o sample-client main.o slipstream.o -I.

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

}}}

To test the SLIPstream server type:

{{{

 ./sample-client localhost 4000

  opening: /dev/ttyUSB0

}}}

If the FireFly node connected to the gateway is running and the SLIPstream server is running you should see:

On the '''client''', messages sent from the FireFly node that are forwarded by the server:

{{{

  Got: Hello 8

  Got: Hello 9

  Got: Hello 10

}}}

On the '''server''', you see messages sent from the client that the FireFly node echos back using printf:

{{{

  Task3

  Task2 cnt=53

  Task2 cnt=54

  Task3 got data: This is a sample slip string: Count 6

  Task3

  Task2 cnt=55

  Task2 cnt=56

  Task3 got data: This is a sample slip string: Count 7

  Task3

  Task2 cnt=57

  Task2 cnt=58

  Task3 got data: This is a sample slip string: Count 8

  ...

}}}

= Another Example =

The bmac_slipstream example project (nano-RK/projects/demo_samples/bmac_slipstream) shows how sensors can be sent 1-hop to a gateway node which in turn forwards a packet over SLIPstream to a client. 

The components are as follow:

 * client

  * Client node program to be flashed on a FireFly node sending data to the gateway

  * make with "make NODE_ADDR=<node num>" to identify node

 * gateway

  * gateway code for running on the FireFly node that is connected to the gateway computer

 * SLIPstream-client

  * simple SLIPstream-client example that connects to the SLIPstream-server and prints out incomming data packets

 * SLIPstream (standard server from above)

  * SLIPstream server that forwards SLIP and UDP packets

When correctly operating, the SLIPstream-client should print packets from the client FireFly node with the following string:

"S ''mac_addr'' ''battery'' ''light'' ''temperature'' ''mic'' ''adxl_x'' ''adxl_y'' ''adxl_z''"

= 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.