First steps: Basic RAK Module - WisBlock Starter Kit

What comes to mind when you hear about Hardware Prototyping? Maybe a series of connectors and wires, a small or big breadboard, and, many times, mounting and assembling your circuit. WisBlock leaves in the past this way of looking at hardware prototyping, especially for IoT applications. WisBlock wants to make IoT easy in a way that it is Click, Code, and Connect —making IoT easy right?—.

This is one of the first tutorials that we want to offer using RAKwireless and WisBlock products, so you can explore the benefits from prototyping to a complete solution in the easiest and fastest way.

What do you need to start?

Mainly:

• WisBlock Starter Kit

Or you can purchase these items separately:

• WisBlock Core RAK4631 - Module for LoRaWAN
• 1 WisBlock Base Board RAK5005-O

Step by Step

About WisBlock Stater Kit

• WisBlock Base RAK5005-O
• WisBlock Core RAK4631

Assembling

Programing

• Configure Arduino for use with WisBlock Starter Kit
• Make your first ‘Hello World’ using Arduino
• Configure Visual Studio Code and PlatformIO for use with WisBlock Starter Kit
• Make your first ‘Hello World’ using VS Code and PlatformIO

What’s next…?

About WisBlock Starter Kit

The primary mission of RAKwireless with WisBlock is to empower individuals, entrepreneurs, and small or large companies to effectively connect “things” using LoRa/LoRaWAN technology. But, enough spam, let’s get down to the technical details.

WisBlock ecosystem is a modular concept for developing block-based IoT end-solutions —and no, it is not theory. They are genuinely hardware blocks—. As you just read, forget about finding a way to connect modules and breadboards using wires or anything else.

The process is simple. First, make a list of all the elements you need for your project. You can get them from the RAKwireless Store. When you receive them, just connect, code and that’s it. It's almost as if you were assembling your game computer, you need a motherboard, RAM, microprocessor, video card, among other elements. When you have all these elements you only have to connect and it’s ready for use.

There are many categories according to the project you have in mind: WisBlock Base (like a motherboard), WisBlock Core (such as a microprocessor), WisBlock Wireless, sensors, and all the peripherals you can think of. In this tutorial, we will talk about the first modules, WisBlock Base and WisBlock Core.

WisBlock Base RAK5005-O

WisBlock Base is a card that proposes a completely different hardware design paradigm. This is a platform where the processing units, sensors, radio, antennas, and all devices will be connected with a single click, quickly and easily.

This ecosystem is particularly developed to facilitate the development of IoT applications. To meet this challenge, all modules have an easy connection, so that you can go from your prototype to your final product in a very short time and with little effort. To show how it works, let's start by looking at the WisBlock Base and its features.

RAK5005-O provides the following interfaces: headers, jumpers, buttons, and connectors:

• 1 connector for CPU Slot
• 4 connectors for WisBlock Module Slot A to D
• 1 connector for IO Slot
• Sets of 4-pin 2.54 mm headers (UART, GPIOS, I2C, power, etc.)
• 2-pin battery interface
• 2-pin solar panel interface
• 3 LEDs (Blue, Red, and Green)
• Reset button

Note:

Battery voltage limits are 3.7V (recommended) to 4.2V (maximum); for solar panels maximum supported voltage is 5V.Do notconnect batteries or panels with a higher voltage it will damage the device.

If you are a developer or hardware maker, you may be wondering about the pinout: Where are the inputs and outputs? Where are the analog inputs? Keep calm. WisBlock is different, but that doesn’t mean it is complicated. On the contrary, it has ways of working to make prototyping and creating your final product even easier.

WisBlock Base handles all connections through slots. The slots are of three types and you can see them indicated in three different colors in Figure 2.

WisBlock Core Connector (40 pins - Green color in Figure 3)

WisBlock Core is the main WisBlock microcontroller where all information is processed. Some of the features of the Core Slot are:

• 1 UART Connection
• 1 SPI Connection
• 2 I2C Connection
• 6 General Purpose IO

WisBlock Sensor Slot (24 pins - Red Color in Figure 3)

The WisBlock ecosystem has a large number of sensors for various applications, all of them can use this type of slot. The WisBlock Base RAK5005-O can directly connect 4 sensors, two below and two above. These slots have the following characteristics:

• 1 SPI Communication
• 1 I2C Communication
• 2 General Purpose I/O

WisBlock IO Slot (40 pines - Blue Color in Figure 3)

Used for connecting IO general-purpose modules, ADC inputs, and other communications. These are its features:

• 1 UART Communication
• 2 I2C Communication
• 1 SPI Communication
• 6 General Purpose IO
• 2 Analogic Inputs

Do you need more Inputs/Outputs or want to connect more sensors? No worries, you can increase these capabilities with WisBlock interfaces. In the next tutorials, we will show how to do it.

WisBlock Core RAK4631

