rfm12.h File Reference

rfm12 library main header More...

#include "include/rfm12_extra.h"
#include "include/rfm12_ctrl.h"

Data Structures
struct	rf_tx_buffer_t
	The transmission buffer structure. More...
struct	rf_rx_buffer_t
	The receive buffer structure. More...
struct	rfm12_control_t
	Control and status structure. More...
Defines
States for rx and tx buffers
See also: rfm12_rx_status() and rfm12_control_t
#define	STATUS_FREE 0
	Indicates that the buffer is free.
#define	STATUS_OCCUPIED 1
	Indicates that the buffer is in use by the library.
#define	STATUS_COMPLETE 2
	Indicates that a receive buffer holds a complete transmission.
Return values for rfm12_tx() and rfm12_start_tx()
See also: rfm12_tx() and rfm12_start_tx()
#define	RFM12_TX_ERROR 0x02
	The packet data is longer than the internal buffer.
#define	RFM12_TX_OCCUPIED 0x03
	The transmit buffer is already occupied.
#define	RFM12_TX_ENQUEUED 0x80
	The packet has been enqueued successfully.
Functions
void	rfm12_init (void)
	This is the main library initialization function.
void	rfm12_tick (void)
	The tick function implements collision avoidance and initiates transmissions.
void	rfm12_rx_clear (void)
	Function to clear buffer complete/occupied status.
uint8_t	rfm12_start_tx (uint8_t type, uint8_t length)
	Enqueue an already buffered packet for transmission.
uint8_t	rfm12_tx (uint8_t len, uint8_t type, uint8_t *data)
	Copy a packet to the buffer and call rfm12_start_tx() to enqueue it for transmission.
static uint8_t	rfm12_rx_status (void)
	Inline function to return the rx buffer status byte.
static uint8_t	rfm12_rx_len (void)
	Inline function to return the rx buffer length field.
static uint8_t	rfm12_rx_type (void)
	Inline function to return the rx buffer type field.
static uint8_t *	rfm12_rx_buffer (void)
	Inline function to retreive current rf buffer contents.
Variables
rf_tx_buffer_t	rf_tx_buffer
	Buffer and status for packet transmission.
rf_rx_buffer_t	rf_rx_buffers [2]
	Buffers and status to receive packets.
rfm12_control_t	ctrl
	Global control and status.

Detailed Description

rfm12 library main header

Author:: Hans-Gert Dahmen; Peter Fuhrmann; Soeren Heisrath

Version:: 0.9.0

Date:: 08.09.09

This header represents the library's core API.

Define Documentation

#define RFM12_TX_ENQUEUED 0x80

The packet has been enqueued successfully.

#define RFM12_TX_ERROR 0x02

The packet data is longer than the internal buffer.

#define RFM12_TX_OCCUPIED 0x03

The transmit buffer is already occupied.

#define STATUS_COMPLETE 2

Indicates that a receive buffer holds a complete transmission.

#define STATUS_FREE 0

Indicates that the buffer is free.

#define STATUS_OCCUPIED 1

Indicates that the buffer is in use by the library.

Function Documentation

void rfm12_init ( void )

This is the main library initialization function.

This function takes care of all module initialization, including:

Setup of the used frequency band and external capacitor
Setting the exact frequency (channel)
Setting the transmission data rate
Configuring various module related rx parameters, including the amplification
Enabling the digital data filter
Enabling the use of the modules fifo, as well as enabling sync pattern detection
Configuring the automatic frequency correction
Setting the transmit power

This initialization function also sets up various library internal configuration structs and puts the module into receive mode before returning.

Note:: Please note that the transmit power and receive amplification values are currently hard coded. Have a look into rfm12_hw.h for possible settings.

static uint8_t* rfm12_rx_buffer ( void ) [inline, static]

Inline function to retreive current rf buffer contents.

Returns:: A pointer to the current receive buffer contents

See also:: rfm12_rx_status(), rfm12_rx_len(), rfm12_rx_type(), rfm12_rx_clear() and rf_rx_buffer_t

void rfm12_rx_clear ( void )

Function to clear buffer complete/occupied status.

This function will set the current receive buffer status to free and switch to the other buffer, which can then be read using rfm12_rx_buffer().

See also:: rfm12_rx_status(), rfm12_rx_len(), rfm12_rx_type(), rfm12_rx_buffer() and rf_rx_buffers

static uint8_t rfm12_rx_len ( void ) [inline, static]

Inline function to return the rx buffer length field.

Returns:: The length of the data inside the buffer

See also:: rfm12_rx_status(), rfm12_rx_type(), rfm12_rx_buffer(), rfm12_rx_clear() and rf_rx_buffer_t

static uint8_t rfm12_rx_status ( void ) [inline, static]

Inline function to return the rx buffer status byte.

Returns:: STATUS_FREE or STATUS_COMPLETE

See also:: rx buffer states, rfm12_rx_len(), rfm12_rx_type(), rfm12_rx_buffer(), rfm12_rx_clear() and rf_rx_buffer_t

static uint8_t rfm12_rx_type ( void ) [inline, static]

Inline function to return the rx buffer type field.

Returns:: The packet type from the packet header type field

See also:: rfm12_rx_status(), rfm12_rx_len(), rfm12_rx_buffer(), rfm12_rx_clear() and rf_rx_buffer_t

uint8_t rfm12_start_tx	(	uint8_t	type,
		uint8_t	length
	)

Enqueue an already buffered packet for transmission.

If there is no active transmission, the packet header is written to the transmission control buffer and the packet will be enqueued for transmission.
This function is not responsible for buffering the actual packet data. The data has to be copied into the transmit buffer beforehand, which can be accomplished by the rfm12_tx() function.

Note:: Note that this function does not start the transmission, it merely enqueues the packet.
Transmissions are started by rfm12_tick().

Parameters:

	[type]	The packet header type field
	[length]	The packet data length

Returns:: One of these defines: TX return values

See also:: rfm12_tx() and rfm12_tick()

void rfm12_tick ( void )

The tick function implements collision avoidance and initiates transmissions.

This function has to be called periodically. It will read the rfm12 status register to check if a carrier is being received, which would indicate activity on the chosen radio channel.
If there has been no activity for long enough, the channel is believed to be free.

When there is a packet waiting for transmission and the collision avoidance algorithm indicates that the air is free, then the interrupt control variables are setup for packet transmission and the rfm12 is switched to transmit mode. This function also fills the rfm12 tx fifo with a preamble.

Warning:: Warning, if you do not call this function periodically, then no packet will get transmitted.

See also:: rfm12_tx() and rfm12_start_tx()

uint8_t rfm12_tx	(	uint8_t	len,
		uint8_t	type,
		uint8_t *	data
	)

Copy a packet to the buffer and call rfm12_start_tx() to enqueue it for transmission.

If there is no active transmission, the buffer contents will be copied to the internal transmission buffer. Finally the buffered packet is going to be enqueued by calling rfm12_start_tx(). If automatic buffering of packet data is not necessary, which is the case when the packet data does not change while the packet is enqueued for transmission, then one could directly store the data in rf_tx_buffer (see rf_tx_buffer_t) and use the rfm12_start_tx() function.