⚠️ 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:
- Copy the folder rakwireless into the project folder. This folder contains the WisBlock and WisDuo board definitions and board variant files.
- 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:
After installing PlatformIO, you can see the PlatformIO icon and open it as follow:
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
- RAK11200 => install ESP32 platform
- RAK11300 => install Raspberry Pi RP2040 platform
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:
- Open or create a project that uses the updated platform.
- 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
- 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):
Install the patch
Open a terminal in the .platformio folder and execute python ./rak_patch.py
Example (Windows 10 terminal):
Example (Linux terminal):
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:
Then compile it by click the compiling icon at the bottom tool bar as follows:
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 Electronics Engineer, 23 years of experience in industrial and automotive HW and SW R&D. Supporting Arduino open-source community since 2014. |
Updated