Learn about the new way of Programming IoT: RUI3

RAKwireless is known for offering IoT Hardware products. There is WisNode, WisBlock and WisGate, so you can develop a complete IoT project. Our mission is to make IoT easy. With WisBlock we achieve the hardware mounting simple and we wanted to make programming even easier. Our answer to this was to create our software tool to program our products. This tool is RUI3.

RUI3 is a framework with all the tools you need to quickly configure all RAKwireless' products, especially WisBlock products. Our idea is to provide you with a complete set of functions to configure and use the sensors, cores and boards that we have for you.

This framework is in the process of development, but right now we want to share with you the first stable version so that you are among the first to try it, and if you like it, or have any observations or improvements that we have to work on, please let us know.

In this tutorial you will learn how to start using RUI3, you will develop a simple Hello world application, and finally, you will learn how to connect two WisBlock using RUI3 and LoRa P2P communication. Let's get started!

NOTE: This tutorial is useful if you have already used WisBlock. If this is your first time hearing about this, you can refer to the getting started tutorial for more information.

What do you need?

• 1 WisBlock Starter Kit (Optional x2)
• 1 WisBlock Temperature and Humidity sensor RAK1901

Or you can buy them separately:

• 1 WisBlock Core RAK4631 (Optional x2)
• 1 WisBlock Base RAK5005-O (Optional x2)
• 1 WisBlock Temperature and Humidity sensor RAK1901

These items are also available in:

• Helium Developer Kit

Step by Step

Installation Process

• Firmware
• Arduino

Hello World Program

Reading a Sensor

Sending LoRa P2P Data

What’s next?

Installation Process

RUI3 requires two main installation processes. The first one is a special firmware that needs to be installed on the WisBlock Core to read all the commands. The other is a necessary tool for Arduino IDE to recognize the board and the instructions.

Firmware

NOTE: For LoRa P2P communications this process must be done in both WisBlock Cores

The firmware installation might be necessary if you don’t have a WisBlock Starter Kit, or the WisBlock Core RAK4631, with the RUI Firmware. You can purchase the RAK4631-R or the WisBlock Starter Kit with RUI, just select on the purchase page the firmware that you need:

If you already have a RAK4631 with the another firmware, follow the next steps to update to RUI3 Firmware (If you have the WisBlock Core RAK4631-R, jump to Arduino subsection).

1. Download the next tools for the Nordic RF chips:

• Development tool for nRF chips: nrfutil.exe
• Adafruit tools or nRF: adafruit-nrfutil.exe

2. Download the RUI3 files:

• RUI3 Bootloader: rui3_nrf52840_bootloader
• RUI3 Firmware: rui3_rak4631_latest

When you finish this process, you will have these four files downloaded. Make sure they are in the same folder:

Unzip the adafruit-nrfutil file and, if you want, delete the zip file.

Finally, create a folder on your computer's C drive called RUI3 and copy the files into it.

3. Connect your WisBlock Starter Kit to your PC. Open the Device Manager in windows (Start>Device Manager) and search where your WisBlock is connected.

Open the Command Prompt (Start > CMD) and write the following commands.

• Go to the folder where you paste the downloaded files.

cd C:\RUI3

• Install the RUI3 bootloader

adafruit-nrfutil.exe --verbose dfu serial --package rui3_nrf52840_bootloader_latest.zip --port COM31 -b 115200 --singlebank --touch 1200

Change the Port Number for the one found in the previous step.

NOTE: If you have not updated to the last firmware version, you can refer to the tutorial on how to do it here.

• On the first try, an error might occur. This is because the port changes. You can once again check the device manager:

Try again, changing the port number. You now have the RUI3 bootloader installed.

Finally, using the nrfutil.exe install the RUI3 firmware, using the following command. Don't forget to check where the port is connected to the WisBlock.

nrfutil.exe dfu serial -pkg rui3_rak4631_latest.zip -p COM9

In Figure 9, all this process is described:

At this point your WisBlock will have the RUI3 firmware updated and installed.

• Arduino

The next step is to install the board on Arduino.

After installing Arduino IDE, go to File>Preferences.

In Preferences, make sure that compilation and upload options are selected in the option Show verbose output during. And in Additional Boards Manager URLs, add the next link:

https://raw.githubusercontent.com/RAKWireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless.com_rui_index.json

Click on OK.

Go to Tools > Board > Boards Manager.

Search by RAKwireless and install the RAKwireless RUI nRF boards, and Click on the Install button.

Go to Tools > Board > RAKwireless RUI nRF Modules > WisBlock Core RAK4631 Board. With this step you have your WisBlock selected and ready to be programmed.

Now you are ready to begin to program your WisBlock using RUI3. Let’s go!

Hello World!

Let’s start with something simple, a Hello World and blinking Code!

Copy and paste the following code:

void setup() {
// put your setup code here, to run once:
Serial.begin(115200);
pinMode(LED_BLUE, OUTPUT);
digitalWrite(LED_BLUE, HIGH);
}
void loop() {
// put your main code here, to run repeatedly:
digitalWrite(LED_BLUE, HIGH);
delay(1000);
digitalWrite(LED_BLUE, LOW);
delay(1000);
Serial.println("Hello! I'm Alive");
}

Select the port where your WisBlock is connected.

Finally, Click on Verify and Upload.

And that's it! You have a first Program using RUI3. If all went well, you will have results like Figures 18 and 19.

Reading a Sensor

Ok, now that you've got some simple code working, let's do something else. We are going to read a sensor and print its value on the serial monitor.

The chosen sensor was one of the most basic of WisBlock, the RAK1901. The first step is to connect the sensor to the WisBlock Base. For that, you need a screwdriver, the RAK1901 and the screw, as you can see in Figure 20.

