In a very informative response to my first post about the Seeeduino XIAO, D. J. Park included instructions on how to add the XIAO to the list of SAM D21 boards in PlatformIO. I rushed to make that information available to others in a previous post. Parts of that post are now outdated because support for the XIAO has been added to the PlatformIO environment. Instead of rewriting that previous post, I decided to explain in more detail how to install the Atmel SAM package, how to create a very simple "Hello XIAO" program for the Seeduino XIAO and how to download the firmware to the XIAO, all in the PlatformIO environment.

Why PlatformIO?

Why use PlatformIO (PIO for short) instead of the Arduino IDE? Given that the XIAO can be programmed in either environment, this is largely a matter of personal preferences. I have many reasons for prefering PIO.

PlatformIO is an extension of Visual Studio Code. That means that I can program the microcontroler and write notes about the process within the same environment. Indeed, I set up workspaces which point to the folder containing the source code for my site and the folder containing the source code for a program and everything is available in the EXPLORER pane on the left panel. Furthermore, it was easy to set up tasks to "compile" the post source file into an html file with GTML (GTML an HTML pre-processor) and to view the result in a web browser.
PlatformIO is a more or less standard C/C++ environement. I have an Object Pascal (Free Pascal/Lazarus and before that Delphi and before that Turbo Pascal) background and I like its very clean unit file approach that combines the interface and implementation blocks. I can deal with the C/C++ approach with seperate header and source files, but I find the Arduino IDE confusing with its mixture of the standard C/C++ souce and header files and sketch files (.ino extension) with automatically generated header files. It seemed like I could never get the function prototypes having parameters with default values correct.
From the programming point of view, the ability to set up the programming environement on a project by project basis in PIO is worth the effort needed to install and learn how to use it. I don't know how often the following scenario has happened to me. I load a sketch for an ESP8266 based board into the Arduino IDE and make a few small changes and find that the sketch will no longer compile. After wasting several minutes investigating my changes trying to pinpoint a non existant error, I will finally remember that I had been playing with another type of board before and the IDE was still using the toolchain for that board to compile the ESP program. The programming environment with Arduino IDE is global. Programming a board is a two step operation: load the sketch and select the board definition. And the later is not particularly easy if many board definitions have been added to the IDE. In PIO each project has a configuration file, platformio.ini which, among other things, specifies the board used and the toolchain to be used to compile the project.
PIO allows one to be much more productive. Autocompletion and spell checking come immediately to mind.

Of course there are tradeoffs.

Arduino has a huge following and appeals to a wider audience that may not be interested in a full fledged development environement. Indeed, the whole idea behind .ino sketches with automatic generation of header files and implicit inclusion of some headers was to make it easier for beginners and it does work quite well for simple projects. In the end that means that PIO users will know how to import an Arduino sketch while some Arduino IDE users may be put off by a C/C++ source tree. For a long time, Tasmota by Theo Arends has been written for Arduino IDE and PlatformIO. so it is certainly possible to create projects that will compile in either environment, but I have yet to master this skill.
The Arduino IDE has a serial plotter which makes it very simple to plot output from a sketch with simple Serial.print() statements. I used it when discussing the XIAO analogue input and ouput. Apparantly, something analogous can be done in PlatformIO but I have yet to test that and even if it works, it will be more challenging to set up.

PlatformIO Prequisites

If not wrong, it was my third try when I finally got PlatformIO working properly a couple of months ago on a Linux desktop computer (initially Ubuntu 18.04 and now Mint 19 with Mate). At first, I tried with the Atom editor and then I ran into problems with being able to upload to only some ESP8266 boards. Finally, I installed the recommended Visual Studio Code editor using default settings and used it for at least a week before adding the PlatformIO extension. PlatformIO is regularly updated so perhaps it would now work just as well with Atom or any other supported editor). Adding the PlatformIO extension in the editor is quite simple, just follow the installation instructions. Once PlatformIO is added, it adds a toolbar to the status bar at the bottom of the editor.

References to the Home, Build, Upload and Serial Monitor buttons will be made in what follows. The toolbar documentation gives the keyboard shortcuts for these buttons.

