btnut/btnode/include/cc/rfc.h File Reference


Detailed Description

Multihop packet-communication library for the CC1000 radio.

Author:
Florian Schuetz <fschuetz@ethz.ch>
This multihop packet-communiction library allows nodes to communicate, even if they are not within each others communication range. RFC works with any routing protocol that provides its functionality through the CC1000 routing interface.

If an application wants to send and receive packets, it should register a packet handler and an error handler with RFC. To do this, it must choose a free port that it attaches to. It then can begin sending packets to other nodes.

Sending packets to other nodes is done byu calling rfc_send(...). This will start a route discovery if no route to the destination is known. As soon as the next hop is known, the packet is sent on it's way. Sending packets works asynchronously, which means that there can be several pending packets for different destinations at the same time. Packets for destinations with an available route a processed right away, they do not have to wait for packets that were queued earlier to finish.

Received packets are delivered to the port listener, if the receiving node is the final destination. If the receiving node is not the final destination, it is forwarded on the route.

In case of error, corrective action is taken. If the node that receives the error is the originating node, the applicatino is informed. If it is not, The packet is silently discarded. There exist hooks in the source code, that allow to easily add end-to-end and intermediate node error reporting. This should be implemented in the next version.

When reading the sourcecode, you will find IMPROVE-tags. This means, that the source code could/should be improved at this point in a later version.

#include <sys/types.h>
#include <cc/ccc.h>
#include <sys/mutex.h>
#include <led/btn-led.h>
#include "routing.h"

Data Structures

struct  rfc_packet_handler_st
struct  rfc_packet_st

Defines

#define RFC_DESTINATION_UNREACHABLE   5
 State that marks a destination as unreachable (packets are dropped).
#define RFC_ERROR_RECV_QUEUE_FULL   -1
 Error that is returned, when the receive queue is full.
#define RFC_ERROR_SEND_QUEUE_FULL   0xFFFF
 Error that is returned, when the send queue is full.
#define RFC_FLAG_ACK   2
 If set, this packet must be acknowledged by it's final destination.
#define RFC_FLAG_NEXT_HOP_ACK   1
 If set, this packet must be acknowledged by next hop.
#define RFC_LED_DATA   LED2
 Defines which led to use to show where data lies.
#define RFC_NO_ERROR   0
 Standard return value for successfull processing.
#define RFC_PACKET_HANDLER_QUEUE_SIZE   10
 Number of available ports that applications can bind to.
#define RFC_RECV_QUEUE_SIZE   20
 Size of the queue for packets that are received and not yet processed.
#define RFC_RECV_STATUS_BUFFER_SIZE   50
 Size of the status buffer for received packets.
#define RFC_RECV_STATUS_BUFFER_TIMEOUT   30000
 Time in ms that rfc packet information is cached to detect duplicates.
#define RFC_SEND_QUEUE_RETRY_TIMEOUT   300
 Minimum time in ms until send retry if send failed.
#define RFC_SEND_QUEUE_SIZE   10
 Size of the queue for packets to be sent or forwarded.
#define RFC_SEND_RETRY   7
 Maximum number of retries.
#define RFC_STATUS_FAILED   3
 State that marks packet as dropped because of processing errors.
#define RFC_STATUS_PENDING   2
 State that marks packet as waiting for processing.
#define RFC_STATUS_READY   7
 State that marks packet as ready for sending.
#define RFC_STATUS_REJECTED   8
 State that marks packet as rejected by destination.
#define RFC_STATUS_SENT   1
 State that marks packet as successfully delivered to destination.
#define RFC_STATUS_SENT_TO_NEXT_HOP   4
 State that marks packet as successfully sent to next hop.
#define RFC_STATUS_UNDEF   0
 Undefined state.
#define RFC_STATUS_WAIT_NEXT_HOP_ACK   9
 State that marks packet as waiting for an ack of next hop.
#define RFC_STATUS_WAITING   6
 State that marks packet as waiting for a message.
#define RFC_TYPE   23
 Defines the CCC packet type that RFC data packets use.

Typedefs

typedef rfc_packet_handler_st rfc_packet_handler_t
typedef rfc_packet_st rfc_packet_t

Functions

