Skip to content

Instantly share code, notes, and snippets.

@somebox

somebox/teensy-41-guide.md

Created June 29, 2025 01:40
Show Gist options
  • Save somebox/d969f8a97e5a4362af5049ed554a9e69 to your computer and use it in GitHub Desktop.
Save somebox/d969f8a97e5a4362af5049ed554a9e69 to your computer and use it in GitHub Desktop.
Download ZIP
Teensy 4.1 Best Practices
Raw
teensy-41-guide.md

Teensy 4.1 Microcontroller: A Community Reference Guide

This guide synthesizes practical knowledge, best practices, and known issues for the Teensy 4.1 microcontroller, based on extensive community discussions. It is intended for developers, hobbyists, and engineers designing circuits and software with the Teensy 4.1. The information was reviewed by a human, with summarization and structuring help from Gemini 2.5 Studio.

Getting Started: Development Environment & Toolchain

Arduino IDE & Teensyduino Setup

  • Best Practice: For reliable development, use the official Teensyduino installer with a supported version of the Arduino IDE.
    • For Arduino IDE 1.8.x, only specific versions are supported, with 1.8.19 being the most recommended. Teensy support must be added by running the Teensyduino installer and pointing it to the IDE's location.
    • For Arduino IDE 2.x, board support is added via the Boards Manager. You must add https://www.pjrc.com/teensy/package_teensy_index.json to File > Preferences > Additional Boards Manager URLs.
  • Known Issue (IDE 2.x Index Download): The IDE can appear to hang while downloading the Teensy board index file. This is often caused by a bug where the process stalls if the Serial Monitor is open. Close the Serial Monitor to allow the index download to complete quickly.
  • Known Issue (Windows 11 UI): The "Additional Boards Manager URLs" field in Arduino IDE 2.x Preferences may be hidden. Use the mouse wheel or TAB key to navigate to and reveal this field.
  • Best Practice (Library Management): The Arduino IDE prioritizes libraries in Documents/Arduino/libraries. An older or incompatible library here can override the correct version bundled with Teensyduino, causing compilation errors. If you encounter unexpected library-related errors, check this folder for duplicates and remove them.

Compiler, Linker, and Optimization

  • C++ Standard: The Teensy 4.1 toolchain is tested against and supports the C++17 standard. C++20 is not officially supported.
  • Link-Time Optimization (LTO): LTO options are available under Tools > Optimize in the Arduino IDE but require a recent Teensyduino version (1.59+). LTO can expose latent code issues, such as One Definition Rule (ODR) violations in libraries like LittleFS, which have since been fixed in newer releases.
  • Custom Compiler Flags: The Teensy build system does not honor generic platform.local.txt flags like compiler.cpp.extra_flags by default. To add custom flags, you must first modify the core platform.txt file to include these variables in its compilation recipes.
  • Headless Development: The standard arduino-cli upload command requires a GUI environment. For headless systems (e.g., Raspberry Pi Lite), compile the .hex file first, then use the separate teensy_loader_cli utility for the upload.

Hardware Design & Interfacing

Power Management & Electrical Safety

  • Fact (Voltage Levels): Teensy 4.1 operates at 3.3V logic levels. Its I/O pins are NOT 5V tolerant. Applying more than 3.3V to any general-purpose I/O pin will cause permanent damage.
  • Best Practice (External Power): The VIN pin accepts an external voltage, with an official maximum of 6V, though staying at 5V is safest.
  • Critical Warning (VUSB/VIN Separation): If using an external power source on VIN, you must cut the trace between the VUSB and VIN pads on the bottom of the board. Failure to do so can back-feed voltage to your computer's USB port, causing damage.
  • Best Practice (Inrush Current): Large peripheral capacitors can draw significant inrush current, potentially delaying the Teensy's startup or tripping USB host protection. Use a powered USB hub or a dedicated load switch (e.g., TPS214x, BL2555) for high-capacitance loads.
  • Best Practice (Noise Mitigation): For sensitive analog circuits, power them from a separate, clean supply rather than the Teensy's 3.3V LDO. Add bypass capacitors (e.g., 10uF) near the Teensy's 3.3V pin and as close as possible to the power pins of all external components.
  • Fact (USB Host Power): The Teensy 4.1's USB Host port (VHST pin) provides a software-controllable 5V rail with built-in current limiting (~850mA hardware limit, but practically limited by the main 0.5A fuse if USB-powered). This is a feature unique to the T4.1.