The only hardware requirements is a free USB port on the desktop or portable computer to be used to download firmware to the XIAO or any other board and an appropriate USB cable to connect to the board. The XIAO requires a usb-c type cable.

Installing the XIAO Board Definition

Go to the PIO home page by clicking on the house icon on the status bar at the bottom of the editor window. If the mouse hovers over the iconthen the hint identifies it as the PlatformIO: Home button.
Bring up the Board Explorer in PIO by clicking on the Boards icon in the left panel.
Enter seeduino or xiao in the Search Board... search box and press Enter.
Click on the Atmel SAM platform

Click on the Install button in the Atmel SAM page. Not surprisingly, this will install the platform.

A message box confirming the installation of the platform will pop up. Click on the OK button to close the message window.

And that completes the installation of a platform. PIO will know where to obtain the toolchain and will manage to download needed packages as needed. It is now possible to create a project for the XIAO.

Create a Project

Go to the PIO home page by clicking on the PIO home button in the PIO toolbar on the status bar at the bottom of the editor window.
Go to the Projects page in PIO by clicking on the Projects icon in the left panel.
Bring up the Project Wizard in PIO by clicking on the + Create New Project button in the top right of the Projects page.
Enter a project name in the Name field. Here I entered hello_xiao.
Select the Board. The full name is Seeeduino XIAO but you can enter a part of the name and a list of matching boards will be displayed in the drop-down list.
Click on the full board name in the list. Not visible in the above image, the Framework will automatically be set to Arduino.
Leaving Location checked will mean that the project will be saved in a directory called hello_xiao in the PIO projects directory. The default location of that folder is /home/user/Documents/PlatformIO/Projects.
If that location is acceptatble, click on the Finish button.

I prefer to group board specific projects in a directory named after the board.

I unchecked Location.
Then I clicked on the Projects directory in the Places section of teh left panel of the file explorer.
Then I clicked on the desired subdirectory named xiao which I had created previously. Otherwise I could have clicked on the New button to create the subdirectory.
Click on the Finish button.

This will create the project which consists of a number of directories and files that are displayed in the EXPLORER pane.

Two files are important at this juncture. The main.cpp source file in the .../hello_xiao/src/ which contains the typical Arduino sketch structure. Note how PIO explicitely includes the Arduino.h header file in the project.

Check carefully the content of the project configuration file. For some reason my first project had the following content

[env:seeeduino] platform = atmelavr board = seeeduino framework = arduino

which is not correct. At this point, it is a good idea to add an entry setting the baud of the serial connection to the XIAO. The content of platformio.ini for a Seeeduino XIAO project should be:

[env:seeed_xiao] platform = atmelsam board = seeed_xiao framework = arduino monitor_speed = 115200

see Seeeduino for details.

Compile a Project

Let's put what is probably the simplest working XIAO program in main.cpp.

/* hello_xiao A first sketch for the Seeeduino XIAO in PlatformIO This example code is in the public domain. Michel Deslierres June 15, 2020 */ #include <Arduino.h> // needed in PlatformIO void setup() { } void loop() { Serial.println("Hello XIAO!"); delay(2000); }

Click on the Build button of the PIO toolbar.

A terminal window will be opened in which the output from the compiler and linker will be displayed.

Upload a Project

Once a project can be compiled without error, it is possible to upload the firmware to the XIAO. This is done by clicking on the PlatformIO: Upload icon on the status bar which is the right pointing arrow beside the home and compile icons. PIO should then reuse the terminal window to show the status of the upload and then to show the serial monitor with the XIAO output, if the upload was successful.

It may be necessary to manually start the serial monitor. The PlatformIO: Serial Monitor icon is the upward pointing plug on the status bar. Once the serial monitor is connected, the "Hello XIAO!" message from the board should be printed every second. The blue LED labeled T (for UART TX activity) will flash as the XIAO prints out it's message to the serial port.

Given the double duty performed by the USB port of the XIAO, there is a good chance that PIO will fail at a first attempt to upload the firmware.

In that case ground the XIAO RST (reset) pad twice in quick succession and the board should then be in "bootloader" mode waiting for the new version of the firmware. When the XIAO is in this mode, it shows up as a storage device named Arduino on my system as can be seen below.