RFM12 library/en

The rfm12 library provides the ability to use RFM12(B) modules in conjunction with Atmel AVR microcontrollers.

Features

Software & Hardware SPI

This mode is especially useful for controllers that don't have a hardware SPI interface or where the SPI interface is used for something else.

To enable software SPI, add the following to your rfm12_config.h:

 #define SPI_SOFTWARE

Power-saving

You can make use of the RFM12's wakeup timer by adding the following line to your rfm12_config.h:

 #define RFM12_USE_WAKEUP_TIMER

Raw transmissions

You can make use of raw transmission mode, meaning manually switching the transmitter on and off in software. This feature is especially useful if you want to control devices that don't support the RFM12's modulation (e.g. Radio controlled power Plugs).

In order to use the raw transmission feature, you have to set the variable RFM12_RAW_TX in rfm12_config.h. Before you can use the raw transmission mode, you'll have to tell the library to switch to raw mode using the function rfm12_rawmode(1). The functions rfm12_tx_on() and rfm12_tx_off() will then manually switch the transmitter on and off.

Note that when being in raw transmission mode, the rfm12 interrupt is disabled as well as other library functions. You will not be able to receive or send data the "usual" way while raw transmission mode is on. To switch back to normal mode, execute rfm12_rawmode(0).

Example Code

 ...
 rfm12_rawmode(1);   /* switch to raw mode           */
 rfm12_tx_on();      /* send a logical one...        */
 _delay_ms(1);       /* ...for 1 ms...               */
 rfm12_tx_off();     /* then disable the transmitter */
 rfm12_rawmode(0);   /* switch back to normal mode   */
 ...

Technical details

In raw transmission mode, the RFM12 module's transmitter is simply turned on and off. While it is enabled it transmits the preamble in an endless loop.

The module doesn't seem to support modulation modes other than it's own, so sending a logical one actually means sending the preamble with the native modulation mode. "Dumb" devices (rf power-plugs, doorbells, etc.) may well recognize this as a high-peak and can be controlled this way.

Collision prevention

Before a packet is actually sent, the RFM12's status register is read in order to measure the current signal strength. When the signal strength is above a treshold, it is assumed that there's a transmission underway. The library then waits some time until the "ether" is free and starts the transmission when the module hasn't seen any traffic for some time.

Collision prevention is enabled by default. You can disable it by adding #define RFM12_BE_RUDE to your rfm12_config.h.

Integrity checking

The library already provides a very small protocol to provide integrity for your transmissions. There are two additional bytes sent in per packet that contain the length of the payload and a "checksum" field, that simply is the byte-per-byte XOR'ed payload.

Downloading the library

The library is hosted in our subversion repository. You can browse the repository or directly check out the sources with the command:

 svn co svn://roulette.das-labor.org/microcontroller/src-atmel/lib/rfm12

Using the library

The file rfm12_config.h contains all the configuration as well as a pin assignment table.

Here's an example how to use the library:

uint8_t teststring[] = "teststring\r\n";
uint8_t packettype = 0xEE;
rfm12_init();  /* initialize the library */
sei();

while (23)
{
    /* ... */
    rfm12_tx (sizeof(teststring), packettype, teststring);
    rfm12_tick();  /* periodic tick function - call that one once in a while */
}