Arduino Core for STM32  1.0

RadioHead Library

Author: Mike McCauley (mikem.nosp@m.@air.nosp@m.spayc.nosp@m.e.co.nosp@m.m) DO NOT CONTACT THE AUTHOR DIRECTLY Copyright (C) 2014 Mike McCauley

Id
RadioHead.h,v 1.89 2020/08/05 04:32:19 mikem Exp mikem

This is the RadioHead Packet Radio library for embedded microprocessors. It provides a complete object-oriented library for sending and receiving packetized messages via a variety of common data radios and other transports on a range of embedded microprocessors.

The version of the package that this documentation refers to can be downloaded from http://www.airspayce.com/mikem/arduino/RadioHead/RadioHead-1.113.zip You can find the latest version of the documentation at http://www.airspayce.com/mikem/arduino/RadioHead

You can also find online help and discussion at http://groups.google.com/group/radiohead-arduino Please use that group for all questions and discussions on this topic. Do not contact the author directly, unless it is to discuss commercial licensing. Before asking a question or reporting a bug, please read

Caution: Developing this type of software and using data radios successfully is challenging and requires a substantial knowledge base in software and radio and data transmission technologies and theory. It may not be an appropriate project for beginners. If you are a beginner, you will need to spend some time gaining knowledge in these areas first.

Overview

RadioHead consists of 2 main sets of classes: Drivers and Managers.

  • Drivers provide low level access to a range of different packet radios and other packetized message transports.
  • Managers provide high level message sending and receiving facilities for a range of different requirements.

Every RadioHead program will have an instance of a Driver to provide access to the data radio or transport, and usually a Manager that uses that driver to send and receive messages for the application. The programmer is required to instantiate a Driver and a Manager, and to initialise the Manager. Thereafter the facilities of the Manager can be used to send and receive messages.

It is also possible to use a Driver on its own, without a Manager, although this only allows unaddressed, unreliable transport via the Driver's facilities.

In some specialised use cases, it is possible to instantiate more than one Driver and more than one Manager.

A range of different common embedded microprocessor platforms are supported, allowing your project to run on your choice of processor.

Example programs are included to show the main modes of use.

Drivers

The following Drivers are provided:

  • RH_RF22 Works with Hope-RF RF22B and RF23B based transceivers, and compatible chips and modules, including the RFM22B transceiver module such as hthis bare module: http://www.sparkfun.com/products/10153 and this shield: http://www.sparkfun.com/products/11018 and this board: http://www.anarduino.com/miniwireless and RF23BP modules such as: http://www.anarduino.com/details.jsp?pid=130 Supports GFSK, FSK and OOK. Access to other chip features such as on-chip temperature measurement, analog-digital converter, transmitter power control etc is also provided.
  • RH_RF24 Works with Silicon Labs Si4460/4461/4463/4464 family of transceivers chip, and the equivalent HopeRF RF24/26/27 family of chips and the HopeRF RFM24W/26W/27W modules. Supports GFSK, FSK and OOK. Access to other chip features such as on-chip temperature measurement, analog-digital converter, transmitter power control etc is also provided.
  • RH_RF69 Works with Hope-RF RF69B based radio modules, such as the RFM69 module, (as used on the excellent Moteino and Moteino-USB boards from LowPowerLab http://lowpowerlab.com/moteino/ ) and compatible chips and modules such as RFM69W, RFM69HW, RFM69CW, RFM69HCW (Semtech SX1231, SX1231H). Also works with Anarduino MiniWireless -CW and -HW boards http://www.anarduino.com/miniwireless/ including the marvellous high powered MinWireless-HW (with 20dBm output for excellent range). Supports GFSK, FSK.
  • RH_NRF24 Works with Nordic nRF24 based 2.4GHz radio modules, such as nRF24L01 and others. Also works with Hope-RF RFM73 and compatible devices (such as BK2423). nRF24L01 and RFM73 can interoperate with each other.
  • RH_NRF905 Works with Nordic nRF905 based 433/868/915 MHz radio modules.
  • RH_NRF51 Works with Nordic nRF51 compatible 2.4 GHz SoC/devices such as the nRF51822. Also works with Sparkfun nRF52832 breakout board, with Arduino 1.8.9 and Sparkfun nRF52 boards manager 0.2.3.
  • RH_RF95 Works with Semtech SX1276/77/78/79, Modtronix inAir4 and inAir9, and HopeRF RFM95/96/97/98 and other similar LoRa capable radios. Supports Long Range (LoRa) with spread spectrum frequency hopping, large payloads etc. FSK/GFSK/OOK modes are not (yet) supported.
  • RH_MRF89 Works with Microchip MRF89XA and compatible transceivers. and modules such as MRF89XAM9A.
  • RH_CC110 Works with Texas Instruments CC110L transceivers and compatible modules such as Anaren AIR BoosterPack 430BOOST-CC110L
  • RH_E32 Works with EBYTE E32-TTL-1W serial radio transceivers (and possibly other transceivers in the same family)
  • RH_ASK Works with a range of inexpensive ASK (amplitude shift keying) RF transceivers such as RX-B1 (also known as ST-RX04-ASK) receiver; TX-C1 transmitter and DR3100 transceiver; FS1000A/XY-MK-5V transceiver; HopeRF RFM83C / RFM85. Supports ASK (OOK).
  • RH_ABZ Works with EcoNode SmartTrap, Tlera Grasshopper and family. Almost any board equipped with a muRata cmwx1zzabz module should work. Tested with EcoNode SmartTrap, Arduino 1.8.9, GrumpyOldPizza Arduino Core for STM32L0. When building for EcoNode SmartTrap in Arduino IDE, select board type Grasshopper-L082CZ. This chip and GrumpyOldPizza Arduino Core for STM32L0 are now supported by PlatformIO: https://docs.platformio.org/en/latest/platforms/ststm32.html#arduino-stm32l0-configuration-system
  • RH_Serial Works with RS232, RS422, RS485, RS488 and other point-to-point and multidropped serial connections, or with TTL serial UARTs such as those on Arduino and many other processors, or with data radios with a serial port interface. RH_Serial provides packetization and error detection over any hardware or virtual serial connection. Also builds and runs on Linux and OSX.
  • RH_TCP For use with simulated sketches compiled and running on Linux. Works with tools/etherSimulator.pl to pass messages between simulated sketches, allowing testing of Manager classes on Linux and without need for real radios or other transport hardware.
  • RHEncryptedDriver Adds encryption and decryption to any RadioHead transport driver, using any encrpytion cipher supported by ArduinoLibs Cryptographic Library http://rweather.github.io/arduinolibs/crypto.html

Drivers can be used on their own to provide unaddressed, unreliable datagrams. All drivers have the same identical API. Or you can use any Driver with any of the Managers described below.

We welcome contributions of well tested and well documented code to support other transports.

If your radio or transciever is not on the list above, there is a good chance it wont work without modifying RadioHead to suit it. If you wish for support for another radio or transciever, and you send 2 of them to AirSpayce Pty Ltd, we will consider adding support for it.

Managers

The drivers above all provide for unaddressed, unreliable, variable length messages, but if you need more than that, the following Managers are provided:

  • RHDatagram Addressed, unreliable variable length messages, with optional broadcast facilities.
  • RHReliableDatagram Addressed, reliable, retransmitted, acknowledged variable length messages.
  • RHRouter Multi-hop delivery of RHReliableDatagrams from source node to destination node via 0 or more intermediate nodes, with manual, pre-programmed routing.
  • RHMesh Multi-hop delivery of RHReliableDatagrams with automatic route discovery and rediscovery.

Any Manager may be used with any Driver.

Platforms

A range of processors and platforms are supported:

Other platforms are partially supported, such as Generic AVR 8 bit processors, MSP430. We welcome contributions that will expand the range of supported platforms.

If your processor is not on the list above, there is a good chance it wont work without modifying RadioHead to suit it. If you wish for support for another processor, and you send 2 of them to AirSpayce Pty Ltd, we will consider adding support for it.

RadioHead is available (through the efforts of others) for PlatformIO. PlatformIO is a cross-platform code builder and the missing library manager. http://platformio.org/#!/lib/show/124/RadioHead

History

RadioHead was created in April 2014, substantially based on code from some of our other earlier Radio libraries:

  • RHMesh, RHRouter, RHReliableDatagram and RHDatagram are derived from the RF22 library version 1.39.
  • RH_RF22 is derived from the RF22 library version 1.39.
  • RH_RF69 is derived from the RF69 library version 1.2.
  • RH_ASK is based on the VirtualWire library version 1.26, after significant conversion to C++.
  • RH_Serial was new.
  • RH_NRF24 is based on the NRF24 library version 1.12, with some significant changes.

During this combination and redevelopment, we have tried to retain all the processor dependencies and support from the libraries that were contributed by other people. However not all platforms can be tested by us, so if you find that support from some platform has not been successfully migrated, please feel free to fix it and send us a patch.

Users of RHMesh, RHRouter, RHReliableDatagram and RHDatagram in the previous RF22 library will find that their existing code will run mostly without modification. See the RH_RF22 documentation for more details.

Installation

For Arduino IDE, install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook. The example sketches will be visible in in your Arduino, mpide, maple-ide or whatever. http://arduino.cc/en/Guide/Libraries

Building for Particle Photon

The Photon is not supported by the Arduino IDE, so it takes a little effort to set up a build environment. Heres what we did to enable building of RadioHead example sketches on Linux, but there are other ways to skin this cat. Basic reference for getting started is: http://particle-firmware.readthedocs.org/en/develop/build/

  • Download the ARM gcc cross compiler binaries and unpack it in a suitable place:
    cd /tmp
    wget https://launchpad.net/gcc-arm-embedded/5.0/5-2015-q4-major/+download/gcc-arm-none-eabi-5_2-2015q4-20151219-linux.tar.bz2
    tar xvf gcc-arm-none-eabi-5_2-2015q4-20151219-linux.tar.bz2
  • If dfu-util and friends not installed on your platform, download dfu-util and friends to somewhere in your path
    cd ~/bin
    wget http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/linux-i386/dfu-util
    wget http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/linux-i386/dfu-suffix
    wget http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/linux-i386/dfu-prefix
  • Download the Particle firmware (contains headers and libraries require to compile Photon sketches) to a suitable place:
    cd /tmp
    wget https://github.com/spark/firmware/archive/develop.zip
    unzip develop.zip
  • Make a working area containing the RadioHead library source code and your RadioHead sketch. You must rename the sketch from .pde or .ino to application.cpp
    cd /tmp
    mkdir RadioHead
    cd RadioHead
    cp /usr/local/projects/arduino/libraries/RadioHead/ *.h .
    cp /usr/local/projects/arduino/libraries/RadioHead/ *.cpp .
    cp /usr/local/projects/arduino/libraries/RadioHead/examples/cc110/cc110_client/cc110_client.pde application.cpp
  • Edit application.cpp and comment out any #include <SPI.h> so it looks like:
    // #include <SPI.h>
  • Connect your Photon by USB. Put it in DFU mode as descibed in Photon documentation. Light should be flashing yellow
  • Compile the RadioHead sketch and install it as the user program (this does not update the rest of the Photon firmware, just the user part:
    cd /tmp/firmware-develop/main
    PATH=$PATH:/tmp/gcc-arm-none-eabi-5_2-2015q4/bin make APPDIR=/tmp/RadioHead all PLATFORM=photon program-dfu
  • You should see RadioHead compile without errors and download the finished sketch into the Photon.
Compatible Hardware Suppliers

We have had good experiences with the following suppliers of RadioHead compatible hardware:

Coding Style

RadioHead is designed so it can run on small processors with very limited resources and strict timing contraints. As a result, we tend only to use the simplest and least demanding (in terms of memory and CPU) C++ facilities. In particular we avoid as much as possible dynamic memory allocation, and the use of complex objects like C++ strings, IO and buffers. We are happy with this, but we are aware that some people may think we are leaving useful tools on the table. You should not use this code as an example of how to do generalised C++ programming on well resourced processors.

Code Contributions

We welcome, and will consider for merging into the mainline, contributions of fixes, patches, improvements etc. that meet the following criteria:

  • Are generally useful to more than a few people.
  • Are thoroughly tested.
  • Dont break anything else.
  • Are backwards compatible.
  • Are properly and completely documented.
  • Conform to the coding style of the rest of the library.
  • Clearly transfer the ownership of the intellectual property to Mike McCauley
  • Are posted on the Google group as a patch in unified Diff format, made against the latest version of the library.
Donations

This library is offered under a free GPL license for those who want to use it that way. We try hard to keep it up to date, fix bugs and to provide free support. If this library has helped you save time or money, please consider donating at http://www.airspayce.com or here:

Passing Sensor Data Between RadioHead nodes

Trademarks

RadioHead is a trademark of AirSpayce Pty Ltd. The RadioHead mark was first used on April 12 2014 for international trade, and is used only in relation to data communications hardware and software and related services. It is not to be confused with any other similar marks covering other goods and services.

Copyright

This software is Copyright (C) 2011-2020 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V3 or Commercial:

Open Source Licensing GPL V3

This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 3 when your application is distributed. See https://www.gnu.org/licenses/gpl-3.0.html

Commercial Licensing

This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. To purchase a commercial license, contact info@.nosp@m.airs.nosp@m.payce.nosp@m..com