The RAK4631 is a powerful WisBlock core designed for IoT applications. It combines the benefits of the Nordic nRF52840 MCU microcontroller, based on the ARM Cortex M4F and this is complemented by the newest LoRa transceiver from SemTech, the SX1262 for LoRaWAN communications. In a few words, you have a powerful microcontroller with BLE, along with one of the latest LoRaWAN transceivers in a single device of only 3cm x 2cm.

Some features of this device:

• Nordic nRF52840 ultra-low-power MCU
• 32-bit ARM® Cortex™-M4 CPU
• 64 MHz CPU clock
• 1 MB Flash, 256 KB RAM
• Semtech SX1262 low power high range LoRa transceiver
• LoRaWan® 1.0.2 protocol stack
• Bluetooth 5.0 protocol stack
• I2C, SPI, Analog inputs, Digital inputs, and outputs
• Low power consumption

In Figure 3 you can see the RAK4631 from the bottom and top view. Notice the connection slot highlighted in green, which we discussed in the WisBlock Base section. Now that you are clear about the characteristics of each of the products that compose the WisBlock Starter Kit, let's get to work!

Assembling

If you purchase the kit, WisBlock Core and WisBlock Base could come already assembled, but, on many occasions, you have to assemble them.

The first step is to recognize the slots in the WisBlock Base and WisBlock Core. The idea is that the WisBlock Core will be on top of the WisBlock Base. The connection slot will be on the top of the WisBlock Base and at the bottom of WisBlock Core, check Figure 4.

Be careful when connecting. Press the WisBlock Core slowly and finally use the screws to adjust and secure the WisBlock Core to the WisBlock Base, as you can see in Figure 5:

Finally, we recommend that you connect the antennas before turning on your device in their respective slots:

And that’s it! You are ready to start programming your WisBlock Starter Kit.

Frequent Questions:

Q: Do I need some cable or wire to connect the blocks?

A: No, you don’t.

Q: Do I need an additional module to connect to LoRaWAN?

A: No, the LoRaWAN Module and the BLE Module are included in the WisBlock Core.

Q: I bought the RAK4631. Why in the module say RAK4630 on the top side?

A: That’s a good question. The RAK4630 is the core, you can use it for your final product that includes Surface Mount. But, for prototyping, you are using a little board underneath the core, and together, these two parts compose the RAK4631. See the Figure 8:

Programming

Note:

Before programming your WisBlock Starter Kit for the first time, we recommend that you update the bootloader by following this tutorial.

In this starter tutorial, we are going to explain the two most used ways to program WisBlock. The first one is using Arduino IDE and the second one will be using VS Code and PlatformIO. Let's go for it!

Configure Arduino for use with WisBlock Starter Kit

Chances are that you already know Arduino IDE. But, just in case you don't know it, here is its official page to download and install it. Once you have installed it, start the program and you’ll have your environment ready to program.

Before you start coding, you will need to make some settings on Arduino IDE. To do this, go to File > Preferences.

Make sure that Compilation and Upload options are selected, and in Additional Boards Manager press the icon to add the WisBlock boards URL.

Add the next URL in the dialog that will open, as shown in Figure 11.

https://raw.githubusercontent.com/RAKwireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless_index.json

After adding the URL, you can now install the RAKwireless cards, by going to Tools > Board (the default card will appear here) > Boards Manager.

In the dialog box that appears, search for the word RAK and all available RAKwireless boards will appear. For this example, we will only need the RAKwireless nRF Boards. Click on the Install Button. You can also install the other cards for later tutorials.

If everything went well, you can now select your WisBlock RAK4631 from the list of boards. For this go to Tools > Board > RAKwireless nRF Modules > WisBlock RAK4631

Finally, you can access all the examples that RAKwireles has for all its modules and sensors, by accessing File > Examples > RAK WisBlock Examples > RAK4631.

Make your first ‘Hello World’ using Arduino

For this tutorial we are not going to use any RAK sensors or libraries, we are just going to perform a simple blinking and Hello World! For this you can copy and paste the following code:

#include <Arduino.h>
#include <Adafruit_TinyUSB.h>

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");
  }

In the first lines of the code, we add two libraries necessary to run, compile and load the code. We perform the initialization of the serial port, be sure to use 115200 baud. Finally, we start the WisBlock output connected to the blue LED. WisBlock has two LEDs to be controlled by users as LED_BLUE, LED_GREEN, or WB_IO1, WB_IO2.

Finally, the blue LED turns on and off every second, and a message is printed to be seen on the serial monitor.

Connect your WisBlock to your computer using a micro USB cable. Press the Verify icon and then Upload to run the program on your WisBlock Starter Kit. Next, you will see your first blinking:

Then, you can see the message of WisBlock. For this, click Tools > Serial Monitor:

Configure Visual Studio Code and PlatformIO to use Wisblock Starter Kit

