high level interface

Macros
#define	RFM70_LIB_VERSION   "V1.02 (2011-12-31)"
	version of this rfm70 library More...
#define	RFM70_MAX_PACKET_LEN   32
	maximum number of data bytes in a (received or transmitted) rfm70 packet More...

Typedefs
typedef unsigned char	rfm70_buffer[RFM70_MAX_PACKET_LEN]
	type of rfm70 (transmit or receive) buffer More...

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

Detailed Description

The high-level interface provides methods for using the rfm70 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 RFM70_LIB_VERSION   "V1.02 (2011-12-31)"

version of this rfm70 library

#define RFM70_MAX_PACKET_LEN   32

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

Typedef Documentation

typedef unsigned char rfm70_buffer[RFM70_MAX_PACKET_LEN]

type of rfm70 (transmit or receive) buffer

Function Documentation

void rfm70::address_length

(

unsigned char

len

)

set the rfm70 address length

This method sets the length (in bytes) of the addresses used by the rfm70. 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 rfm70::air_data_rate

(

unsigned char

rate

)

set the rfm70 air data rate (baudrate)

This method sets the air data rate used by the rfm70 for receiving and transmitting. Allowed values are 1 and 2 (Mbits). A value of 0 will have the same effect as a avlaue of 1. A value > 2 will have the same effect as a value of 2. Note that this is the bitrate the rfm70 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 rfm70::channel

(

unsigned char

ch

)

set the rfm70 channel frequency

This method sets the frequency (channel) used by the rfm70 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 rfm70::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 rfm70::crc_length

(

unsigned char

len

)

set the rfm70 CRC length

This method sets the length of the CRC used by the rfm70 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 rfm70::is_present

(

void

)

report whether the rfm70 module is present

This method tests whether the rfm70 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 rfm70::lna_high

(

void

)

set the rfm70 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 rfm70::lna_low

(

void

)

set the rfm70 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 rfm70::lost_packets_count

(

void

)

read rfm70 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 rfm70::lost_packets_reset

(

void

)

reset rfm70 lost packets count

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

void rfm70::mode_powerdown

(

void

)

switch the rfm70 to power down mode

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

void rfm70::mode_receive

(

void

)

switch the rfm70 to receive mode

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

void rfm70::mode_standby

(

void

)

switch the rfm70 to standby mode

This method puts the rfm70 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 rfm70::mode_transmit

(

void

)

switch the rfm70 to transmit mode

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

void rfm70::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 rfm70::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 rfm70::power

(

unsigned char

level

)

set the rfm70 transmit power

This method sets the rfm70 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 rfm70::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 RFM70_MAX_PACKET_LEN (32).

The RFM70 must be in transmit mode.

void rfm70::receive_address_p0

(

const unsigned char

address[5]

)

set the rfm70 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 rfm70::receive_address_p1

(

const unsigned char

address[5]

)

set the rfm70 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 rfm70::receive_address_pn	(	unsigned char	channel,
		unsigned char	address
	)

set the rfm70 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 rfm70::receive_fifo_empty

(

void

)

report whether the receive fifo is empty

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

unsigned char rfm70::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 RFM70 datasheet does not specify the value that is returned when the receive FIFO is empty

unsigned char rfm70::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 rfm70::retransmit_count

(

void

)

read rfm70 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 rfm70::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.

rfm70::rfm70 ( pins::output_pin &  sclk, pins::output_pin &  mosi, pins::input_pin &  miso, pins::output_pin &  csn, pins::output_pin &  ce, void(*)(unsigned int)  wait_ms, void(*)(unsigned int)  wait_us  )

inline

constructor: create and RFM70 object

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

void rfm70::transmit_address

(

const unsigned char *

address

)

set the rfm70 transmit address

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

bool rfm70::transmit_fifo_full

(

void

)

report whether the transmit fifo is full

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

void rfm70::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 RFM70_MAX_PACKET_LEN (32). Specifying a larger length has the same effect as specifying a length of RFM70_MAX_PACKET_LEN.

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

The RFM70 must be in transmit mode.

void rfm70::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 RFM70_MAX_PACKET_LEN (32). Specifying a larger length has the same effect as specifying a length of RFM70_MAX_PACKET_LEN.

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

The RFM70 must be in transmit mode.