RF22
Public Member Functions | Protected Member Functions
RF22ReliableDatagram Class Reference

RF22 subclass for sending addressed, acknowledged, retransmitted datagrams. More...

#include <RF22ReliableDatagram.h>

Inheritance diagram for RF22ReliableDatagram:
RF22Datagram RF22 RF22Router RF22Mesh

List of all members.

Public Member Functions

 RF22ReliableDatagram (uint8_t thisAddress=0, uint8_t slaveSelectPin=SS, uint8_t interrupt=0)
void setTimeout (uint16_t timeout)
void setRetries (uint8_t retries)
boolean sendtoWait (uint8_t *buf, uint8_t len, uint8_t address)
boolean recvfromAck (uint8_t *buf, uint8_t *len, uint8_t *from=NULL, uint8_t *to=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
boolean recvfromAckTimeout (uint8_t *buf, uint8_t *len, uint16_t timeout, uint8_t *from=NULL, uint8_t *to=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
uint16_t retransmissions ()

Protected Member Functions

void acknowledge (uint8_t id, uint8_t from)
boolean haveNewMessage ()

Detailed Description

RF22 subclass for sending addressed, acknowledged, retransmitted datagrams.

Extends RF22Datagram to define addressed, reliable datagrams with acknowledgement and retransmission. Based on RF22Datagram, adds flags and sequence numbers. RF22ReliableDatagram is reliable in the sense that messages are acknowledged, and unacknowledged messages are retransmitted until acknowledged or the retries are exhausted. When addressed messages are sent (by sendtoWait()), it will wait for an ack, and retransmit after timeout until an ack is received or retries are exhausted. When addressed messages are collected by the application (by recvfromAck()), an acknowledgement is automatically sent.

The retransmit timeout is randomly varied between timeout and timeout*2 to prevent collisions on all retries when 2 nodes happen to start sending at the same time .

Each new message sent by sendtoWait() has its ID incremented.

An ack consists of a message with:

Part of the Arduino RF22 library for operating with HopeRF RF22 compatible transceivers (see http://www.hoperf.com)

Examples:

rf22_reliable_datagram_client.pde, and rf22_reliable_datagram_server.pde.


Constructor & Destructor Documentation

RF22ReliableDatagram::RF22ReliableDatagram ( uint8_t  thisAddress = 0,
uint8_t  slaveSelectPin = SS,
uint8_t  interrupt = 0 
)

Constructor.

Parameters:
[in]thisAddressThe address to assign to this node. Defaults to 0
[in]slaveSelectPinthe Arduino pin number of the output to use to select the RF22 before accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega)
[in]interruptThe interrupt number to use. Default is interrupt 0 (Arduino input pin 2)

Member Function Documentation

void RF22ReliableDatagram::acknowledge ( uint8_t  id,
uint8_t  from 
) [protected]

Send an ACK for the message id to the given from address Blocks until the ACK has been sent

References RF22Datagram::sendto(), RF22::setHeaderFlags(), RF22::setHeaderId(), and RF22::waitPacketSent().

Referenced by recvfromAck(), and sendtoWait().

boolean RF22ReliableDatagram::haveNewMessage ( ) [protected]

Checks whether the message currently in the Rx buffer is a new message, not previously received based on the from address and the sequence. If it is new, it is acknowledged and returns true

Returns:
true if there is a message received and it is a new message
boolean RF22ReliableDatagram::recvfromAck ( uint8_t *  buf,
uint8_t *  len,
uint8_t *  from = NULL,
uint8_t *  to = NULL,
uint8_t *  id = NULL,
uint8_t *  flags = NULL 
)

If there is a valid message available for this node, send an acknowledgement to the SRC address (blocking until this is complete), then copy the message to buf and return true else return false. If a message is copied, *len is set to the length.. If from is not NULL, the SRC address is placed in *from. If to is not NULL, the DEST address is placed in *to. This is the preferred function for getting messages addressed to this node. If the message is not a broadcast, acknowledge to the sender before returning. You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters:
[in]bufLocation to copy the received message
[in,out]lenAvailable space in buf. Set to the actual number of octets copied.
[in]fromIf present and not NULL, the referenced uint8_t will be set to the SRC address
[in]toIf present and not NULL, the referenced uint8_t will be set to the DEST address
[in]idIf present and not NULL, the referenced uint8_t will be set to the ID
[in]flagsIf present and not NULL, the referenced uint8_t will be set to the FLAGS (not just those addressed to this node).
Returns:
true if a valid message was copied to buf

Reimplemented in RF22Router, and RF22Mesh.

References acknowledge(), RF22::available(), and RF22Datagram::recvfrom().

Referenced by RF22Router::recvfromAck(), and recvfromAckTimeout().

boolean RF22ReliableDatagram::recvfromAckTimeout ( uint8_t *  buf,
uint8_t *  len,
uint16_t  timeout,
uint8_t *  from = NULL,
uint8_t *  to = NULL,
uint8_t *  id = NULL,
uint8_t *  flags = NULL 
)

Similar to recvfromAck(), this will block until either a valid message available for this node or the timeout expires. Starts the receiver automatically. You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters:
[in]bufLocation to copy the received message
[in,out]lenAvailable space in buf. Set to the actual number of octets copied.
[in]timeoutMaximum time to wait in milliseconds
[in]fromIf present and not NULL, the referenced uint8_t will be set to the SRC address
[in]toIf present and not NULL, the referenced uint8_t will be set to the DEST address
[in]idIf present and not NULL, the referenced uint8_t will be set to the ID
[in]flagsIf present and not NULL, the referenced uint8_t will be set to the FLAGS (not just those addressed to this node).
Returns:
true if a valid message was copied to buf

Reimplemented in RF22Router, and RF22Mesh.

References recvfromAck().

uint16_t RF22ReliableDatagram::retransmissions ( )

Returns the number of retransmissions we have had to send

Returns:
The number of retransmissions since initialisation.
boolean RF22ReliableDatagram::sendtoWait ( uint8_t *  buf,
uint8_t  len,
uint8_t  address 
)

Send the message and waits for an ack. Returns true if an acknowledgement is received. Synchronous: any message other than the desired ACK received while waiting is discarded. Blocks until an ACK is received or all retries are exhausted (ie up to retries*timeout milliseconds).

Parameters:
[in]addressThe address to send the message to.
[in]bufPointer to the binary message to send
[in]lenNumber of octets to send
Returns:
true if the message was transmitted and an acknowledgement was received.

Reimplemented in RF22Router, and RF22Mesh.

References RF22Datagram::_thisAddress, acknowledge(), RF22::available(), RF22::clearRxBuf(), RF22::headerFlags(), RF22::headerFrom(), RF22::headerId(), RF22::headerTo(), RF22Datagram::sendto(), RF22::setHeaderFlags(), RF22::setHeaderId(), and RF22::waitPacketSent().

Referenced by RF22Router::route().

void RF22ReliableDatagram::setRetries ( uint8_t  retries)

Sets the max number of retries. Defaults to 3. If set to 0, the message will only be sent once. sendtoWait will give up and return false if there is no ack received after all transmissions time out. param[in] retries The maximum number a retries.

void RF22ReliableDatagram::setTimeout ( uint16_t  timeout)

Sets the minimum retransmit timeout. If sendtoWait is waiting for an ack longer than this time (in milliseconds), it will retransmit the message. Defaults to 200ms. The timeout is measured from the end of transmission of the message. It must be at least longer than the the transmit time of the acknowledgement (6 octets) plus the latency/poll time of the receiver. The actual timeout is randomly varied between timeout and timeout*2.

Parameters:
[in]timeoutThe new timeout period in milliseconds

The documentation for this class was generated from the following files: