RadioTest (Notification Ping)

The simple RadioShuttle test application (“RadioTest”) is meant for beginners. There are two devices which communicate with each other and share a simple message. One device is called Node, the other is a so-called Station. At the touch of a button (button “A”) a message is transmitted from the node to the station. This also works the other way around, the station can also transmit a message to the node.

RadioShuttle RadioTest example code

This example is included in the RadioShuttle product, here’s the simplified code:

Here, frequency, channel bandwidth, transmitting power, and the LoRa spreading factor are determined. These data must be identical amongst all participants, so please don’t change anything when running a first test!

Here, some global variables for the LED and button “A” get defined, in addition a function named “SwitchInput” that is called after the button has been pushed. InterruptIn and DigitalOut are mbed compatible functions. Of course, Arduino functions can be used as well.

The initialization shown above activates the radio module (RFM95) and the related RadioShuttle protocol software with a status indicator “MyRadioStatus”, which makes the receiving and transmitting LEDs flash on activity. Node and server will then be started by the “Startup” function.

The main loop checks if the button has been pressed and sends a message to the counterpart station. The sleep function pauses the application until a new message comes in, i.e. the button has been pressed, or another activity interrupts the sleep. On activity, the LED is switched on, on high activity (e.g. an open USB “Serial Monitor” window) the LED flashes very quickly (which almost looks like permanent light). With disconnected USB plug and a restart (Reset) the LED should be switched off and merely flash upon activity.

The RadioShuttle example code includes a deepsleep() variant, which has USB deactivated and hence saves a substantial amount of energy.

The Receive Handler is called whenever a message has been sent, or a new message comes in, or an error has occured. Depending on the application, several Receive Handlers can be defined, one per app ID.

Message receipt

In general, a message transmission is confirmed, if the RadioShuttle::MF_NeedsConfirm flag is set in the SendMsg function. In this way, the node that sends the message is notified about the completed transmission only when the counterpart station has received the data. This prevents the message from being received only partly, or not at all.

Password authorization

A password can be stored for each RadioShuttle app ID. This prevents the station from accepting messages if the password between node and station is not identical. A password is stored for the original example code (please change to your own password).

The password ensures that external devices cannot communicate with your devices. It is stored on a per-app ID basis, which allows using one app publicly while other apps may be password protected. Passwords do not have a protocol overhead because they only need to be checked upon initial contact between the node and the station. The Apps Strategy documentation contains additional background information related to different apps.

Passwords are not transmitted over the network, hence they cannot be stolen. Instead of a password a large random number, together with the password, is converted to a SHA 256-bit hash code. Only this hash code is transmitted, which changes upon each login, e.g. when restarting a device.

AES 128-bit message encryption

AES encrypts all app data by use of the password, so no participant on the network who logs the communication can see the message content. Also fake messages do not work with AES, and are dismissed.

For the RadioShuttle purposes AES128-bit is more than sufficient because 340282366920938463463374607431768211456 attempts (2128) are very time-consuming and not realistic. RadioShuttle password and AES encryption are included in the separate “RadioSecurityInterface” module and can be adjusted or changed for other requirements.

Despite all its benefits, AES encryption has one major disadvantage: AES128-bit has a minimum block length of 16 bytes per message that needs to be transmitted. With SF7 this takes approximately 100 milliseconds in addition, with SF11 it is as much as half a second.

AES encryption can be defined on a per-message basis. The RadioShuttle::MF_Encrypted flags in the “SendMsg” must be set to allow AES encryption of the message. The RadioTest example code already comes configured that way.

Logging of the RadioShuttle network packet

The RadioTest example activates the logging of network transactions and internal operations. This can be helpful to verify what is currently happening. Deactivating the “EnablePacketTrace” function disables logging.

Logging function by dprintf and dump

The “dprintf” function allows for a “C printf” compatible output, with a time stamp per output line as well as automatic appending of line end marks.

“dump” allows hexdumping data including the name, address and a length. Examples are included in the RadioTest application.

RadioShuttle API documentation

The “RadioShuttle.h” file contains the complete RadioShuttle protocol API documentation. In addition, the file “RadioShuttleProtocol.rtf” documents the underlying concepts of the RadioShuttle protocol.