rfc_packet_tnew_rfc_packet (int data_len)
void rfc_deregister_packet_handler (u_char port)
void rfc_enable_ack (char enable_ack)
void rfc_enable_led (int enable_led)
u_short rfc_get_address (void)
u_short rfc_get_mtu (void)
int rfc_init (routing_interface_t *routing_interface)
int rfc_register_packet_handler (u_char port, rfc_packet_handler_t *handler)
void rfc_release (void)
u_short rfc_send (u_short dst, u_char type, rfc_packet_t *pkt)

Variables

u_long rfc_failed_count
 Number of failed RFC packets passing through node.
u_long rfc_recv_count
 Number of RFC packets targeted for this node.


Define Documentation

#define RFC_FLAG_ACK   2

If set, this packet must be acknowledged by it's final destination.

Warning:
Not implemented. Probably this was just waiting for you. ;)


Typedef Documentation

typedef struct rfc_packet_handler_st rfc_packet_handler_t

Structure describing a port listener for an application

Warning:
Make sure that these handler run short, since they block RFC operation and might delay packet processing. In the worst case, this fills the receive buffer and incomming packets will be dropped.
It is good practice to copy received data packets or error messages in a buffer and process them from a separate thread.

typedef struct rfc_packet_st rfc_packet_t

Structure of an rfc packet.

Warning:
Make sure that the data length field and the length of the actual data are entered correctly.

Check the MTU with rfc_get_mtu(). Since RFC does not yet support fragmenting packets, this MUST be done at application level.


Function Documentation

rfc_packet_t* new_rfc_packet ( int  data_len  ) 

Allocates space for a new RFC packet

Attention:
Do not forget to free the space of this packet when you are done. All packets that are sent by RFC will be buffered there, which means that they are not affected by any change you make to the original packet after they have been sent.
Parameters:
data_len [in] length of the data to be transmitted
Returns:
pointer to packet on success, 0 otherwise

void rfc_deregister_packet_handler ( u_char  port  ) 

Deregisters a port listener

Parameters:
type [in] port

void rfc_enable_ack ( char  enable_ack  ) 

Enables data ACKs

Parameters:
enable_ack [in] 0 to disable, 1 to enable

void rfc_enable_led ( int  enable_led  ) 

Enables LED flashing when data is transmitted.

The node's LEDs shines yellow, whenever a data packet is being processed in the node. Whenever a delivery fails, the red LED flashes.

Parameters:
enable_led [in] 0 to disable, 1 to enable.

u_short rfc_get_address ( void   ) 

Returns the configured mac address

Returns:
mac address of the node

u_short rfc_get_mtu ( void   ) 

Get the maximal transfer unit

SHOULD be used to decide maximum size of a packet that can be sent.

Returns:
Maximal payload size of a data packet.

int rfc_init ( routing_interface_t routing_interface  ) 

Initialises the RFC library.

This function initializes the RFC communication library and MUST be called first. You must provide it a valid interface to the routing protocol you want to use. This requires, that routing is already initialized and running.

Warning:
Make sure you have initialized a routing protocoll before you do initialize the RFC layer with this function.
Parameters:
address [in] interface to the routing protocol that RFC should use
Returns:
0 on success, <> 0 otherwise.

int rfc_register_packet_handler ( u_char  port,
rfc_packet_handler_t handler 
)

Registers a port listener

Warning:
Make sure that the handlers run short, since they block RFC operation and might delay packet processing. In the worst case, this fills the receive buffer and incomming packets will be dropped.
It is good practice to copy received data packets or error messages in a buffer and process them from a separate thread.

Parameters:
type [in] packet type to handle
handler [in] packet handler to use
Returns:
received packet.

void rfc_release ( void   ) 

Disable RFC

Warning:
Not yet implemented. Be honest, you don't want to stop RFC anyways. :)

u_short rfc_send ( u_short  dst,
u_char  type,
rfc_packet_t pkt 
)

Sends a Packet to the destination

Calling this starts sending a packet towards its destination. If a packet can not be delivered, the application will be notified, if it has registired an error handler.

Warning:
The end-to-end error reporting functionality is not yet implemented. However, sophisticated hooks exist so that this funtionallity can easily be added (by yourself?)
Attention:
Do not forget to free the packet if you don't need it anymore. This can safely be done since RFC keeps its own, local copies of packets.
Parameters:
dst [in] destination address
type [in] port number at which target application listens
pkt [in] pointer to the packet that should be sent
Returns:
sequence no. on success, -1 otherwise.


Generated on Wed Apr 29 11:12:29 2009 for BTnut System Software by doxygen 1.5.1