diff --git a/.gitignore b/.gitignore index cd1845a..b94f8c2 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,9 @@ $RECYCLE.BIN/ # Build folder build +.pio* +.pioenvs +.piolibdeps # # ========================= diff --git a/README.md b/README.md index da845d2..5e64182 100644 --- a/README.md +++ b/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 2 I2C 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. 3 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 diff --git a/grblHAL_Teensy4/platformio.ini b/grblHAL_Teensy4/platformio.ini new file mode 100644 index 0000000..1d285e5 --- /dev/null +++ b/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 = + + +# +# 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}