General Purpose I/O (GPIO)

  • Performance: digitalWriteFast() and digitalToggleFast() are highly optimized and provide extremely fast I/O, capable of generating software-driven signals in the low MHz range. No external library is needed for these functions.
  • Pin States at Boot: GPIO pins are not guaranteed to be tri-stated at power-up. The NXP ROM, which runs first, may drive certain pins (notably UART1 pins 24 and 25) to a HIGH state.
  • INPUT_PULLUP: Use pinMode(pin, INPUT_PULLUP) for connecting switches to ground. This activates an internal ~47kΩ pull-up resistor, eliminating the need for external components.
  • Debouncing: The high speed of the Teensy 4.1 makes it very sensitive to mechanical switch bounce. Use a library like Bounce2 for reliable button input.
  • Synchronization: Sequential digitalWriteFast() calls to multiple pins are not perfectly simultaneous. For true atomic, multi-pin state changes, direct port register manipulation is required.

Analog-to-Digital Converter (ADC)

  • Known Issue (Precision): The Teensy 4.1's internal ADC is generally less precise than those on older Teensy 3.x boards due to silicon design trade-offs favoring digital speed.
  • Best Practice (Source Impedance): The ADC is sensitive to high source impedance, which can cause inaccurate readings due to "kickback" current. For high-precision measurements, buffer the input signal with a low-impedance source, such as an op-amp, and use an RC filter at the ADC input.

Pin & Peripheral Conflicts

  • SPI Pins: Initializing an SPI peripheral (e.g., via SD.begin(cs_pin) for an external SD card) will configure pins 11 (MOSI), 12 (MISO), and 13 (SCK) for SPI use, making them unavailable for GPIO.
  • Audio Library: The Audio library can conflict with other DMA-based libraries (like FastLED/ObjectFLED). This is often a low-level hardware resource contention, which can sometimes be mitigated by adjusting timing parameters in the conflicting library.

Communication Interfaces

USB (Device & Host)

  • USB Serial vs. Hardware UART: The native USB port (Serial) is orders of magnitude faster than hardware UARTs (Serial1, Serial2, etc.). USB Serial can achieve >20 MB/s, while hardware UARTs are limited to a few Mbit/s.
  • Known Issue (USB Serial Output): Initial data sent via Serial.println() may be lost or jumbled. This is often a host-side issue.
    • Best Practice: Use while(!Serial && millis() < 5000) {} to wait for the connection to be established without blocking indefinitely. Adding a small extra delay(2) after this loop can also improve reliability.
  • Known Issue (Windows COM Ports): Windows can incorrectly assign the same COM port to multiple Teensy boards. This is an OS-level issue, not a Teensy fault.
    • Best Practice: Use the teensy_ports.exe command-line utility to diagnose. Resolve the conflict by manually reassigning COM ports in Windows Device Manager.
  • USB Host Mode: The dedicated USB Host port allows the Teensy to control other USB devices (keyboards, mice, MIDI, hubs). It requires the USBHost_t36 library. A powered USB hub is recommended for connecting multiple devices.
  • USB Isolation: Teensy 4.1 requires a high-speed (480 Mbps) compatible USB isolator. The "Hifime Hi-Speed USB Isolator v2" is a verified working solution. Standard ADUM3160-based isolators are too slow.

Hardware Serial (UART)

  • Pin Remapping: UART pins can be remapped to alternates using SerialX.setRX(pin) and SerialX.setTX(pin) before calling SerialX.begin(). This is useful for avoiding pin conflicts.
  • Half-Duplex: Hardware half-duplex (single-wire) communication is supported via SerialX.begin(baud, SERIAL_HALF_DUPLEX). For external transceivers, use SerialX.transmitterEnable(dir_pin).
  • Polarity Inversion: Hardware TX signal inversion is supported via the SERIAL_8N1_TXINV flag in begin().
  • Buffering: The default 64-byte hardware serial transmit buffer can be increased with addMemoryForWrite() to prevent blocking on large data writes.
  • Known Issue (LPUART Mapping on MicroMod): On Teensy MicroMod, the underlying LPUART hardware for Serial2 and Serial4 is swapped compared to the standard T4.0/T4.1. Be aware of this when working with these ports on a MicroMod.

SPI (LPSPI, FlexSPI, FlexIO)

  • LPSPI (Standard SPI):
    • The standard SPI library uses the LPSPI peripheral.
    • Fact: The official maximum reliable clock speed for LPSPI is 30 MHz. Exceeding this risks data errors due to setup/hold time violations.
    • Best Practice (Signal Integrity): For high-speed SPI, especially with external wiring, add series termination resistors (50-220Ω, 100Ω is common) on the MOSI, SCK, and CS lines, placed close to the Teensy's pins.
  • FlexSPI (High-Speed Memory Interface):
    • This is a specialized, high-speed interface primarily for external Flash and PSRAM, accessible on the bottom pads of the T4.1.
    • It is not a general-purpose SPI port and requires complex, low-level configuration of Look-Up Tables (LUTs) for use with non-memory devices.
    • Fact: The DQS (Data Strobe) feature for compensating signal delay is exclusive to FlexSPI.
  • FlexIO (Emulated SPI):
    • The FlexIO peripheral can be configured to emulate SPI and other serial protocols.
    • It can achieve clock speeds higher than LPSPI's 30 MHz limit.
    • Limitation: FlexIO-emulated SPI is typically half-duplex.