Visual Studio Code is an editor that is becoming more and more popular due to the large number of programming languages ​​for which it has developed plugins and with which it has compatibility. Most of the SW languages ​​are supported by VS code and now HW development is also done with this tool. We leave you the official page to download and install it. Once installed you will see the environment as shown in Figure 18.

The next step is to install the plugin for PlatformIO. If you don't know PlatformIO, it is a platform that contains many of the libraries of the most important hardware companies to implement and compile code in any OS, without installing the exclusive software of each manufacturer. Its idea is to generate freedom in the developers allowing them to use these libraries in the environment of their choice.

To install it, go to the toolbar on the left side and click on the extensions icon. In the search bar, type Platformio and the PlatformIO plugin will appear. Then, click on the Install button.

Once PlatformIO is installed, a message will appear informing you of the correct procedure. Restart Visual Studio Code so that the changes to be applied.

As in Arduino, you must install the libraries to support the RAKwireless WisBlock boards. If everything went well in the previous steps, in the sidebar you will already have a PlatformIO logo. Click on the PlatformIO logo > Open, click on the Platforms logo, and then on Install Embedded Platform Button.

In the search bar type nrf2. Then install the respective platform, as seen in Figures 22 and 23.

When the platform is finished installing, you will see a message like the one in Figure 24.

Finally, you can also install the libraries for the core with the ESP32 and the Raspberry PI RP2040, following the same procedure as for the RAK4631.

We are going to create a first project with the installed libraries. Click on the Home icon > New project. Name the project as you want, add a Nordic board of Adafruit, and select Arduino Framework.

Build and Upload the empty project. Ignore any errors you may get, we're just doing it so that Visual Studio creates some folders that we're going to need in the next step.

For this step, download the folder from this link and unzip it. You will find some files like the ones in Figure 29. The folders contain the files for PlatformIO to recognize RAKwireless devices.

Open a new file explorer window with the address where PlatformIO will be installed. Depending on your operating system the address may vary:

Windows      C:\Users\{Your_User_id}\.platformio\
Linux:            ~/.platformio/
MacOS         /Users/{Your_User_id}/.platformio/

Go back to the window where the downloaded folder is and go to:

...RAK_PATCH\platforms\nordicnrf52\boards

Copy the file wiscore_rak4631.json to the address according to your operating system:

Windows:    C:\Users\{Your_User_id}\.platformio\platforms\nordicnrf52\boards
Linux:    ~/.platformio/platforms/nordicnrf52/boards
MacOS:     /Users/{Your_User_id}/.platformio/platforms/nordicnrf52/boards

You should have something as shown in Figure 30:

Again, go back to your RAK_PATCH folder and, inside it, to the variants folder, located at:

...RAK_PATCH\packages\framework-arduinoadafruitnrf52\variants

Copy the WisCore_RAK4631_Board folder to the address where the platform is installed:

Windows:     C:\Users\{Your_User_id}\.platformio\packages\framework-arduinoadafruitnrf52\variants
Linux:     ~/.platformio/packages/framework-arduinoadafruitnrf52/variants
MacOS:     /Users/{Your_User_id}/.platformio/packages/framework-arduinoadafruitnrf52/variants

You will see something similar to Figure 31:

Note:

If the folder does not exist, recompile a new empty project using another board. We recommend choosing Adafruit boards.

Finally, restart Visual Studio for the changes to take effect.

Note:

In the RAK_PATCH folder are the files to install the two additional RAKwireless boards, RAK11200 and RAK11300. To install all RAKwireless cards you can perform the same process described above manually or you can run the rak_patch.py ​​file using Python 3, to have this process done automatically.

Make your first Hello World using VS Code and PlatformIO

If all went well in the previous process, you're all set to create your first HelloWorld program, so let's do it!

Create a new project. This time in Board select WisCore RAK4631 Board and Arduino Framework.

Copy and paste the code used in the Arduino section.

Build the code using the icon for this action.

Connect your WisBlock Starter Kit to your computer and upload the program. Click on the Upload icon.

At this point, you should have a blinking LED on your WisBlock Starter Kit, like the one in Figure 16. Finally, open the serial monitor to see the messages from your WisBlock.

And done! Congratulations, now you are ready to continue developing new projects using WisBlock Starter Kit. This tutorial was tested on Windows 11, Windows 10, and Ubuntu 18.04 machines. Please leave your comments if you have questions or errors, we will be glad to help you.

What’s next…?

We want you to start connecting all things using WisBlock Starter Kit. That's why in the next tutorials you will learn how to make your first basic Bluetooth application and we will also teach you how to connect two RAKwireless devices using LoRaWAN! We hope you don't miss them, and you can visit our older tutorials such as How to Update Bootloader using Bluetooth Connection. If you like this tutorial or have any other ideas, let us know, we love reading and interacting with you!