Merge pull request #3 from brianredbeard/platformio-config
docs: Document use of PlatformIO
This commit is contained in:
Terje Io
GitHub
commit
9843c73a48
|
|
@ -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