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
unsigned char	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, unsigned char enabled)
	enables or disables the autoack on a pipe More...
void	rfm70_pipe_enable (unsigned char d, unsigned char 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...
unsigned char	rfm70_transmit_fifo_full (void)
	report whether the transmit fifo is full More...
unsigned char	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...
unsigned char	rfm70_receive (unsigned char *pipe, unsigned char *buf, unsigned char *length)
	(try to) receive a message More...

Detailed Description

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

To use any of these functions, (except rfm70_init() itself) the interface and the module must have been initialized by an rfm70_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 function 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 function 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 function 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 function 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 function 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.

unsigned char rfm70_is_present

(

void

)

report whether the rfm70 module is present

This function 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 function 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 rfm70_channel() ) or explicitly by calling rfm70_lost_packets_reset().

void rfm70_lost_packets_reset

(

void

)

reset rfm70 lost packets count

This function 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 function 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 function flushes the receive queue, and switches the rfm70 to transmit mode.

void rfm70_mode_standby

(

void

)

switch the rfm70 to standby mode

This function puts the rfm70 in standby I mode, which reduces the power consumption (50 uA max). rfm70_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 function flushes the transmit queue, and switches the rfm70 to transmit mode.

void rfm70_pipe_autoack	(	unsigned char	pipe,
		unsigned char	enabled
	)

enables or disables the autoack on a pipe

This function 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,
		unsigned char	enabled
	)

enables or disables a pipe

This function 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 function 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.

unsigned char rfm70_receive	(	unsigned char *	pipe,
		unsigned char *	buf,
		unsigned char *	length
	)

(try to) receive a message

This function tries to receive a message.

This function tries to retrieve a received message from the receive FIFO. When no message is available this function 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 function 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 function 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 function 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 function sets the least significant byte of the receive address of the pipe n. The other bytes of the address are copied from pipe 1.

unsigned char rfm70_receive_fifo_empty

(

void

)

report whether the receive fifo is empty

This function 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 function 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 function 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 function 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 function 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.

void rfm70_transmit_address

(

const unsigned char *

address

)

set the rfm70 transmit address

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

unsigned char rfm70_transmit_fifo_full

(

void

)

report whether the transmit fifo is full

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

void rfm70_transmit_message	(	const unsigned char *	buf,
		unsigned char	length
	)

transmit a message

This function 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 function 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 function 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.