RFM73library
 All Classes Functions Typedefs Groups Pages
Macros | Typedefs | Functions
high level interface

Macros

#define RFM73_LIB_VERSION   "V1.03 (2012-11-16)"
 version of this rfm73 library
 
#define RFM73_MAX_PACKET_LEN   32
 maximum number of data bytes in a (received or transmitted) rfm73 packet
 

Typedefs

typedef unsigned char rfm73_buffer [RFM73_MAX_PACKET_LEN]
 type of rfm73 (transmit or receive) buffer
 

Functions

 rfm73::rfm73 (pins::output_pin &sclk, pins::output_pin &mosi, pins::input_pin &miso, pins::output_pin &csn, pins::output_pin &ce)
 constructor: create and RFM73 object
 
bool rfm73::is_present (void)
 report whether the rfm73 module is present
 
void rfm73::mode_transmit (void)
 switch the rfm73 to transmit mode
 
void rfm73::mode_receive (void)
 switch the rfm73 to receive mode
 
void rfm73::mode_standby (void)
 switch the rfm73 to standby mode
 
void rfm73::mode_powerdown (void)
 switch the rfm73 to power down mode
 
void rfm73::lna_low (void)
 set the rfm73 lna gain to low
 
void rfm73::lna_high (void)
 set the rfm73 lna gain to high
 
void rfm73::channel (unsigned char ch)
 set the rfm73 channel frequency
 
void rfm73::air_data_rate (unsigned char rate)
 set the rfm73 air data rate (baudrate)
 
void rfm73::crc_length (unsigned char len)
 set the rfm73 CRC length
 
void rfm73::address_length (unsigned char len)
 set the rfm73 address length
 
void rfm73::power (unsigned char level)
 set the rfm73 transmit power
 
void rfm73::retransmit_delay_attempts (unsigned char d, unsigned char n)
 set the retransmission delay and number of attempts
 
unsigned char rfm73::retransmit_count (void)
 read rfm73 retransmit count
 
unsigned char rfm73::lost_packets_count (void)
 read rfm73 lost packets count
 
void rfm73::lost_packets_reset (void)
 reset rfm73 lost packets count
 
void rfm73::pipe_autoack (unsigned char pipe, bool enabled)
 enables or disables the autoack on a pipe
 
void rfm73::pipe_enable (unsigned char d, bool enabled)
 enables or disables a pipe
 
void rfm73::receive_address_p0 (const unsigned char address[5])
 set the rfm73 pipe 0 address
 
void rfm73::receive_address_p1 (const unsigned char address[5])
 set the rfm73 pipe 1 address
 
void rfm73::receive_address_pn (unsigned char channel, unsigned char address)
 set the rfm73 pipe n (2..5) address
 
void rfm73::channel_payload_size (unsigned char n, unsigned char size)
 set the payload size for pipe n
 
void rfm73::transmit_address (const unsigned char address[])
 set the rfm73 transmit address
 
bool rfm73::transmit_fifo_full (void)
 report whether the transmit fifo is full
 
bool rfm73::receive_fifo_empty (void)
 report whether the receive fifo is empty
 
void rfm73::transmit_message (const unsigned char buf[], unsigned char length)
 transmit a message
 
void rfm73::transmit_message_once (const unsigned char buf[], unsigned char length)
 transmit a message once
 
unsigned char rfm73::receive_next_pipe (void)
 get pipe number of the next message in receive FIFO
 
unsigned char rfm73::receive_next_length (void)
 get payload length of the next message in receive FIFO
 
bool rfm73::receive (unsigned char &pipe, unsigned char buf[], unsigned char &length)
 (try to) receive a message
 

Detailed Description

The high-level interface provides methods for using the rfm73 module. These methods are implemneted by calling the appropriate low level methods. When possible, it is recommended to use only these high level methods. But when a functionality is needed that is missing it can be implemented using the low level interface.

To use any of these methods, (except init() itself) the interface and the module must have been initialized by an init() call.

Macro Definition Documentation

#define RFM73_LIB_VERSION   "V1.03 (2012-11-16)"

version of this rfm73 library

#define RFM73_MAX_PACKET_LEN   32

maximum number of data bytes in a (received or transmitted) rfm73 packet

Typedef Documentation

typedef unsigned char rfm73_buffer[RFM73_MAX_PACKET_LEN]

type of rfm73 (transmit or receive) buffer

Function Documentation

void rfm73::address_length ( unsigned char  len)

