Basics

The purpose if this page is to provide an overview of the basic usage of the library API. For details on each supported radio module, please refer to the provided examples.

Standalone Module

1. Connect the wireless module to the Arduino. This includes connecting the SPI bus, as well as some GPIO pins. The extra pins are used for SPI chip select, hardware reset and GPIO or interrupts. Each module uses slightly different setup. For example, some modules might only have one interrupt pin, while others may have multiple. Some modules might have reset pin, others might do without one.

2. Provide the pin setup to the library. This is done using the Module constructor in the following format: Module(cs, irq, rst, gpio). For example: RF69 rf = new Module(10, 2, 3);

   • CS: this is the pin that's used as SPI chip select.
   • IRQ: this is the interrupt pin, it's usually connected to external interrupt on Arduino. It's a fast way for the module to tell Arduino something has happened - for example, a packet was received. All SPI modules have at least one interrupt pin.
   • RST: most modules have a hardware reset pin. If the module doesn't have a reset or chip enable pin (e.g. CC1101), set rst to RADIOLIB_NC.
   • GPIO: this is the fourth possible pin. It's optional for most modules, but may be required for some. SX127x requires additional interrupt pin to perform CAD and blocking receive. SX126x also uses this pin as the BUSY indication pin. If not in use, this pin can be left unassigned, or set to RADIOLIB_NC.

3. After the object is created, the module has to be initialized using the begin() method. Typically, this is done in Arduino setup() function. If you want to change the module settings, this can be done by providing appropriate values to the begin() method.

4. At this point, your module is ready to send or receive any data you want!

Using RadioShield

1. Plug the wireless module into either of the two slots and select the required communication channels/GPIO pins using jumper pins.

2. In Arduino code, select the slot the module is plugged into. For example, assuming SX1278 module plugged into slot A:
   SX1278 lora = RadioShield.ModuleA;

3. After the object is created, the module has to be initialized using the begin() method. Typically, this is done in Arduino setup() function. If you want to change the module settings, this can be done by providing appropriate values to the begin() method.

4. At this point, your module is ready to send or receive any data you want!

Non-standard SPI setup

Some platforms (such as ESP32) allow user to change the SPI bus pins. By default, RadioLib is using the SPI instance provided by Arduino, and will automatically initialize the bus - usually by calling SPI.begin(). However, user may want to use a different SPI bus than the default, or do the initialization outside the library. For this cases, an extended Module class constructor is provided, in the format Module(cs, irq, rst, gpio, &spi, spiSettings), where spi is a reference to an instance of SPIClass, and spiSettings is an instance of class SPISettings. In such case, RadioLib will not perform any internal initialization of the bus, and therefore this is left up to the user, as shown in an example for SX1278 and ESP32 below.

SPIClass spi(VSPI);
SPISettings spiSettings(2000000, MSBFIRST, SPI_MODE0);
SX1278 radio = new Module(cs, irq, rst, gpio, spi, spiSettings);

void setup() {
  spi.begin();
  (...)
  radio.begin();
}

Please note that SPI bus MUST be initialized prior to calling the begin() method!

The same logic can also be applied to change some properties of the default SPI bus, for example:

SPISettings spiSettings(4000000, LSBFIRST, SPI_MODE3);
SX1278 radio = new Module(cs, irq, rst, gpio, SPI, spiSettings);

void setup() {
  SPI.begin();
  (...)
  radio.begin();
}