How to Perform Installation of Board Support Package in PlatformIO

⚠️ Update

While the Python script to add WisDuo and WisBlock boards to the PlatformIO BSP's is still working, the problem with the script is that it has to be run every time PlatformIO updates the platforms.
To get around this, I checked the possibilities of PlatformIO to add custom boards to existing platforms, and I found a different solution, inspired by the work of Meshtastic. They are using PlatformIO's features to add (or better add customized) additional boards to the existing platforms.
RAK_PATCH_V2 is the result of my findings.

RAK_PATCH_V2

Instead of adding board descriptions and files to the existing platforms, the boards are added directly in the project folders.
This keeps the added boards active, even if the main platform is updated.

⚠️ INFO:
For the RAK11300 and RAK11310 modules with the RP2040 MCU, this method works only with the develop branch of platform-raspberrypi that is using the RP2040 BSP arduino-pico provided by Earl F. Philhower, III

How Does It Work?

PlatformIO allows to add custom board definition files (*.json) and custom variant folders to the main platform by hosting them in the project folder.
To use this feature, 2 steps are required in the project folder:

  1. Copy the folder rakwireless into the project folder. This folder contains the WisBlock and WisDuo board definitions and board variant files.
  2. Add access to these board definitions and variant files in the platformio.ini file of the project.

The folder rakwireless and an example platformio.ini file are provided in the archive RAK_PATCH_V2.zip in our WisBlock Github repo. Download this archive for the next steps.

Step 1

Copy the complete folder rakwireless from the RAK_PATCH_V2.zip archive into your project folder. The project folder structure should look like:

  • EXAMPLE_PROJECT
    • .pio
    • .vscode
    • include
    • lib
    • rakwireless
    • src
    • test
    • .platformio.ini

Step 2

To add these "custom" boards to the project, a few entries are required in the platformio.ini file:

  • boards_dir to define the path to the additional boards (only needed for RAK4630/RAK4631, RAK11200 and RAK3112/RAK3312)
  • build_src_filter to add the variant cpp files to tbe build path (Only needed for RAK4630/RAK4631)
  • build_flags = -I rakwireless/variants/rakxxxxxx to include the variant include files (only needed for RAK4630/RAK4631, RAK11200 and RAK3112/RAK3312)

An example that adds all 4 available Arduino based WisBlock Core modules and WisDuo stamp modules to a project can be found in the platformio.ini file.

Platformio.ini for RAK4630/RAK4631

To use the WisBlock Core RAK4631 or WisDuo RAK4630 stamp module the platformio.ini file should content the following entries:

[platformio]
boards_dir = rakwireless/boards
; other required definitions

[env:rak4630]
platform = nordicnrf52
board = rak4630
framework = arduino
build_src_filter = ${env.build_src_filter}+<../rakwireless/variants/rak4630>
build_flags =
-I rakwireless/variants/rak4630
; other build flags
lib_deps =
; project library dependencies
; other required environment definitions

Platformio.ini for RAK11200

To use the WisBlock Core RAK11200 the platformio.ini file should content the following entries:

[platformio]
boards_dir = rakwireless/boards
; other required definitions

[env:rak11200]
platform = espressif32
board = rak11200
framework = arduino
build_flags =
-I rakwireless/variants/rak11200
; other build flags
lib_deps =
; project library dependencies
; other required environment definitions

Platformio.ini for RAK3112/RAK3312

To use the WisBlock Core RAK3312 or WisDuo RAK3112 stamp module the platformio.ini file should content the following entries:

[platformio]
boards_dir = rakwireless/boards
; other required definitions

[env:rak11200]
platform = espressif32
board = RAK3112
framework = arduino
build_flags =
-I rakwireless/variants/RAK3112
; other build flags
lib_deps =
; project library dependencies
; other required environment definitions

Platformio.ini for RAK11300/RAK11310

⚠️ INFO:
The develop branch of the platform-raspberrypi already has a variant of for the RAK11300/RAK11310. But the variant definition is missing the WisBlock GPIO definitions that are used in the RAKwireless examples.

The platformio.ini example is using the rakwireless_rak11300 board, but adds the WisBlock GPIO definitions in the build_flags.

To add the missing WisBlock GPIO definitions with the WisBlock Core RAK11310 or WisDuo RAK11300 stamp module the platformio.ini file should content the following entries:

