SLIPstream is simple mechanism based on the Serial Line IP (SLIP) protocol to connect sensor nodes to Unix socket programs. 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:

Block Diagram

SLIPstream uses a modified version of the SLIP (serial line IP) protocol described 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:

SLIP packet format diagram

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.

STEP 1: Add 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
 1
 2// If you are reading data, the node cannot sleep or it will not wakeup in time
 3#define NRK_NO_POWER_DOWN
 4
 5// This must be greater than or equal to the highest priority task that uses
 6// the serial port (i.e. print of nrk_kprintf)
 7#define SLIP_PCP_CEILING                18     
 8
 9// Enable buffered and signal controlled serial RX
10#define NRK_UART_BUF                    1
11// Set buffer to MAX slip packet size.
12// This could be smaller than 128 if you are careful.
13#define MAX_RX_UART_BUF                 128
14
15// Slip uses a single semaphore to control UART access
16#define NRK_MAX_RESOURCE_CNT            2

STEP 2: Add the following in your makefile:

1SRC += $(ROOT_DIR)/src/net/slip/slip.c
2
3...
4
5EXTRAINCDIRS += $(ROOT_DIR)/src/net/slip
6

STEP 3: Use the following functions in your Nano-RK code running on the node:

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:

1slip_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:

1while (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.

1// Remember not to declare large buffers locally
2uint8_t slip_tx_buf[MAX_SLIP_BUF];
3...
4sprintf (slip_tx_buf, "Hello %d", cnt);
5len = strlen (slip_tx_buf);
6slip_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.

 1int8_t v;
 2// Remember not to declare large buffers inside functions. (protect your stack)
 3uint8_t slip_rx_buf[MAX_SLIP_BUF];
 4...
 5v = slip_rx (slip_rx_buf, MAX_SLIP_BUF);
 6 if (v > 0) {
 7     nrk_kprintf (PSTR ("Task got data: "));
 8     for (i = 0; i < v; i++)
 9        printf ("%c", slip_rx_buf[i]);
10     printf ("\r\n");
11     }
12else
13     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 SLIPstream-client project. These functions are wrappers around UDP messages. For an example of using raw UDP see the SLIPstream-client-UDP project.

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

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:

1int v;
2
3v=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.

1sprintf (buffer, "This is a sample slip string: Count %d\n", cnt);
2
3v=slipstream_send(buffer,strlen(buffer));
4if (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.

1v=slipstream_receive( buffer );
2if (v > 0) {
3  printf ("Got: ");
4  for (i = 0; i < v; i++)
5    printf ("%c", buffer[i]);
6  printf ("\n");
7}

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.

block-diagram.png - Block Diagram (22.8 kB) Anthony Rowe, 06/28/2007 02:42 pm

SLIP-packet.png - SLIP packet format diagram (17.9 kB) Anthony Rowe, 06/28/2007 02:50 pm

slip-stream-car.png (96 kB) Anthony Rowe, 06/28/2007 02:54 pm