I2C & I2S Audio

  • Known Issue (I2C & Audio Conflict): I2C communication can become unstable when the Teensy is an I2C slave and I2S audio is simultaneously active.
    • Workaround: This hardware-level issue can often be mitigated by adding a small RC filter (e.g., 1kΩ series resistor and 22pF capacitor to ground) on the SCL line of the I2C slave.
  • I2S for Multi-Channel Audio: For more than 2 channels of simultaneous audio I/O, the TDM (Time Division Multiplexing) protocol is required. The Teensy Audio Library and compatible hardware support this.

Ethernet & WiFi

  • Fact (Ethernet Chip): Some Teensy 4.1 boards are sold without the Ethernet PHY chip ("NE" versions). Manually soldering this chip is extremely difficult and not recommended.
  • Performance: The native Ethernet interface with the QNEthernet library can achieve nearly 100 Mbit/s throughput on a LAN.
  • WiFi: There is no built-in WiFi. External modules (like ESP32 "AirLift") are used, but performance can be a bottleneck. The ESP32-SPI bridge setup is often limited to ~100 KB/s and can be unstable.

Memory & Storage Management

Internal Memory (RAM & Flash)

  • Fact (Memory Regions): The T4.1 has multiple RAM regions. RAM1 is split into fast ITCM (for code) and DTCM (for variables/stack). RAM2 is used for DMA-capable memory (DMAMEM) and dynamic allocations (malloc/new).
  • DMAMEM and EXTMEM Initialization: Variables declared with DMAMEM (in RAM2) or EXTMEM (in external PSRAM) are not automatically initialized to zero at startup. You must explicitly initialize them in your code, for example, by using memcpy from a PROGMEM constant array.
  • PROGMEM and PSTR() for Flash Storage:
    • Use const and PROGMEM to store constant data (like large lookup tables) in Flash, preventing it from consuming RAM.
    • By default, string literals are copied to RAM at startup. Use the PSTR() macro to keep them in Flash.
    • Known Issue: The compiler de-duplicates identical string literals. Using PSTR() on identical strings will defeat this optimization and may increase Flash usage. It is most effective for unique strings.

External Memory (PSRAM & SDRAM)

  • PSRAM: Optional PSRAM chips (e.g., 8MB or 16MB) can be soldered to the bottom of the T4.1. Check the PJRC website for a list of compatible chips. ips6404lsq is a verified compatible part.
  • SDRAM: More complex to integrate than PSRAM, SDRAM requires a custom PCB and careful trace length matching. A 10pF capacitor on the EMC_39 pin is critical for stability.

Non-Volatile Storage (EEPROM, SD Cards, External Flash)

  • EEPROM: The Teensy 4.1 has emulated EEPROM with built-in wear-leveling. The EEPROM.put() function only writes if the data has changed, making it very durable for typical use cases (e.g., saving user settings). For high-frequency data logging, EEPROM is not suitable.
  • SD Cards (Onboard SDIO): Use SD.begin(BUILTIN_SDCARD) to access the onboard microSD slot. This uses the fast SDIO interface and does not conflict with the main SPI pins (11, 12, 13).
  • SD Cards (External SPI): External SD card readers are connected via SPI. The SdFat library offers advanced configuration options, including using alternate SPI ports (SPI1, SPI2).
  • External QSPI Flash: The pads on the bottom of the T4.1 can also be used for an external QSPI Flash chip (up to 256MB). This memory must be accessed via a filesystem like LittleFS. It cannot be used to extend the program memory.
  • Best Practice (LittleFS Performance): For optimal performance when writing numerical data, use binary I/O (file.write(), file.read()) instead of text-based I/O (file.println()). Repeatedly removing and writing files can degrade LittleFS performance; consider periodic formatting or using formatUnused().

Controlling Common Peripherals

Displays (SPI & Parallel)

  • Library Compatibility: Many display libraries intended for other platforms may use legacy register names (KINETISK_SPI0) and will not compile for Teensy 4.x. Use Teensy-optimized libraries (e.g., ILI9341_t3, ST7735_t3).
  • Multi-Display Setup:
    • When sharing an SPI bus, each display needs a unique Chip Select (CS) pin.
    • If displays share a Reset (RST) pin, initializing one will reset all. Pass -1 as the RST pin in the constructor to manage the reset line manually.
  • Troubleshooting: Blank or flickering displays after a successful upload usually point to a hardware wiring issue (CS and DC pins are common culprits) or a driver/controller mismatch.

