docs: Document use of PlatformIO
This contains documentation (README.md), configuration (platformio.ini), and relevant entries for `.gitignore` providing a working PlatformIO setup for the Teensy 4.x platform. Additional care was taken to extend the configuration beyond the most basic level, demonstrating how common and board specific entries may be used together.
This commit is contained in:
Brian 'Redbeard' Harrington
parent
0f2e698d9f
commit
a11a5fbfcf
|
|
@ -25,6 +25,9 @@ $RECYCLE.BIN/
|
|||
# Build folder
|
||||
|
||||
build
|
||||
.pio*
|
||||
.pioenvs
|
||||
.piolibdeps
|
||||
|
||||
#
|
||||
# =========================
|
||||
|
|
|
|||
140
README.md
140
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
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
Loading…
Reference in New Issue