NAROM has written an Arduino library for the RFM96 radio for use on Cansat activities. This page will list the different commands than can and should be used by the user. When you use the radio, make sure that you have included the radio by using this at or close to the top of you sketch:
#include <Cansat_RFM96.h>
Note that this is not all the commands that are available for the user, but the other commands will be very specific and is not documented. This is for instance to change the bandwidth, coding rate and spreading factors and other transceiver specific parameters (these are the parameters that we set when reaching 60 km of range). Also, there are some functions for debugging the radio that should not be necessary to use.
Basic commands
Cansat_RFM96 rfm96(433500);
This will make an object for the library named rfm96, with the frequency of 433500 kHz (433.500 MHz), so please use the frequency that your tutor tells you to if you have been given one. Using this object initialization will use SD card by default. This «command» (it is not strictly as command per se) or the one below must be used when using the radio, or else you will get an error.
Cansat_RFM96 rfm96(433500, False); Cansat_RFM96 rfm96(433500, 0);
These two commands will disable use of SD cards. You can still use the SD card commands stated below, but the library will just not execute the parts of the commands related to SD cards.
rfm96.init()
This will initialize the rfm96 object that you made above. It does not take any inputs, but it will give an output stating if the initialization was successful or not. The normal use of it is something like this:
if (!rfm96.init()) {
Serial.println("Init of radio failed, stopping");
while(1);
}
rfm96.printToBuffer(1001);
rfm96.printToBuffer(this_is_a_variable_containg_numbers);
rfm96.printToBuffer("This is some text");
rfm96.printlnToBuffer(1001);
rfm96.printlnToBuffer(this_is_a_variable_containg_numbers);
rfm96.printlnToBuffer("This is some text");
rfm96.printlnToBuffer();
When you want to send something or write to the SD card (often both, but not always), you will first need to fill a buffer before actually using the send or writeToFile commands. This is how you can send numbers or text or lineshifts. The use of these commands is exactly the same as when using the Serial.print and Serial.println commands (if you are familiar with Arduino from before, this is something that you would have seen), and they behave exactly the same, except that they only writing it to a buffer and not actually sending it or writing to file. The printToBuffer and printlnToBuffer commands will convert whatever is not in readable ASCII (normal text) to ASCII. The difference between the commands with print and println is that the commands with println will do the same thing as print, but will also add a line shift after it.
rfm96.writeToBuffer(101);
This is the same as the print counterparts from above, but this does not convert anything to ASCII/readable text, it will just add it without doing anything with the data. This is not often used in Cansat, but it might be used for very advanced users which will try to compact the data that it sends to binary. It is not very user friendly to do this, so make sure you understand how to use it works.
rfm96.send();
This will mark anything in the buffer to transmit. It is a so-called blocking command, which means that if the radio is not ready for transmission it will wait (block anything else going on) before setting the buffer to transmit the data currently in the buffer. Note that this command also clears the buffer, so writing to file after using a send will not do anything, since the buffer will be empty.
rfm96.writeToFile();
This will write everything that is in the current buffer to the SD card. It will not clear the buffer, so you can use this before using the send command to send with the radio.
rfm96.sendAndWriteToFile();
A combination of the send and writeToFile commands. The way this function works is that it will write everything in the buffer to the SD card, then check if the radio is ready to transmit, and if that is the case, it also send with the radio. However, if the radio is not ready to transmit, it will exit the function without sending anything. It will always clear the buffer, no matter if the radio was ready to transmit or not. This is a command that is very easy to use, but it leaves the user out of control of some things. To be clear of how it works, this is the entire function:
uint8_t Cansat_RFM96::sendAndWriteToFile() {
uint8_t tmp_length;
tmp_length = writeToFile(); // This is always ready,
// and will also flush every time
if (isTxReady())
tmp_length = send(); // IF we send, then this is the length we return
clear(); // We empty the buffer and are ready to fill it up again
return(tmp_length);
}
rfm96.clear()
This will clear anything in the buffer, and do nothing else. This must be done if you use the writeToFile command without using the send command after it, as the writeToFile command does not clear the buffer.
rfm96.getTxBuffer()
With this command it is possible to get the content in the buffer without sending it by the radio and thereby clearing the buffer. It can be used f.ex. in the case where we want to use the serial monitor to control what is actually send by the radio:
String txbuf = rfm96.getTxBuffer(); Serial.print(txbuf);
The two above code lines can be replaced by the single command:
rfm96.printTxBuffer() rfm96.setTxPower(20);
As the name suggest, this command will set the TX power, and the input is the transmit power in dBm. You can set it from +5 dBm (lowest) to +20 dBm.
int last_RSSI_value_in_dBm = rfm96.last_RSSI();
This command returns the Received Signal Stength Indication (RSSI) value of the lastly received data package and store it in a variable called last_RSSI_value (you can change the variable name) in dBm power. The RSSI is an indicator of the received signal strength, and is an excellent indication of how «far» you are from losing communication between the Cansat and the ground station. Normally the Cansat starts dropping out at about -80 dBm. You can read more about RSSI in general here (which is not specific to the RFM96 radio).