Addressable LEDs (WS2812B)

  • Best Practice (Level Shifting): WS2812B LEDs require a 5V data signal. The Teensy's 3.3V output may work but is unreliable. Use a 3.3V-to-5V level shifter (e.g., 74AHCT125) for robust operation.
  • Best Practice (Software): Use hardware-accelerated libraries like WS2812Serial for non-blocking, high-performance control. Note that these libraries often work only on specific hardware-capable pins (e.g., Pin 1).

Servos & Stepper Motors

  • Servo Library: The standard Arduino Servo.h is incompatible. Use the PWMServo library included with Teensyduino.
  • Known Issue: The PWMServo::detach() method is unimplemented on Teensy 4.x and will cause a linker error.
  • Stepper Motors: Use genuine Pololu DRV8825 drivers for reliability. Increase microstepping to reduce mechanical vibration. Use the QuadEncoder library to leverage the T4.1's hardware quadrature decoders for efficient position tracking.

Audio (Input & Output)

  • Best Practice: The Teensy Audio Library is the recommended and most robust solution for audio projects.
  • Noise: The Audio Shield's inputs can be noisy. Ensure proper grounding and short I/S signal paths. Class D amplifiers (like PAM8403) can inject significant noise into power rails; use dedicated power and filtering.
  • Outputs: The Audio Shield's LINE OUT is for line-level signals and cannot drive low-impedance speakers directly. Use an external amplifier. The HEADPHONE jack has a virtual ground (VGND) that must not be connected to the system GND.

Troubleshooting & Debugging

Common Boot & Upload Issues

  • Program Button: The button on the Teensy is a PROGRAM button, not a RESET button. It forces the board into bootloader mode.
  • 15-Second Restore: If a Teensy becomes unresponsive, holding the PROGRAM button for ~15 seconds initiates a full flash erase and restores a factory blink sketch. This is a crucial recovery tool.
  • Blinking Red LED: A slowly blinking red LED in bootloader mode means the Teensy is not detecting any USB communication from the host. This is almost always due to a faulty or "charge-only" USB cable. A solid red LED indicates a successful connection.
  • 4-Blink Code: A repeating 4-blink pattern from the red LED indicates a problem with the 24MHz crystal oscillator, often caused by physical contamination (flux) or damage.

Crash Diagnostics

  • CrashReport: Teensy 4.x has a built-in CrashReport feature. Print this to Serial in setup() to see details about the last crash.
  • addr2line: Use the arm-none-eabi-addr2line utility (part of the Teensy toolchain) with the memory address from a CrashReport and the compiled .elf file to find the exact source file and line number that caused the crash.
  • Breadcrumbs: Use CrashReport.breadcrumb(num, value) to leave markers in your code, helping to trace the execution path leading up to a crash.

Advanced Topics & Customization

Custom Board Design & Bootloader

  • Bootloader Chip: Custom boards must use the PJRC MKL02 bootloader chip, purchased directly from PJRC.
  • Board Identification: The bootloader identifies the board model (4.0, 4.1, or Micromod) by reading the JEDEC ID of the external flash memory chip. This choice is critical as it affects which core library features are enabled.
    • 2MB Flash -> Teensy 4.0
    • 8MB Flash -> Teensy 4.1
    • 16MB Flash -> Teensy Micromod
  • Code Security: Custom boards with a new iMXRT chip and MKL02 bootloader are "lockable" by default. The security process involves permanently writing keys to OTP fuses. Back up your key.pem file; its loss is irreversible.

Performance & Optimization

  • Overclocking: The CPU can be overclocked via the IDE or programmatically with set_arm_clock(). This requires effective cooling (heatsink and/or fan) and active temperature monitoring to prevent crashes or permanent damage. Overclocking is done at your own risk and will likely shorten the chip's lifespan.
  • Assembly Language: While possible, writing assembly is rarely necessary. The GCC compiler is highly optimized for the ARM Cortex-M7. For performance gains, it's often more effective to analyze the compiler's output (.lst file) and restructure C++ code to enable better optimization.

RTOS Integration (Zephyr)

  • The Zephyr RTOS has official support for Teensy 4.x boards, offering advanced multi-threading and task management.
  • It uses a complex Device Tree (.dts) and Kconfig system for hardware configuration, which presents a steep learning curve.
  • It is a powerful option for complex, concurrent applications, but requires careful consideration of thread safety for existing code.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment