Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Ipolite best effort local broadcast

The ipolite module sends one local area broadcast packet within one time interval.

If a packet with the same header is received from a neighbor within the interval, the packet is not sent.

The polite primitive is a generalization of the polite gossip algorithm from Trickle (Levis et al, NSDI 2004). The polite gossip algorithm is designed to reduce the total amount of packet transmissions by not repeating a message that other nodes have already sent. The purpose of the polite broadcast primitive is to avoid that multiple copies of a specific set of packet attributes is sent on a specified logical channel in the local neighborhood during a time interval.

The polite broadcast primitive is useful for implementing broadcast protocols that use, e.g., negative acknowledgements. If many nodes need to send the negative acknowledgement to a sender, it is enough if only a single message is delivered to the sender.

The upper layer protocol or application that uses the polite broadcast primitive provides an interval time, and message along with a list of packet attributes for which multiple copies should be avoided. The polite broadcast primitive stores the outgoing message in a queue buffer, stores the list of packet attributes, and sets up a timer. The timer is set to a random time during the second half of the interval time.

During the first half of the time interval, the sender listens for other transmissions. If it hears a packet that matches the attributes provided by the upper layer protocol or application, the sender drops the packet. The send timer has been set to a random time some time during the second half of the interval. When the timer fires, and the sender has not yet heard a transmission of the same packet attributes, the sender broadcasts its packet to all its neighbors.

The polite broadcast module does not add any packet attributes to outgoing packets apart from those added by the upper layer.

Channels

The ipolite module uses 1 channel.

Data Structures

struct  ipolite_callbacks
 A structure with callback functions for an ipolite connection. More...
 
struct  ipolite_conn
 An opaque structure with no user-visible elements that holds the state of an ipolite connection,. More...
 

Files

file  ipolite.h
 
    Header file for Ipolite best effort local Broadcast (ipolite)

 

Macros

#define IPOLITE_ATTRIBUTES   IBC_ATTRIBUTES
 

Functions

void ipolite_cancel (struct ipolite_conn *c)
 Cancel a pending packet. More...
 
void ipolite_close (struct ipolite_conn *c)
 Close an ipolite connection. More...
 
void ipolite_open (struct ipolite_conn *c, uint16_t channel, uint8_t maxdups, const struct ipolite_callbacks *cb)
 Open an ipolite connection. More...
 
int ipolite_send (struct ipolite_conn *c, clock_time_t interval, uint8_t hdrsize)
 Send a packet on an ipolite connection. More...
 

#define IPOLITE_ATTRIBUTES   IBC_ATTRIBUTES

void ipolite_cancel ( struct ipolite_conn c)

Cancel a pending packet.

Parameters
cA pointer to a struct ipolite_conn that has previously been opened with ipolite_open().
        This function cancels a pending transmission that has
        previously been started with ipolite_send().
void ipolite_close ( struct ipolite_conn c)

Close an ipolite connection.

Parameters
cA pointer to a struct ipolite_conn that has previously been opened with ipolite_open().
        This function closes an ipolite connection that has
        previously been opened with ipolite_open().
void ipolite_open ( struct ipolite_conn c,
uint16_t  channel,
uint8_t  maxdups,
const struct ipolite_callbacks cb 
)

Open an ipolite connection.

Parameters
cA pointer to a struct ipolite_conn.
channelThe channel number to be used for this connection
maxdupsThe number of duplicates that are allowed to be heard before suppressing
cbA pointer to the callbacks used for this connection
        This function opens an ipolite connection on the
        specified channel. The callbacks are called when a
        packet is received, or when another event occurs on the
        connection (see \ref "struct ipolite_callbacks").
int ipolite_send ( struct ipolite_conn c,
clock_time_t  interval,
uint8_t  hdrsize 
)

Send a packet on an ipolite connection.

Parameters
cA pointer to a struct ipolite_conn that has previously been opened with ipolite_open().
intervalThe timer interval in which the packet should be sent.
hdrsizeThe size of the header that should be unique within the time interval.
        This function sends a packet from the packetbuf on the
        ipolite connection. The packet is sent some time during
        the time interval, but only if no other packet is
        received with the same header.