platformio
Add Xiao nRF52840 (Sense) board support
Fixes #142.
Based on https://medium.com/@alwint3r/working-with-seeed-xiao-ble-sense-and-platformio-ide-5c4da3ab42a3.
As requested in https://community.platformio.org/t/support-for-seeeduino-xiao-ble-board/28420.
Uses the latest core version as defined in the Arduino package manifest referenced in https://wiki.seeedstudio.com/XIAO_BLE/#software-setup.
Adds xiaoblesense and xiaoble as available boards. (Difference is, the "Sense" version has a IMU and microphone sensors per this).
Adds the Seeed version of framework-mbed as a new package, framework-mbed-seeed with version "2.8.1". Adaptions in the builder script are done according to https://github.com/maxgerhardt/builder-framework-arduino-core-mbed/commit/abb229f5bb99460e6e964cc8488cab1faa41b3c6.
Further adds framework-arduinoadafruitnrf52-seeed variant of framework-arduinoadafruitnrf52 and adds dedicated board files for the Adafruit varaint of the board used with the "1.0.0" core.
Suggested course of action:
- Add https://github.com/maxgerhardt/framework-mbed-seeed.git to the PlatformIO registry under the PlatformIO owner
- same for https://github.com/maxgerhardt/framework-arduinoadafruitnrf52-seeed.git
- merge https://github.com/platformio/builder-framework-arduino-core-mbed/pull/7
- merge https://github.com/platformio/builder-framework-arduino-nrf5/pull/13
- update submodule reference (two-level, https://github.com/platformio/builder-framework-arduino-nrf5 -> https://github.com/platformio/builder-framework-arduino-core-mbed/tree/master, then this repo ->builder-framework-arduino-nrf5)
- I will then adapt the submodule references and package source for
framework-mbed-seeedhere - then this PR can be merged
This PR can be tested by using the platformio.ini
[env]
platform = https://github.com/maxgerhardt/platform-nordicnrf52
framework = arduino
[env:xiaoblesense_arduinocore_mbed]
board = xiaoblesense
[env:xiaoblesense_adafruit_nrf52]
board = xiaoblesense_adafruit
[env:xiaoble_arduinocore_mbed]
board = xiaoble
[env:xiaoble_adafruit_nrf52]
board = xiaoble_adafruit
Thanks for the contribution! I see you've adopted Seeed's Mbed-based implementation, which is forked from the original Nano 33 BLE (Sense) BSP. Seeed themselves have 2 BSPs for the Xiao BLE (Sense) series, v1.0.0 being forked from Adafruit's FreeRTOS implementation bundled with their excellent Bluefruit libraries that support higher-level functionality such as HID, MIDI, etc, compared to the barebones original ArduinoBLE library. According to Seeed themselves, v1.0.0 is recommended in case one wishes to leverage the Bluefruit functionalities. Could there be a way to support both v1.0.0 (FreeRTOS + Bluefruit) and the official Arduino implementation (what has been forked for this PR, based on the latest version for the Seeed core)? I would definitely look into it myself, but I've got no experience with adding support for boards/frameworks in PIO. To clarify, I do not mean supporting them at the same time, but as different BSPs for the Xiao nRF52 boards under PlatformIO.
This PR is based on the ArduinoCore-mbed fork of Seeed, not the Adafruit nRF52 fork.
But indeed I now see that there are two packages
{
"name": "Seeed nRF52 Boards",
"architecture": "nrf52",
"version": "2.6.1",
"category": "Contributed",
"url": "https://files.seeedstudio.com/arduino/core/nRF52840/nrf52840_05202022_2.6.1.tar.bz2",
"archiveFileName": "nrf52840_05202022_2.6.1.tar.bz2",
"checksum": "SHA-256:32A4544728E9C9E234BA7A2F0719019F1FD5AD5A204BCE1227EC2E20F265C4BB",
"size": "31600049",
"boards": [{
"name": "Seeed XIAO nRF52840 Sense"
}],
...
{
"name": "Seeed nRF52 Boards",
"architecture": "nrf52",
"version": "1.0.0",
"category": "Contributed",
"url": "https://files.seeedstudio.com/arduino/core/nRF52840/Arduino_core_nRF52840.tar.bz2",
"archiveFileName": "Arduino_core_nRF52840.tar.bz2",
"checksum": "SHA-256:2754015D46A2EF7A8CF2727F5459BC8C5CAD9F73A7E69A130AC744D39BECEF77",
"size": "49463833",
},
....
What an extremely bad way to name board packages. If there's a 1.0.0 version and a 2.6.1 version, I won't even look at the 1.0.0 version for integration. But indeed, the 1.0.0 core is indeed an entirely different core (https://github.com/adafruit/Adafruit_nRF52_Arduino).
I'll have a look at adding this. Not sure if I want to add another board = .. option to this or a special core switching logic via board_build.core, which would be more in-line with other PlatformIO integrations where a board supports multiple different arduino cores.
What an extremely bad way to name board packages
Pretty much. I'd imagine they thought about maintaining the 2 varaints under the 1.x and 2.x versioning, so an upstream bugfix/feature addition for 1.0.0 would yield an updated BSP package under e.g. 1.0.1, but since Arduino BSPs never do this, this is just asking for trouble. Maybe they wanted to avoid naming Adafruit for whatever legal reason and resorted to the confusing 1.x / 2.x system as a consequence? I don't think Adafruit would go after them for forking their open-source Arduino BSP, though.
I also would like to see the Adafruit runtime support. My observations/understandings subject to correction by anyone more knowlegeable: It seems to wiggle with v 1.3.0 though I've not tried any of the Nordic SoftDevice functionality. Other than porting the variants pin definition code the other major thing I hit was a SoftDevice version mismatch between what the Seeed bootloader is built with by default (Seems to be 7.3.0) and what the Adafruit runtime is built with by default, 6.1.1.
The Adafruit runtime uses FreeRTOS under the covers, thus an RTOS task is run to execute the "Arduino" setup()/loop(), don't know about the mbed runtime. If the Softdevice versions do no match the inital RTOS task will not start and you end up in the weeds with a Hard Fault. has to do with locating the correct SVC_Handler() within the Adafruit runtime. The addressing for this is Softdevice version specific. (The actual SVC instruction that kicks off the start of the first RTOS task should also change a bit from "SVC 0" to SVC "3" or some other non interfering value. I believe 0 is reserved for SoftDevice use)
As mentioned it does wiggle with SoftDevice 6.1.1, I have yet to try rebuilding bootloader/runtime with Softdevice version 7.3.0.
I've not discussed this with Seeed at all to see if they might have a heart ache with support tickets re the Adafruit runtime. Edit.. Does seem to wiggle with SoftDevice 7.3.0.
https://github.com/leroyle/Adafruit_nRF52_Arduino/tree/leroyle A fork of the Adafruit_nRF52_Arduino repo with my above changes incorporated into branch "leroyle". PlatformIO board definition is "xiaoblesense" as in: [env] platform = nordicnrf52 board = xiaoblesense framework = arduino ... TODO: create a separate board definition for "Xiao BLE" vs "Xiao BLE Sense" The current pin definition incarnation is for the non "Sense" version Probably needs to be a separate issue of incorporating AdaFrutit runtime.
I've updated the Seed ArduinoCore-mbed version from 2.6.1 to 2.8.1 and added support for building for the "1.0.0" core, aka the Adafruit nRF52 core fork, by using the dedicated board definitions xiaoble_adafruit and xiaoblesense_adafruit .
I also had to make an update to the extra_script.py of the Adafruit nRF Crypto library to make it compile with the latest PIO version.
Blinky and BLE examples are at https://github.com/maxgerhardt/pio-xiao-ble-test.
Just to be clear, there's technically no need to wait for a merge to be able to use this within PlatformIO as of right now. Create an arbitrary project in PlatformIO (e.g. "Arduino Uno" + Framework: "Arduino"), then replace the created platformio.ini of the project with the one posted in the PR description above, select the environment you want to work in and you're good to go.
@maxgerhardt haven't tested that yet, but wouldn't we be missing the board definitions?
No because when you use the platformio.ini from above it sets platform = https://github.com/maxgerhardt/platform-nordicnrf52 so all board definitions are pulled from this repo and the xiaoble* board definitions are all in there. You don't have to do anything more to get them.
@maxgerhardt I have been using your repo for a while now, however I am having issues with using some of the core libraries in the framework. On your original merge request you say you have included framework-arduinoadafruitnrf52-seeed instead of framework-arduinoadafruitnrf52 , the latter of these includes these libraries. Does the framework you've used include them ?
I include everything what Seeed's variant of the adafruit core gives you, which can be found in https://github.com/maxgerhardt/framework-arduinoadafruitnrf52-seeed.git, just as the platform.json change of this PR says.
Thanks for your work.
Does this board support out of the box debugging? Or is external hardware like SWD to USB interface necessary?
There is no on-board JLink, ST-Link, CMSIS-DAP or similiar on the board. You need an external debugger, just like Seeed's documentation already tells you.
A caveat is of course if you can find a GDB-stub that runs on the nRF52840 and communicates via UART / USB. Such things were already done to enable debugging without external hardware for AVR Arduinos, the Teensy and ESP8266. You might be able to find, port or create something similiar for the nRF52.
I've been using this board for about a month now and would like to share some of my experience.
The PlatformIO support under this PR is great! It is not seamless, however, and I suffered some delays in development due to a lack of proper documentation and examples for this board, past the basic "hello world" Arduino stuff.
As many have already noted, this board has two cores - one based on Mbed and another based on FreeRTOS. It can also support Zephyr, though you need to add the XIAO BLE's onboard flash (P25Q16H) manually to the device tree.
BLE
My goal was to keep my nRF52 code as similar as possible to my ESP32 code by sharing the same BLE library, but unfortunately I was unable to accomplish this because I found no library that supported both my ESP32 and this particular board and didn't require moving to Mbed. Here's my research on available libraries:
- Bluefruit - https://github.com/adafruit/Adafruit_nRF52_Arduino
- Part of XIAO BLE v1 core, so it's officially supported
- nRF52 only
- ArduinoBLE - https://github.com/arduino-libraries/ArduinoBLE
- Supports nRF52 and ESP32
- Part of XIAO BLE v2 core, so it's officially supported
- Requires ARM Mbed
- Arduino-ESP32 - https://docs.espressif.com/projects/arduino-esp32/en/latest/api/ble.html
- ESP32 only
- Requires full Arduino-ESP32 core (ESP-IDF, which runs on FreeRTOS)
- NimBLE - https://github.com/h2zero/NimBLE-Arduino
- Supports both ESP32 and nRF52
- Does not require a SoftDevice!
- Requires forked Arduino-nRF5/Adafruit FreeRTOS core (https://github.com/h2zero/n-able-Arduino)
- Doesn't support XIAO BLE Sense
- BLEPeripheral - https://github.com/sandeepmistry/arduino-BLEPeripheral
- nRF only
- Requires Arduino-nRF5 FreeRTOS core (https://github.com/sandeepmistry/arduino-nRF5)
I settled on the officially supported Adafruit nRF52 core for my program, since the Bluefruit library seemed like the best BLE library to use, though in retrospect I would have liked to use Zephyr.
The Adafruit nRF52 core is dated and has only one maintainer (hathach) who seems to have plenty on his plate working on other components for Adafruit. Seeed doesn't contribute any maintenance to this core. I think they are working on MicroPython support right now.
Onboard flash
For storage, XIAO BLE has an onboard QSPI flash, but it is not documented how exactly to use it. (There is an example for InternalFileSystem, but this uses the small internal nRF52 flash rather than the onboard external flash.) For Adafruit, use the Adafruit_SPIFlash library (adafruit/Adafruit SPIFlash@^4.1.1) and configure the flash as follows:
static SPIFlash_Device_t P25Q16H {
.total_size = 1UL << 21, // 2 MiB
.start_up_time_us = 10000, // Unsure, but seems to be the typical value
.manufacturer_id = 0x85,
.memory_type = 0x60,
.capacity = 0x15,
.max_clock_speed_mhz = 104,
.quad_enable_bit_mask = 0x2,
.has_sector_protection = false,
.supports_fast_read = true,
.supports_qspi = true,
.supports_qspi_writes = true,
.write_status_register_split = false,
.single_status_byte = false,
.is_fram = false,
};
// Adafruit_FlashTransport_QSPI accepts _digital_ pin numbers
// which are mapped to low-level pin numbers through g_ADigitalPinMap.
static Adafruit_FlashTransport_QSPI flashTransport {};
static Adafruit_SPIFlash flash {&flashTransport};
void setup() {
/* ... */
flash.begin(&P25Q16H);
}
I suggest using LittleFS to create a filesystem. Some examples will tell you to pair this library with SdFat to create a filesystem, but SdFat will not format devices with less than 6 MB for some undocumented reason. You can try to remove this hardcoded limitation, or you can use LittleFS and gain the benefit of wear leveling.
Unfortunately, LittleFS has not been updated in the Adafruit core - it's stuck at version 1.6. I highly recommend updating it, as the library has been overhauled since this version from 2018. I would be happy to write a PR instead of writing these long instructions, though I don't really have time to thoroughly test it. Here is how to update LittleFS for your project:
- Copy out the Adafruit_LittleFS and InternalFileSystem libraries from the core to your project and change their versions in their
library.propertiesfiles. - Replace the code in the
littlefsdirectory in the Adafruit_LittleFS library with the latest version of the official LittleFS repo. - In the InternalFileSystem library, open
InternalFileSystem.cppand find the_InternalFSConfigdeclaration and update it for LittleFS 2.x by replacing the config with the following:
static struct lfs_config _InternalFSConfig =
{
.context = NULL,
.read = _internal_flash_read,
.prog = _internal_flash_prog,
.erase = _internal_flash_erase,
.sync = _internal_flash_sync,
.read_size = LFS_BLOCK_SIZE,
.prog_size = LFS_BLOCK_SIZE,
.block_size = LFS_BLOCK_SIZE,
.block_count = LFS_FLASH_TOTAL_SIZE / LFS_BLOCK_SIZE,
.block_cycles = 200,
.cache_size = LFS_BLOCK_SIZE,
.lookahead_size = 128,
.read_buffer = NULL,
.prog_buffer = NULL,
.lookahead_buffer = NULL,
.name_max = 0,
.file_max = 0,
.attr_max = 0,
.metadata_max = 0,
};
To interface LittleFS with the above Adafruit_SPIFlash device configuration, I created this lfs_config:
constexpr uint32_t SFLASH_ADDR(lfs_block_t block, lfs_off_t off) {
return block * SFLASH_SECTOR_SIZE + off;
}
static lfs_config lfsConfig {
.context = nullptr,
// Do not return a positive value on success. Do not return anything other
// than zero or a negative number. Positive values are treated as errors
// by LittleFS.
.read = [](const struct lfs_config *c, lfs_block_t block, lfs_off_t off,
void *buffer, lfs_size_t size) {
uint32_t ret = flash.readBuffer(SFLASH_ADDR(block, off), (uint8_t *) buffer, size);
if (ret == 0)
return (int) LFS_ERR_IO;
return 0;
},
.prog = [](const struct lfs_config *c, lfs_block_t block, lfs_off_t off,
const void *buffer, lfs_size_t size) {
uint32_t ret = flash.writeBuffer(SFLASH_ADDR(block, off), (uint8_t *) buffer, size);
if (ret == 0)
return (int) LFS_ERR_IO;
return 0;
},
.erase = [](const struct lfs_config *c, lfs_block_t block) {
bool ret = flash.eraseSector(SFLASH_ADDR(block, 0));
if (!ret)
return (int) LFS_ERR_IO;
return 0;
},
.sync = [](const struct lfs_config *c) {
// cache currently not used, but whatever
bool ret = flash.syncDevice();
if (!ret)
return (int) LFS_ERR_IO;
return 0;
},
.read_size = SFLASH_PAGE_SIZE,
.prog_size = SFLASH_PAGE_SIZE,
.block_size = SFLASH_SECTOR_SIZE,
.block_count = P25Q16H.total_size / SFLASH_SECTOR_SIZE,
// .lookahead = SFLASH_SECTOR_SIZE, /* LittleFS 1.x only */
.block_cycles = 768,
.cache_size = 2048,
.lookahead_size = SFLASH_SECTOR_SIZE,
.read_buffer = nullptr,
.prog_buffer = nullptr,
.lookahead_buffer = nullptr,
// .file_buffer = nullptr, /* LittleFS 1.x only */
.name_max = 0,
.file_max = 0,
.attr_max = 0,
.metadata_max = 0,
};
You can then use the Adafruit_LittleFS library or use LittleFS directly to use the filesystem as normal.
void setup()
{
Serial.begin(115200);
while ( !Serial ) delay(10);
flash.begin(&P25Q16H);
LOG_LV1(TAG, "Flash size: %lu bytes", flash.size());
// Adafruit_LittleFS version
Adafruit_LittleFS littlefs(&lfsConfig);
littlefs.begin();
LOG_LV1(TAG, "mkdir returns %d", littlefs.mkdir("helloworld"));
littlefs.end();
// LittleFS version
int err;
err = lfs_mount(&lfs, &lfsConfig);
LOG_LV1(TAG, "LittleFS mount: err=%d", err);
if (err < 0) {
err = lfs_format(&lfs, &lfsConfig);
LOG_LV1(TAG, "LittleFS format: err=%d", err);
err = lfs_mount(&lfs, &lfsConfig);
LOG_LV1(TAG, "LittleFS mount: err=%d", err);
}
if (err < 0) {
abort();
}
// Note - lfs_lfs_size is LittleFS 2.x only
LOG_LV1(TAG, "LittleFS used: %ld/%lu bytes",
lfs_fs_size(&lfs) * lfsConfig.block_size,
lfsConfig.block_count * lfsConfig.block_size
);
}
Debugging
To enable debug logging, you need to remove CFG_DEBUG=0 as a define before setting your own value:
build_unflags = '-DCFG_DEBUG=0'
build_flags =
'-D CFG_DEBUG=1'
CFG_DEBUG=0 is defined in https://github.com/maxgerhardt/framework-arduinoadafruitnrf52-seeed/blob/main/boards.txt.
You do not need J-Link to debug this board - you can use a Black Magic Probe with a Blue Pill setup. However, you will need the expansion board to access the SWD pins easily.
I set up the BMP with the XIAO BLE, and it works somewhat, but is very finicky. You cannot have a debugger attached and have USB attached at the same time; otherwise, the GDB server will freeze. You must activate GPIO UART by calling Serial1.begin(115200). To redirect log output to UART instead of USB CDC, set -DCFG_LOGGER=1 (where 0 is USB CDC, 1 is UART, and 2 is Segger RTT which might be supported by BMP). I was able to get serial working over a separate UART USB adapter, but not through the BMP - that is probably on me, though.
A lot of tutorials on how to set up the Blue Pill seem to be outdated. You should use the new stm32loader, which can be installed from pip, instead of the old Python 2 script of the same name. The ARM embedded toolchain also contains a version of gdb that depends on Python 2 and will not start if it's not installed. Instead, I used gdb-multiarch which is in the Ubuntu universe.
VSCode is often not able to start the debugger, giving no error. By default a breakpoint is put on the first line of main(), but when you try to resume the code, it gives a Remote failure reply: E800000085C... message, after which the only solution is to kill the debugger process manually.
Deep sleeping
I've been doing some research to see how deep this board can be put to sleep. So far the record is 2 uA. Even in CircuitPython 3.6 uA is possible. That's really good.
@oldmud0 wow, thanks for this research, it's super valuable. Regarding debugging I was able to use cheap Chinese stlink clone to debug the board using the expansion board to access the SWD pins.
Hi, thank you for your nice words. WRT bluetooth I wrote an article here explaining why I favor Bluefruit: https://medium.com/@enzo-lombardi/low-power-bluetooth-advertising-with-xiao-ble-and-platformio-e8e7d0da80d2 A few more pointers are here: https://medium.com/@enzo-lombardi/adding-ota-firmware-update-support-to-xiao-ble-boards-3db6f034c1fa with links on how I got IMU and I2S working as well. It's quite a nice board once everything works as expected.
Hi, thanks a lot for providing this!
I can't figure out how to use nrfx_ functions, in particular the I2S related ones. They compile OK and are found to be in .platformio\packages\framework-arduinoadafruitnrf52-seeed\cores\nRF5\nordic\nrfx\drivers\include\nrfx_i2s.h but give link errors at link time.
This page seems to indicate how to include nrfx drivers ("MDK") for various platforms but I can't figure out how to do this with PlatformIO.
Has anyone tried to use these drivers ?
I don't think the NRFC driver functions are available, code like https://github.com/aovestdipaperino/NRF_I2SPlayer/blob/main/I2SPlayer.cpp directly writes to the I2S registers.
Just to be clear, there's technically no need to wait for a merge to be able to use this within PlatformIO as of right now. Create an arbitrary project in PlatformIO (e.g. "Arduino Uno" + Framework: "Arduino"), then replace the created
platformio.iniof the project with the one posted in the PR description above, select the environment you want to work in and you're good to go.
Hi @maxgerhardt, I managed to compile some test code with the platformio.ini file you provided. I noticed that the [env:xiaoblesense_arduinocore_mbed] supports the pre-defined pins mentioned in the Xiao sense documentation (such as the LEDR, LEDB, LEDG for the onboard LEDs). However, when I try to include the bluefruit.h library, I get a compilation error (I think that's expected behavior though, because the comments make it sound like it's not compatible with the ArduinoCore-mbed envrionment). However, if I use the [env:xiaoblesense_adafruit_nrf52] environment, which was also included in the platformio.ini file as an option, then when I try to use the pre-defined board pins, I get a compilation error saying that LEDR, LEDB, LEDG are all undefined. Is that expected behavior? Because, honestly, if that's the only difference between the two environments, then I don't care. However, I want to make sure that using the [env:xiaoblesense_adafruit_nrf52] environment doesn't change anything else. Thanks!
In xiaoblesense_adafruit_nrf52, you also have the builtin LEDs defined as per variant.h:
https://github.com/maxgerhardt/framework-arduinoadafruitnrf52-seeed/blob/92b45349d6af8fcb88603b4231d24f91a64320e6/variants/Seeed_XIAO_nRF52840_Sense/variant.h#L34-L36
In
xiaoblesense_adafruit_nrf52, you also have the builtin LEDs defined as pervariant.h:https://github.com/maxgerhardt/framework-arduinoadafruitnrf52-seeed/blob/92b45349d6af8fcb88603b4231d24f91a64320e6/variants/Seeed_XIAO_nRF52840_Sense/variant.h#L34-L36
Thanks!
@maxgerhardt I'm using the
[env:xiaoblesense_adafruit_nrf52] environment and
board = xiaoblesense_adafruit options in the platformio.ini file, and I have
lib_deps =
https://github.com/Seeed-Studio/Seeed_Arduino_LSM6DS3.git
I am trying to use the Xiao Sense's onboard LSM6DS3, and when I use the basic example code provided with the above library in the Arduino IDE, the IMU initializes successfully. However, when I use the exact same code and setup within Platformio, the IMU fails to ever initialize. Do you know why this would be? I'm not sure if it has to do with my .ini file.
For reference, here is the code:
//Create a instance of class LSM6DS3
LSM6DS3 myIMU(I2C_MODE, 0x6A); //I2C device address 0x6A
void setup() {
// put your setup code here, to run once:
Serial.begin(115200);
while (!Serial);
//Call .begin() to configure the IMUs
if (myIMU.begin() != 0) {
while(myIMU.begin()!=0){
Serial.println("Device error");
delay(1000);
}
} else {
Serial.println("Device OK!");
}
}
char buf[100];
void loop() {
//Accelerometer
sprintf(buf, "Acc Values: x: %f, y: %f, z: %f",myIMU.readFloatAccelX(),myIMU.readFloatAccelY(),myIMU.readFloatAccelZ());
Serial.println(buf);
//Gyroscope
sprintf(buf, "Gyro Values: x: %f, y: %f, z: %f",myIMU.readFloatGyroX(),myIMU.readFloatGyroY(),myIMU.readFloatGyroZ());
Serial.println(buf);
delay(100);
}
Are you really using the bleeding edge git version in the Arduino IDE? If not, set lib_deps = miguelbalboa/MFRC522@^1.4.10 instead for a fairer comparison. Also, the I2C Scanner outputs what? And what version of the core is used in the Arduino IDE? (Tools -> Board -> Board Manager -> Xiao)