Merge pull request #3 from brianredbeard/platformio-config

docs: Document use of PlatformIO

.gitignore

@@ -25,6 +25,9 @@ $RECYCLE.BIN/
 # Build folder
 
 build
+.pio*
+.pioenvs
+.piolibdeps
 
 #
 # =========================

README.md

@@ -2,12 +2,10 @@
 
 A grblHAL driver for the NXP iMXRT1062 processor on a [Teensy 4.x board](https://www.pjrc.com/store/teensy40.html).
 
-This driver compiles and uploads from the Arduino IDE and is partially dependent on the Arduino framework. [Teensyduino](https://www.pjrc.com/teensy/td_download.html) is required and must be added to the Arduino IDE.
-
-See the Wiki-page for [compiling grblHAL](https://github.com/grblHAL/core/wiki/Compiling-GrblHAL) for instructions for how to import the project, configure the driver and compile.
-
 Available driver options can be found [here](main/my_machine.h).
 
+See [Compiling](#Compiling) for more information on building.
+
 ---
 
 
@@ -55,5 +53,139 @@ Download the libraries above as zip files and add to your Arduino installation w
 <sup>2</sup> I<sup>2</sup>C EEPROM \(or FRAM\) is [optional](https://github.com/grblHAL/Plugin_EEPROM/blob/master/README.md) and must be added to the board. FRAM is recommended when the [Odometer plugin](https://github.com/grblHAL/Plugin_odometer/blob/master/README.md) is added to the build.  
 <sup>3</sup> Number of digital input pins available is reduced when the [Encoder plugin](https://github.com/grblHAL/Plugin_encoder/blob/master/README.md) is added to the build.
 
+### Compiling
+
+grblHAL can be built using the Arduino IDE or through the use of PlatformIO.
+Detailed directions may be found in the [grblHAL
+wiki](https://github.com/grblHAL/core/wiki/Compiling-GrblHAL).
+
+
+#### Arduino IDE 
+
+This driver compiles and uploads from the Arduino IDE and is partially dependent on the Arduino framework. [Teensyduino](https://www.pjrc.com/teensy/td_download.html) is required and must be added to the Arduino IDE.
+
+See the Wiki-page for [compiling grblHAL](https://github.com/grblHAL/core/wiki/Compiling-GrblHAL) for instructions for how to import the project, configure the driver and compile.
+
+
+#### PlatformIO 
+
+##### About
+[PlatformIO][PlatformIO] is a cross platform build system for embedded systems.
+It provides both a GUI (delivered as an extension for VSCode) as well as a
+command line interface, both of which wrap the underlying toolsi (`scons`,
+`gdb`, etc).  It features library management, a robust interface for dynamic
+builds and scripting, and a set of Python APIs for customization.  Users
+interested in exploring complex project configurations utilzing many vendor
+provided hardware abstraction layers, processor specific customizations, etc may
+consult the configurations used within the Marlin project (configurations may be
+found in `platformio.ini` and `ini/*`).
+
+##### Quick Start
+
+Compiling grblHAL with PlatformIO is quite trivial.  PlatformIO will handle
+setting up any processor/architecture specific tooling needed to compile and
+flash grblHAL.  To begin, decide whether you are choosing to use the GUI via
+VSCode or the command line tooling. Consult the [documentation][pio-docs]
+for directions on installing in the desired manner.
+
+Next we will clone this repository, ensuring that all submodules have been
+retrieved:
+
+```bash
+git clone --recurse-submodules https://github.com/grblHAL/iMXRT1062.git
+```
+
+Next, change into the `grblHAL_Teensy4` sub-directory located within your checkout
+of the project (by default this would be `iMXRT1062/grblHAL_Teensy4`).
+
+This directory contains the `platformio.ini` configuration file.  Within the
+configuration file we have some basic boilerplate information specifying how to
+build the project.  These settings describe:
+
+  - The `board` we desire to compile for (the Teensy 4.0 or 4.1) Note: Both
+    boards are defined in `platformio.ini`.  The primary distinction between the
+    boards is the onboard flash size (1.94MB in the Teensy 4.0 and 7.75MB in the
+    Teensy 4.1).  While either environment will generally work, using the wrong
+    environment may raise errors in the future if the build sizes become too
+    large.
+  - The `platform` to be used (Within PlatformIO a development platform is
+    described as "a particular microcontroller or processor architecture that
+    PlatformIO projects can be compiled to run on. (A few platforms, for example
+    Teensy, use different target architectures for different boards.)"
+  - The `framework` we will use for development (For the Teensy we use
+    `arduino`.  Examples of other frameworks inclue `CMSIS`, `FreeRTOS`,
+    `STM32Cube`, etc).
+  - A working `environment` which scopes specific configurations for the tools
+    `pio run`, `pio test`, `pio check`, `pio debug`, and any custom targets
+    which may be defined.  Our environment re-uses the board name, `teensy41`
+    and sets this value as the default environment.
+  - Any 3rd-party libraries we may need (e.g. uSDFS, Ethernet, etc)
+  - How assets should be flashed to the device (The `teensy-cli` application)
+
+The configuration file also provides a number of configuration abstractions
+where common configurations can be applied project wide or by build environment.
+For more information on customizing your configuration or build environment,
+consult the [PlatformIO documentation][pio-docs].
+
+Next, make any desired edits to the file `src/my_machine.h`
+
+Begin compilation by running the command:
+
+```bash
+pio run
+```
+
+This will begin the compilation, using the default environment.  Alternate
+environments may be specified using the flag `-e`/`--environment`.  Additional
+targets may be viewed by running `pio run --list-targets`.  Changing the target
+from the default (compilation) can be done using the flag `-t`/`--target`
+(e.g. `pio run -t clean`).
+
+As the compilation begins all of the needed tooling and libraries will be
+retrieved.  Tooling will be installed to the user's "global" PlatformIO
+installation.  Project specific libraries will be stored in the subdirectory
+`.pio`.  The `.pio` directory is solely used for temporary build artifacts and
+caching libraries.  It is safe to completely remove and will be re-created on
+the next execution of `pio run`.
+
+At the end of compilation, two assets will be generated:
+  - `.pio/build/teensy41/firmware.elf`
+  - `.pio/build/teensy41/firmware.hex`
+
+Our ELF ([Executable and Linkable Format][elf]) binary contains the full set of
+headers desribing our program and section headers.  Our HEX file is the binary
+rendering of solely the data section of the ELF file.  The HEX file is the one
+used by the default Teensy tooling.  The ELF file is useful when performing
+debugging (i.e. through the use of `gdb` or `openocd`).
+
+We may use the target `upload` to flash our new firmware.  The default
+project-specific configuration in `platformio.ini` utilizes the Teensy CLI
+application.  A complete list of supported upload protocols for the Teensy 4.1
+(e.g. `teensy-gui`, `jlink`) can be referenced on the [Teensy 4.1][pio-teensy41]
+page in the PlatformIO documentation.
+
+To execute our upload, run the following command:
+
+```bash
+pio run -t upload
+```
+
+Congratulations!  You should now have a newly flashed Teensy running grblHAL!
+
+##### Updating your check-out
+
+To update your checkout in the future, ensure that all git submodules are
+updates along with the primary repository:
+
+```bash
+git pull --recurse-submodules
+```
+
+[elf]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
+[Marlin]: https://github.com/MarlinFirmware/Marlin/
+[PlatformIO]: https://www.platformio.org
+[pio-docs]: https://docs.platformio.org/en/latest/
+[pio-teensy41]: https://docs.platformio.org/en/latest/boards/teensy/teensy41.html
+
 ---
 2021-06-08

grblHAL_Teensy4/platformio.ini

@@ -0,0 +1,49 @@
+[platformio]
+src_dir = src
+include_dir = src
+default_envs = teensy41
+
+[common]
+build_flags   = -g3 
+		-fmax-errors=5
+lib_archive   = no
+lib_deps      = 
+extra_scripts =
+src_filter    = +<src/*>
+
+#
+# Default values apply to all 'env:' prefixed environments  
+#
+[env]
+framework     = arduino
+extra_scripts = ${common.extra_scripts}
+build_flags   = ${common.build_flags}
+		-include src/my_machine.h
+lib_deps      = ${common.lib_deps}
+monitor_speed = 250000
+monitor_flags =
+
+# Common values for Teensy based boards
+[common_teensy]
+platform = teensy
+upload_protocol = teensy-cli
+build_flags = ${env.build_flags}
+lib_deps = 
+    https://github.com/wwatson4506/uSDFS#uSDFS-non-blocking
+    https://github.com/wwatson4506/MSC#MSC-non-blocking
+    https://github.com/ddrown/teensy41_ethernet
+
+# Included as a stub-example for showing how to structure common environments
+[env:teensy40]
+board = teensy40
+platform = ${common_teensy.platform}
+upload_protocol = ${common_teensy.upload_protocol}
+build_flags = ${common_teensy.build_flags}
+lib_deps = ${common_teensy.lib_deps}
+
+[env:teensy41]
+board = teensy41
+platform = ${common_teensy.platform}
+upload_protocol = ${common_teensy.upload_protocol}
+build_flags = ${common_teensy.build_flags}
+lib_deps = ${common_teensy.lib_deps}