set the rfm73 address length

This method sets the length (in bytes) of the addresses used by the rfm73. Valid values are 3, 4 and 5. A value < 3 has the same effect as the value 3. A value > 5 has the same effect as the value 5. This setting is common for all data pipes.

void rfm73::air_data_rate ( unsigned char  rate)

set the rfm73 air data rate (baudrate)

This method sets the air data rate used by the rfm73 for receiving and transmitting. Allowed values are 0 (250 Kbps), 1 (1 MBps) and 2 (Mbps). A value > 2 will have the same effect as a value of 2. Note that this is the bitrate the rfm73 uses in the packages that it sends. Due to various overhead factors the data rate that a user of the module can achieve is much lower, probably by a factor of 4.

void rfm73::channel ( unsigned char  ch)

set the rfm73 channel frequency

This method sets the frequency (channel) used by the rfm73 for receiving and transmitting to ( 2400 + ch ) MHz. The highest bit of val is ignored, so the frequency range is 2.4 .. 2.517 GHz. Not all of these frequencies might be free to use in your jurisdiction.

void rfm73::channel_payload_size ( unsigned char  n,
unsigned char  size 
)

set the payload size for pipe n

This method sets the size (= number of bytes, can be 1..32) for packets to be received on pipe n. This setting must be the same as on the tranmitter. A size of 0 will enable dynamic length packets. A size > 32 will have the same effect as a size of 32.

void rfm73::crc_length ( unsigned char  len)

set the rfm73 CRC length

This method sets the length of the CRC used by the rfm73 in bytes. Valid values are 0 (no CRC), 1 and 2. A value > 2 has the same effect as the value 2. Disabling the CRC disables the auto-acknowledge function. Enabling the CRC does not automatically enable the auto-acknowledge function.

bool rfm73::is_present ( void  )

report whether the rfm73 module is present

This method tests whether the rfm73 module is present. It does so by reading the status register, and verifying that an activate 0x53 command toggles the RBANK bit in the status register.

void rfm73::lna_high ( void  )

set the rfm73 lna gain to high

This sets the LNA gain of the receiver to the so-called 'high' level. (I would have called it the 'normal' level.)

void rfm73::lna_low ( void  )

set the rfm73 lna gain to low

This sets the LNA gain of the receiver to the low level (-20 dB compared to the 'high' level).

unsigned char rfm73::lost_packets_count ( void  )

read rfm73 lost packets count

This method reads and reports the number of lost packets. The range of this count is 0..15, at 15 it will not increment when a next packet is lost. The lost packets count is reset implicitly when the channel is written (by calling channel() ) or explicitly by calling lost_packets_reset().

void rfm73::lost_packets_reset ( void  )

reset rfm73 lost packets count

This method resets the number of lost packets by reading and re-writing the RF channel (RFM73_REG_RF_CH register).

void rfm73::mode_powerdown ( void  )

switch the rfm73 to power down mode

This method puts the rfm73 in power down mode, which reduces the power consumption to a minimum ( 3 uA max).

void rfm73::mode_receive ( void  )

switch the rfm73 to receive mode

This method flushes the receive queue, and switches the rfm73 to transmit mode.

void rfm73::mode_standby ( void  )

switch the rfm73 to standby mode

This method puts the rfm73 in standby I mode, which reduces the power consumption (50 uA max). mode_powerdown() reduces the power consumption even further, but requires a longer (but unspecified?) time to return to active mode.

void rfm73::mode_transmit ( void  )

switch the rfm73 to transmit mode

This method flushes the transmit queue, and switches the rfm73 to transmit mode.

void rfm73::pipe_autoack ( unsigned char  pipe,
bool  enabled 
)

enables or disables the autoack on a pipe

This method enables or disables the auto acknowledgement function on the specified pipe.

pipe must be in the range 0..5. A pipe > 5 has the same effect as using pipe 5.

void rfm73::pipe_enable ( unsigned char  d,
bool  enabled 
)

enables or disables a pipe

This method enables or disables the specified pipe.

pipe must be in the range 0..5. A pipe > 5 has the same effect as using pipe 5.

void rfm73::power ( unsigned char  level)

set the rfm73 transmit power

This method sets the rfm73 transmitter output power level.

  • level == 0 => -10 dBm
  • level == 1 => -5 dBm
  • level == 2 => 0 dBm
  • level == 3 => +5 dBm

A level > 3 has the same effect as level == 3.