[platformio]
boards_dir = rakwireless/boards
; other required definitions

[env:rak11300]
platform = https://github.com/maxgerhardt/platform-raspberrypi
board_build.core = earlephilhower
board = rakwireless_rak11300
framework = arduino
build_flags =
-D ARDUINO_RAKWIRELESS_RAK11300=1
; WisBlock definitions
-I rakwireless/variants/rak11300
-D WB_IO1=6
-D WB_IO2=22
-D WB_IO3=7
-D WB_IO4=28
-D WB_IO5=9
-D WB_IO6=8
-D WB_A0=26
-D WB_A1=27
-D PIN_LED1=23
-D PIN_LED2=24
-D LED_BUILTIN=23
-D LED_CONN=24
-D LED_GREEN=23
-D LED_BLUE=24
; other build flags
lib_deps =
; project library dependencies
; other required environment definitions

Example Projects for RAK_PATCH_V2

Two examples are available to show the usage of the patch.
The first example WisBlock-LoRaWAN-OTAA is a simple example using the SX126x-Arduino library to establish an OTAA based connection to a LoRaWAN server.
The second example WisBlock-API-V2-Example is based on the WisBlock-API-V2 API, that provides low power coding and an AT command interface to setup the devices.

Both examples work on the RAK4630/RAK4631, RAK11300/RAK11310, RAK3112/RAK3312 and RAK11200 + RAK13300 modules.

 

RAK_PATCH (Old)

To make the support of WisBlock Core modules in PlatformIO easier we created a small script that installs or updates RAKwireless WisBlock modules in PlatformIO BSP's This script does not install the required BSP's (platform and package), it only patches already installed BSP's.

📝 NOTE: Download the patch package from RAK_PATCH.zip You will need it during the installation or update.

First Install

Install PlatformIO

First of all, install Visual Studio Code which is a great and open source tool, and you can download it here:

https://code.visualstudio.com/

After installing VS code, you can search PlatformIO and install it in the Extensions item:

KHM-060-01.png

After installing PlatformIO, you can see the PlatformIO icon and open it as follow:

KHM-060-02.png

Once PlatformIO installation is finished, you have to get the BSP's. Before you can use the WisBlock Core modules with PlatformIO you need to install the original platforms:

  • RAK4631 => install nRF52 platform
    KHM-060-03.png
  • RAK11200 => install ESP32 platform
    KHM-060-04.png
  • RAK11300 => install Raspberry Pi RP2040 platform
    KHM-060-05.png

After the required platforms are installed, follow the steps as shown in Update

Update

After updating or installing the nRF52, ESP32 or Raspberry Pi RP2040 package do the following steps:

  1. Open or create a project that uses the updated platform.
  2. Compile the project so that PlatformIO is installing the packages belonging to the platform
    • Ignore the Unknown board ID or variant.h: No such file or directory errors until the following patch has been applied
  3. Patch the platform and package
    • Unzip the contents of RAK_PATCH.zip into folder RAK_PATCH in your PlatformIO installation folder.
Paths on different OS:  
Windows %USER%\.platformio\
Linux ~/.platformio/
MacOS /Users/{Your_User_id}/.platformio/

Example (Windows 10):

KHM-060-06.png

Install the patch

Open a terminal in the .platformio folder and execute python ./rak_patch.py

Example (Windows 10 terminal):

KHM-060-07.png

Example (Linux terminal):

KHM-060-07.png

OK, you've install and configure PlatformIO for WisBlock successfully.

Example:

  • Now, let's try to compile an example of WisBlock using PlatformIO. We use the RAK13007_Relay_G5LE-14-DC3 example in this document:

https://github.com/RAKWireless/WisBlock/tree/master/examples/common/IO/RAK13007_Relay_G5LE-14-DC3/

Just copy the source code of the .ino file into the main.cpp of the PlatformIO project we just created:

KHM-060-09.png

Then compile it by click the compiling icon at the bottom tool bar as follows:

KHM-060-010.png

KHM-060-011.png

We've compiled this example successfully!

📝 NOTE: As same as Arduino IDE, there is an upload icon on the right of compiling icon which can be used to upload the compiled firmware into your device.

 

bernd-giesecke.png

Bernd Giesecke

Electronics Engineer, 23 years of experience in industrial and automotive HW and SW R&D. Supporting Arduino open-source community since 2014.

Updated