## iMXRT1062 Driver A grblHAL driver for the NXP iMXRT1062 processor on a [Teensy 4.x board](https://www.pjrc.com/store/teensy40.html). Available driver options can be found [here](main/my_machine.h). See [Compiling](#Compiling) for more information on building. --- __Important!__ There is a "bug" in Teensyduino prior to v1.54 that may cause [periodic stalls](https://github.com/grblHAL/iMXRT1062/issues/6) in processing. It is possible that this is only happening when networking is enabled and then not always so. Regardless of whether networking is enabled or not it is recommended that [Teensyduino v1.54](https://www.pjrc.com/teensy/td_download.html) is used to build this driver. --- #### Networking plugin The networking plugin is for Teensy 4.1 and needs the [teensy41_ethernet lwIP library](https://github.com/ddrown/teensy41_ethernet) forked by ddrown. Telnet, websocket and ftp protocols are currently supported, http is on the long term roadmap. #### SD card plugin The SD card plugin needs the [uSDFS library](https://github.com/WMXZ-EU/uSDFS) by WMXZ-EU. Important: edit the [utility/sd_config.h](https://github.com/WMXZ-EU/uSDFS/blob/master/src/utility/sd_config.h) file and change `#define USE_MSC 1 // will be used in sd_msc.cpp` to `#define USE_MSC 0 // will be used in sd_msc.cpp` or add the MSC library as well \(not needed\). 2021-06-08: This is now changed in the latest version. **NOTE:** If enabling ftp transfer to the SD card then [utility/sd_sdhc.c](https://github.com/WMXZ-EU/uSDFS/blob/master/src/utility/sd_sdhc.c) has to be replaced with [this patched](patches/sd_sdhc.zip) version \(zip download\). I submitted a PR for this but it was rejected with no explanation, this is why I have added it here. The maintainer has made a similar change but that does not fix the underlying issue, and it may even crash the controller. In addition to this [ffconf.h](https://github.com/WMXZ-EU/uSDFS/blob/master/src/ffconf.h) has to be edited, `#define FF_FS_RPATH` value has to be changed to 2 \(from 1\) or you will get a compiler error. --- Download the libraries above as zip files and add to your Arduino installation with _Sketch > Include Library > Add .ZIP Library..._ --- #### Board maps: | |N_AXIS|Ganged axes1|Ethernet|EEPROM |SD card|I2C Keypad|Encoders|Digital I/O|Analog I/O| |---------------------------------------------------------------------------------|------|----------------------------|--------|---------------|------------|----------|--------|-----------|----------| |Generic | 3 |no |no |yes2|yes |yes | - | - | - | |[BOARD_T40X101](https://github.com/phil-barrett/grbl-teensy-4) for Teensy 4.0 |max 4 |max 1 |no |yes2|no |yes | max 1 | - | - | |[BOARD_T41U5XBB](https://github.com/phil-barrett/grbl-teensy-4) for Teensy 4.1 |max 5 |max 2 |yes |yes2|yes |yes | max 1 |4/3 or 1/33|-| |[BOARD_T41BB5X_PRO](https://github.com/phil-barrett/grbl-teensy-4) for Teensy 4.1|max 5 |max 2 |yes |yes \(FRAM\) |yes |yes | max 1 |4/3 or 1/33|-| 1 Each enabled reduces N_AXIS with one. Currently the board map file must be edited to enable ganged/auto squared axes. 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-07-11