Using PlatformIO for Arduino development

It is possible to use PlatformIO to develop code for the Arduino targeted drivers. This is a howto for Linux, Visual Studio Code, and the iMRX1062 driver for Teensy 4.x. However, the same principles should be applicable to any Arduino targeted driver, using any PlatformIO supported IDE and OS.

These steps assume you already have a working PlatformIO installation, and are able to build and upload a simple blinky style sketch to a Teensy board. In this example we will create the PlatformIO project in a separate location to the grblHAL source tree, but it can be created directly within the source tree if preferred.

Initial Setup

1. Clone, or download and unzip, the grblHAL source to a folder of your choice.
2. Copy (or symlink) the grbl folder into the drivers/IMXRT1062/grblHAL_Teensy4/src/ folder.
3. Copy (or symlink) any required plugin folders into the drivers/IMXRT1062/grblHAL_Teensy4/src/ folder.
4. Create a new PlatformIO project in a folder of your choice, selecting the Teensy 4.1 board, and Arduino framework.
5. Copy (or symlink) the drivers/IMXRT1062/grblHAL_Teensy4 folder from your grblHAL source tree into the root folder of this new project.

At this stage, the root of your PlatformIO project should contain the platformio.ini configuration file, a number of automatically generated folders (include, lib, src, test), and the grblHAL_Teensy4 folder. You can safely remove the automatically generated folders if required.

Project Configuration

In order to successfully build the grblHAL source, we need to add a number of settings to the PlatformIO project configuration. Open the platformio.ini file, and overwrite with the following contents;

[platformio]
src_dir = grblHAL_Teensy4/examples/grblHAL_Teensy4_Upload
lib_dir = grblHAL_Teensy4

[env]
lib_archive = no
src_filter = +<../../src/*/*>
build_flags =
    -IgrblHAL_Teensy4/src/encoder

;lib_deps =  https://github.com/ddrown/teensy41_ethernet/archive/master.zip
;            https://github.com/WMXZ-EU/uSDFS/archive/master.zip
;            https://github.com/wwatson4506/MSC/archive/master.zip

[env:teensy41]
platform = teensy
board = teensy41
framework = arduino
upload_protocol = teensy-cli

At this stage, you should be able to build the Teensy driver, and upload to the board over USB.

Configuration details

The src_dir and lib_dir entries specify the relative paths to the source and library files. Source is fairly self explanatory, as the folder containing the sketch, but is worth noting that the library path is one level above the src folder. The reason for this is that PlatformIO expects libraries to be in direct subfolders of the library path, and not the library path itself.

The lib_archive entry instructs PlatformIO not to create a static library from the grblHAL object files. Without this, the linker may find the default 'blinky' setup() and loop() functions from the teensyduino library, instead of the expected functions from the grblHAL library.

The src_filter entry instructs PlatformIO to also look for code in subfolders of the grblHAL_Teensy4/src folder. (By default, PlatformIO will only attempt to compile source from direct subfolders of the library path). Note that this is specified as a relative path from the src_dir folder.

The build_flags entry is just a workaround for errors when the various source and plugin folders are symbolically linked into the driver folder structure, and needs to point to any real subfolder within the grblHAL/src folder. The reason for this is that, at least under Linux, relative paths are resolved relative to the destination of a symbolic link, and not the source.

As an example; a number of the plugins contain #include "../driver.h" directives. If these folders are symlinked from their original locations in the source tree, then the compiler will attempt to find driver.h in the parent folder of the original plugin folder (i.e. in grblHAL/plugins/) and fail. However, after trying the file path within quotes, the compiler will then also look for the same path within it's include paths. This entry just adds a new include path, one level down from grblHAL/src/, so that ../driver.h will successfully be found in it's parent directory.

The lib_deps entries are examples of pulling in external libraries for the networking and sdcard plugins. These can point to URLs, or local paths. Note that the MSC library is only there as it is required by the default configuration of the uSDFS library. As per the Teensy driver build instructions, that can be disabled in the uSDFS library (for example by editing the file inside a local zip, or by cloning the repository and making the necessary change in that version).

The final section contains standard PlatformIO settings for the board type and platform.