Skip to content

Latest commit

 

History

History
180 lines (131 loc) · 9.49 KB

README.md

File metadata and controls

180 lines (131 loc) · 9.49 KB
Raw

iMXRT1062 Driver

A grblHAL driver for the NXP iMXRT1062 processor on a Teensy 4.x board.

Available driver options can be found here.

This driver can be built with the Web Builder, see Compiling for more information on building.

Important! There is a "bug" in Teensyduino prior to v1.54 that may cause periodic stalls 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 is used to build this driver.

Networking plugin

The networking plugin is for Teensy 4.1 and needs the teensy41_ethernet lwIP library, updated to lwIP 2.1.3 and configured for grblHAL.

SD card plugin

The SD card plugin needs the uSDFS library, patched for bugs and configured for grblHAL.

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 for Teensy 4.0 max 4 max 1 no yes2 no yes max 1 - -
BOARD_T41U5XBB for Teensy 4.1 max 5 max 2 yes yes2 yes yes max 1 4/3 or 1/33 -
BOARD_T41BB5X_PRO for Teensy 4.1 max 5 max 2 yes yes (FRAM) yes yes max 1 4/3 or 1/33 -
BOARD_GRBLHAL2000 for Teensy 4.1 max 5 max 2? yes yes yes 4/?

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 and must be added to the board. FRAM is recommended when the Odometer plugin is added to the build.
3 Number of digital input pins available is reduced when the Encoder plugin 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.

Arduino IDE

This driver compiles and uploads from the Arduino IDE and is partially dependent on the Arduino framework. Teensyduino is required and must be added to the Arduino IDE.

See the Wiki-page for compiling grblHAL for instructions for how to import the project, configure the driver and compile.

PlatformIO

About

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 for directions on installing in the desired manner.

Next we will clone this repository, ensuring that all submodules have been retrieved:

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.

Next, make any desired edits to the file src/my_machine.h

Begin compilation by running the command:

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) 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 page in the PlatformIO documentation.

To execute our upload, run the following command:

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:

git pull --recurse-submodules

2023-09-20