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.
Table of contents
- Why PlatformIO?
- PlatformIO Prerequisites
- Installing the XIAO Board Definition
- Create a Project
- Compile a Project
- Upload a Project
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 (
.inoextension) 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.iniwhich, 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
.inosketches 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.
If not wrong, it was my third try when I finally got PlatformIO working properly a couple of months ago on a
References to the
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 Explorerin PIO by clicking on the Boards icon in the left panel.
Search Board...search box and press Enter.
- Click on the
Atmel SAMplatform .
- Click on the
Atmel SAMpage. Not surprisingly, this will install the platform.
button in the
A message box confirming the installation of the platform will pop up. Click on thebutton 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
Projectspage in PIO by clicking on the
Projectsicon in the left panel.
- Bring up the
Project Wizardin PIO by clicking on the
+ Create New Projectbutton in the top right of the
- Enter a project name in the
Namefield. Here I entered
- 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
Frameworkwill automatically be set to Arduino.
Locationchecked will mean that the project will be saved in a directory called
hello_xiaoin the PIO projects directory. The default location of that folder is
- If that location is acceptatble, click on the button.
I prefer to group board specific projects in a directory named after the board.
- I unchecked Location.
- Then I clicked on the
Projectsdirectory in the
Placessection of teh left panel of the file explorer.
- Then I clicked on the desired subdirectory named
xiaowhich I had created previously. Otherwise I could have clicked on the New button to create the subdirectory.
- Click on the button.
This will create the project which consists of a number of directories and files that are displayed in the
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
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:
see Seeeduino for details.
Compile a Project
Let's put what is probably the simplest working XIAO program in
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.
Uploading will work when the XIAO is in this mode.