Connect the sensor to the slot. You can use the Slot A, B, C or D; and fix it with the screw.

If it is ready, continue with the programming.

The first step is to download the sensor library. Go to the official libraries page and download the library for the RAK1901 module.

In the Arduino IDE go to Sketch > Include Library > Add.ZIP Library

In the pop-up search for the downloaded file and click on Open.

After installing the library, let’s change a little our previous code:

#include "rak1901.h"
rak1901 rak1901;
float Temperature;
float Humidity;
void setup() {
// put your setup code here, to run once:
Serial.begin(115200);
pinMode(LED_BLUE, OUTPUT);
digitalWrite(LED_BLUE, HIGH);
Wire.begin(); // Begin function for I2C
rak1901.init();//Start rak1901
Serial.println("=============Temperature and Humidity Reading =========");
}
void loop() {
// put your main code here, to run repeatedly:
digitalWrite(LED_BLUE, HIGH);
delay(500);
digitalWrite(LED_BLUE, LOW);
delay(500);
if (rak1901.update()) {
Temperature = rak1901.temperature();
Humidity = rak1901.humidity();
} else {
Serial.println("Please plug in the sensor RAK1901 and Reboot");
}
Serial.printf("Temperature = %.2f%°C\r\n", Temperature);
Serial.printf("Humidity = %.2f%%\r\n", Humidity);
delay(5000);
}

In the first lines, we add the sensor library. Next, we call to RAK1901 class, and we declare two variables to measure Temperature and Humidity.

In the setup() function, we start the I2C communication and initialize the sensor. Finally, in the loop() function we add an if function to detect and read the sensor. Finally, print the values.

The final result will be similar to the Figure 26:

Sending Data through LoRa ® P2P

You can explore more options than measuring data about the temperature of your room. For example, I have some plants in my house and the temperature and humidity there might be more important to me. Do you think we can use LoRa® to send this data to another WisBlock that is connected to my computer? The answer is yes! Let's do it!

WARNING! Before continuing with this tutorial, make sure you have connected the LoRa® antennas to the two WisBlock Core RAK4631

Tx Code

The first step is to modify our original code again:

union{
float val_fl;
uint8_t val_arr[4];
}temp, hum;
uint8_t payload[8];

These first few lines of code create a binding structure in Arduino that allows us to read and store data as floats and as an array, and finally create a simple array to use as a simple payload.

Serial.printf("Set Node device work mode %s\r\n", api.lorawan.nwm.set(0) ? "Success" : "Fail");
Serial.printf("Set P2P mode frequency %s\r\n", api.lorawan.pfreq.set(915000000) ? "Success" : "Fail");
Serial.printf("Set P2P mode spreading factor %s\r\n", api.lorawan.psf.set(12) ? "Success" : "Fail");
Serial.printf("Set P2P mode bandwidth %s\r\n", api.lorawan.pbw.set(125) ? "Success" : "Fail");
Serial.printf("Set P2P mode code rate %s\r\n", api.lorawan.pcr.set(0) ? "Success" : "Fail");
Serial.printf("Set P2P mode preamble length %s\r\n", api.lorawan.ppl.set(8) ? "Success" : "Fail");
Serial.printf("Set P2P mode tx power %s\r\n", api.lorawan.ptp.set(22) ? "Success" : "Fail");

With seven lines on the setup() function, we configure all the LoRa parameters. These are: Work Mode, Frequency, Spreading factor, Bandwidth, code rate, preamble length and Tx power. You can learn more about this functions in the official documentation.

// Fill the payload
for(int j=0; j<4; j++){
payload[j] = temp.val_arr[j];
}
for(int k=4; k<8; k++){
payload[k] = hum.val_arr[k-4];
}
//Send data every 5 seconds
Serial.printf("P2P send %s\r\n", api.lorawan.psend(sizeof(payload),payload)? "Success" : "Fail");
delay(5000);

The final step is to fill the simple payload and send it to another WisBlock using LoRa® P2P communication. The complete code can be downloaded from our official GitHub account.

Now you can Verify and Upload your code into the first WisBlock, which will serve as a transmitter.

Rx Code

The Rx code is available in our GitHub repository.

void recv_cb(rui_lora_p2p_recv_t data) {
for(int k=0; k<data.BufferSize; k++){
if(k<4){
temp.arr[k]=data.Buffer[k];
}else if(k>=4 & k<8){
hum.arr[k-4]=data.Buffer[k];
}
}
Serial.print("Humidity: ");
Serial.println(hum.val);
Serial.print("Temperature: ");
Serial.println(temp.val);
}

The function in charge of reading and printing data is a callback function. This function is recv_cb(recv_cb(rui_lora_p2p_recv_t data). It receives a structure called data as a parameter which includes the SNR, RSSI, buffer size and received data buffer. Finally, a union structure is used to print the received data.

In the setup() function the callback function is added to the same configuration of Tx Code.

api.lorawan.registerPRecvCallback(recv_cb);

if(api.lorawan.precv(3000)){
delay(500);
}
else{
delay(1000);
}

Finally, an if-else function is used to keep the LoRa® receiver listening for new data. Verify and upload this code on the second WisBlock, the receiver. Remember that the receiver could be the same hardware configuration in the first step.

You can install the WisBlock transmitter in the place where you want to measure variables, connected to a battery or with a USB charger.

And you get all your data on your computer as you can see in Figures 28 and 29.

What’s next?

We hope you have enjoyed and learn from this tutorial. It's great for us to share with you this new tool to continue facilitating the development of IoT. We want to improve it based on your suggestions and feedback. Follow us on our official Hackster profile, where we continue to teach you how to develop IoT applications in an easier and faster way! Please let us know what other apps and sensors you used based on this tutorial.