bool rfm73::receive ( unsigned char &  pipe,
unsigned char  buf[],
unsigned char &  length 
)

(try to) receive a message

This method tries to receive a message.

This method tries to retrieve a received message from the receive FIFO. When no message is available this method returns false. When a message is avaible it is retrieved. The data is put in the buffer buf, the length is written to length, and the method returns true.

The size of the buffer buf must be at least RFM73_MAX_PACKET_LEN (32).

The RFM73 must be in transmit mode.

void rfm73::receive_address_p0 ( const unsigned char  address[5])

set the rfm73 pipe 0 address

This method sets the (up to 5 byte) receive address of pipe 0. When the address length is set to less than 5 the excess bytes are ignored, but address must still be a 5 byte array.

Pipes 0 and 1 have a full (up to 5) byte address. The other pipes (2..5) copy all but the least significant (= first) byte from the pipe 1 address.

void rfm73::receive_address_p1 ( const unsigned char  address[5])

set the rfm73 pipe 1 address

This method sets the (up to 5 byte) receive address of pipe 1. When the address length is set to less than 5 the excess bytes are ignored, but address must still be a 5 byte array.

Pipes 0 and 1 have a full (up to 5) byte address. The other pipes (2..5) copy all but the least significant (= first) byte from the pipe 1 address.

void rfm73::receive_address_pn ( unsigned char  channel,
unsigned char  address 
)

set the rfm73 pipe n (2..5) address

This method sets the least significant byte of the receive address of the pipe n. The other bytes of the address are copied from pipe 1.

bool rfm73::receive_fifo_empty ( void  )

report whether the receive fifo is empty

This method reads and reports whether the receive fifo is full.

unsigned char rfm73::receive_next_length ( void  )

get payload length of the next message in receive FIFO

This method returns length of the head message in the receive FIFO in bytes (1..32).

The RFM73 datasheet does not specify the value that is returned when the receive FIFO is empty

unsigned char rfm73::receive_next_pipe ( void  )

get pipe number of the next message in receive FIFO

This method returns the number of the pipe (0..5) on which the head message in the receive FIFO was received.

When the receive fifo is empty 0x07 is returned.

unsigned char rfm73::retransmit_count ( void  )

read rfm73 retransmit count

This method reads and reports the number of retransmissions for the last packet that was sent. The number of retransmissions is reset to zero when a new packet is sent.

void rfm73::retransmit_delay_attempts ( unsigned char  d,
unsigned char  n 
)

set the retransmission delay and number of attempts

This method sets the delay d between retransmission attempts, and the maximum number of attempts n. The range of both arguments is 0..15. A value > 15 has the same effect as the value 15.

The retransmission delay d is specified in steps of 250 us with a minimum of 250 us:

  • d == 0 => 250 us
  • d == 1 => 500 us
  • ...
  • d == 15 => 4 ms

The number of retransmissions n can range from 0 (effectively disabling auto-retransmission) to 15.

rfm73::rfm73 ( pins::output_pin sclk,
pins::output_pin mosi,
pins::input_pin miso,
pins::output_pin csn,
pins::output_pin ce 
)
inline

constructor: create and RFM73 object

This constructor creates an RFM73 object from the pins that connect to the RFM73 and a delay function. This constructor calls init().

void rfm73::transmit_address ( const unsigned char  address[])

set the rfm73 transmit address

This method sets the (up to 5 byte) address used for all transmissions.

bool rfm73::transmit_fifo_full ( void  )

report whether the transmit fifo is full

This method reads and reports whether the transmit fifo is full.

void rfm73::transmit_message ( const unsigned char  buf[],
unsigned char  length 
)

transmit a message

This method transmits the specified message.

The specified length must be less than or equal to RFM73_MAX_PACKET_LEN (32). Specifying a larger length has the same effect as specifying a length of RFM73_MAX_PACKET_LEN.

The retransmission setting (set by the method rfm73_retransmit_delay_attempts) determines whether the message is transmitted on the air just once or repeatedly until an acknowledge is received.

The RFM73 must be in transmit mode.

void rfm73::transmit_message_once ( const unsigned char  buf[],
unsigned char  length 
)

transmit a message once

This method transmits the specified message once.

The specified length must be less than or equal to RFM73_MAX_PACKET_LEN (32). Specifying a larger length has the same effect as specifying a length of RFM73_MAX_PACKET_LEN.

The message is transmitted on the air once, irrespective of the retransmission setting.

The RFM73 must be in transmit mode.