Teensy 4.1 Released

Teensy 4.1 is now available with access more I/O and memory expansion.

Teensy 4.1 features a 10/100 Mbit Ethernet PHY.

The Ethernet port also has IEEE1588 precision packet timestamping.

Fast Ethernet opens up possibility for low latency & high bandwidth Artnet LED projects, streaming audio, open sound control and other Ethernet-based protocols that were difficult to accomplish with a traditional SPI-based Ethernet shield.  Traditionally use of Ethernet in a project has involved a choice of single board computers with high bandwidth Ethernet using systems not designed for low latency tasks, versus microcontrollers designed for real-time tasks but with slow Ethernet or lacking performance to handle Ethernet’s speed.  Teensy 4.1 with a Cortex-M7 processor at 600 MHz opens up the possibility to use the high bandwidth and low latency of Ethernet on a microcontroller designed for real-time tasks.

Teensy 4.1 includes a USB host port, supporting 480 Mbit/sec high speed USB.  While Teensy 4.0 has those USB host data signals on surface mount pads, Teensy 4.1 adds the hot-plugging power management needed to simply connect a USB host cable and be able to plug in a USB device.  Or a USB hubs can be used to connect many USB devices.

USB devices are supported by the USBHost_t36 library, which is installed into the Arduino IDE automatically by the Teensyduino installer.

Another feature technically present on Teensy 4.0, but difficult to use, is native SDIO for fast data transfer to a SD card.  Teensy 4.1 includes the SD socket, so you can easily use a micro SD card with the card’s native SDIO protocol rather than slow SPI access.

Teensy 4.1 also includes locations to solder additional memory chips.  The larger space is meant for a QSPI flash memory and the smaller space is intended for a 8MB PSRAM chip.

The IMXRT1062 microcontroller on Teensy 4.0 and 4.1 has 1MB of RAM built in.  For many real-time control projects, the internal RAM is plenty.  But some projects can greatly benefit from the added memory.  Frame buffers for high resolution TFT displays are the most common use, allowing advanced graphics rendering.  Large memory is also very useful for special audio effects like advanced reverb, buffering fast incoming data before logging to a SD card, and for emulation of retro computer systems like classic arcade games.


These extra memory chips have a dedicated QSPI bus, which is independent from Teensy 4.1’s main program memory.  When a flash memory chip added for storage of files or other data, this dedicated bus means it does not interfere with normal program memory access.  This is especially valuable while writing data or erasing sectors in the extra flash memory.  For real time projects controller motors, synthesizing or processing real-time audio, communicating high speed data or other tasks requiring low latency, flash writing can be done to the extra flash chip without blocking access to the normal program memory.

Teensy 4.1’s larger form factor also bring more I/O pins, and makes the difficult-to-access bottom pads from Teensy 4.0 very easy to access, breadboard-friendly pins.  The new I/O pins bring an 8th serial port, more analog inputs and PWM outputs, and access to 16 contiguous native port pins, useful for projects needing fast parallel I/O.

Not every project requires so much I/O or extra memory.  Teensy 4.0 fills those needs.  But when you do need more I/O, more memory, fast Ethernet, or connecting USB devices or fast SD card access, the larger Teensy 4.1 brings this extra I/O capability to a platform designed for real-time use with fast 600 MHz M7 performance.

Teensyduino 1.44 Released

Teensyduino version 1.44 has been released.

The 1.44 installers are available at the downloads page.

Arduino 1.8.7 Support

Only a few weeks after 1.8.6, Arduino released 1.8.7.  With a new Arduino comes a new Teensyduino release to support it.

Arduino 1.8.7 fixes several rare but serious bugs, including issues with the IDE being able to start up.  1.8.7 adds no new features, so there’s no need to upgrade from 1.8.6, unless you’ve encountered issues.

Wavetable Synthesis

A little over 1 year ago, a group of students at Portland State University (Ryan Mellmer, Nicholas Craig, Joshua Bucklin, Aida Keifer, Jonathan Jensen, Yu Tang, Connor Delaplane) completed their capstone project to perform wavetable sound synthesis, for playing of musical notes from sound samples.  PJRC provided hardware and Paul “sponsored” the group.  Dr. Bart Massey advised.

The complete code was published on github.  Now with 1.44, this project has been integrated into the Audio library.  It’s now available in the design tool, and the examples can be accessed in Arduino by clicking File > Examples > Audio > Synthesis > Wavetable.

Wavetable data is stored in Teensy’s internal flash memory.  To create the data, Ryan’s team create a Python utility to import and convert Soundfont format files.

A version of their SoundfontDecoder updated for the Audio library is also available on github.

Faster Ports Menu

Teensyduino 1.42 greatly improved how Teensy is shown in Arduino’s Tools > Ports menu.  But under some circumstances on Macintosh and Windows, a noticeable lag could occur when clicking the Tools menu.  1.44 eliminates this interactive delay, so the Tools menu responds quickly.

The Teensy specific Ports menu is implemented by a native helper program called “teensy_ports”, which Arduino automatically runs at startup.  Because this is a native program, it can gain detailed info about USB devices which isn’t available to Java code in the Arduino IDE.  In 1.42 & 1.43, when you clicked the Ports menu, a query was sent to this program.  When it responded, the info would be put into the Ports menu.  But if anything caused a delay in the response, you would see that delay in the appearance of the Tools menu.

Version 1.44 changes teensy_ports to always send USB device changes as they occur.  A dedicated Java thread listens for the incoming USB info and keeps a list of devices in the IDE updated.  When you click the Tools menu, rather than requiring communication back-and-forth, the list already in the IDE’s memory is copied for use by the menu.

This improvement was partially motivated by a conversation with the Arduino developers.  They intend to eventually allow boards like Teensy to provide their own port “discovery” tools, using a JSON-based format.  This is one of the major missing features which requires Teensy to have a special installer, rather than using Arduino’s Boards Manager.

Another benefit of switching to the JSON format, which allows communicating all info Arduino uses, is the Tools > Get board Info menu now works with Teensy.

The multithreaded JSON-based Ports menu was developed on 1.8.6 and ported to 1.8.7 and back-ported to 1.8.5, so you get this speedup on any of those versions.

Linux 64 bit ARM (AARCH64)

Arduino 1.8.7 is the first non-beta Arduino release which supports Linux on 64 bit ARM, also known as “AARCH64”.  Jetson TX1, Jetson TX2 and Odroid C2 are the main platforms needing AARCH64 support today.

However, Arduino’s downloads page still has ARM64 only on the hourly build and beta build sections.  The Arduino 1.8.7 ARM64 file is actually on their server and can be accessed by copying the link to the ARM32 version, and replace “arm” with “aarch64”.

The final hold-up is due to Oracle’s Java runtime environment (JRE) for 64 bit ARM.  It is “headless”, meaning it only supports command line programs.  Unlike the other Linux copies, there is no “java” folder with the correct Java runtime.  As a result, the IDE will use whatever Java runtime exists on your Linux system, which may or may not be compatible.

Here is a copy of Arduino 1.8.7 with a compatible copy of OpenJDK added in the “java” folder.  Other this this addition, it is identical to the Arduino 1.8.7 file on Arduino’s server.


Just extract this file, then download and run the Teensyduino 1.44 installer.  Like all Linux systems, Teensy’s udev rule file must be installed to access the USB device files.

The default kernel that ships with Jetson lacks the cdc_acm driver needed for USB serial communication.  You can still use Teensy without this this driver, because Teensy Loader uses HID protocol, and the new Ports menu is able to natively detect USB devices even when their drivers don’t load.  But to use the serial monitor with a Teensy programmed to be USB serial, you will need to install the cdc_acm driver.  If following those instructions, you may need to type “./installCDCACM.sh” to run the script, rather than “./installCDCACMModule.sh” as the instructions say.

Obviously AARCH64 support is very new.  If you encounter issues, please report them on the forum.

Teensyduino 1.43 Released

Today PJRC is releasing Teensyduino version 1.43.

The 1.43 installers are available now at the downloads page.

Arduino 1.8.6 Support

The main new feature in 1.43 is support for Arduino 1.8.6.  The main reason to upgrade is 1.8.6 can compile your code significantly faster.

Arduino 1.8.6 is the first non-beta Arduino IDE to support parallel compile.  If your computer has a quad-core processor, when rebuilding all files, Arduino may compile up to 4 pieces of code at the same time.  Usually the speed increase is much less than 4 times faster, but still it manages to compile code in much less time than running every compiler process 1 at a time.

When you change boards or settings, a full rebuild of all libraries files must be done for all library files your code uses.  Arduino 1.8.2 to 1.8.5 would often do this full rebuild unnecessarily, especially if you edited any of the library files (not in the Arduino IDE’s editor).  1.8.6 fixes this unnecessary rebuilding.

However, not everything is perfect with 1.8.6.  Several bugs were discovered after release which cause 1.8.6 to crash, especially if certain data files are corrupted.  Teensyduino 1.43 includes fixes for a couple of these bugs.  The rest will be fixed in Arduino 1.8.7, which may appear soon.  When it does, of course we’ll release Teensyduino 1.44 to support it.

Headless Install

The installer now support a “headless” command line install.  This can be useful if you wish to create scripts to automatically install Teensyduino.  The main intended use is for Continuous Integration testing with systems such as Travis-CI.

Run the installer with –dir=<directory> to specify the Arduino install location.  Using this option cases the installer to run automatically without the GUI.

Adafruit has offered to include Teensy in their automated testing script.  Soon this will allow Teensy to be automatically tested (at least to verify libraries compile without error) for all of Adafruit’s libraries!

Bugs Fixed

Several issues are fixed in version 1.43.

  • Fix default Ethernet CS pins on Teensy 2.0 & Teensy++ 2.0.  Old versions of Ethernet would default to the “SS” pin on AVR chips, and if you wanted any other pin your only option was to edit the Ethernet library code!  With the addition of Ethernet.init(pin), you could choose which pin to use, but this change also caused the default to become pin 10, even if SS was a different pin on your board (as it is with Teensy 2.0 & Teensy++ 2.0).  Now the default is restored to the actual SS pin, and you can use Ethernet.init(pin).
  • Fix USB Keyboard ‘#’ for UK & Irish layouts.
  • Generic UDP class support beginMulticast.  Some libraries using multicast need this defined in the board’s core library.
  • Fix USB MIDI hogging transmit buffers.  If you used USB MIDI together with USB Serial or other USB communication, and you transmit USB MIDI messages faster than your computer can process, previously the MIDI message could consume all the USB buffer memory.  This fix prevents MIDI from hogging all the buffers, so the other non-MIDI communication (hopefully) will not stall.
  • Fix FreqCount for use at high frequencies.  A bug which caused very infrequent errors when measuring very high frequencies has been fixed.
  • Fix SerialPlotter for Ports(Teensy).  Previously Arduino’s Serial Plotter would only work if you had selected Tools > Ports from the “Serial” section of the menu.  Now the “Teensy” ports section is fully supported.  When using a “Teensy” port, board disconnect and reconnect are supported.  The plot restarts from zero when you plug the cable in.  Proper stop and restart is also supported when you upload new code.
  • USBHost_t36 fix for Gigabyte keyboard (thanks KurtE).  These special gaming keyboards with “N Key Rollover” should now work.
  • OctoWS2811 update movie2serial.pde for compatibility with Processing 3.4.  This program streams video to large LED projects.  Minor updates were needed to work with the newest version of Processing and its video library.
  • Remove BYTE define.  This was previously included in Teensyduino for pre-1.0 Arduino compatibility.  But some libraries and code tend to use “BYTE” for their own constants and variables, causing a conflict.  This feature for compatibility with ancient Arduino libraries was causing more harm than good.  It’s been removed.
  • Update WS2812Serial documentation.  A mistake in the documentation showed an extra pin, which was never actually supported and can’t work due to hardware limitation.
  • Improve installer help dialog on Windows.  The “Windows App” incompatible with Teensyduino.  The installer now mentions this in the “?” help dialog.
  • Workaround a rare USB buffering issue.  During sustained fast data transfer from a PC to Teensy, a rare bug could cause wrong data to be received after many megabytes of transfer.  A workaround was added to prevent this problem.  Special thanks to Trammell Hudson for providing a test case.
  • Fix for Arduino 1.8.6 startup (Arduino issue #7917).  If any library you have installed has a version number which Arduino 1.8.6 can’t understand, the IDE crashes at startup.  A fix for this problem is included, so you aren’t left with the software unable to run if you have a “bad” library installed.
  • Add Arduino’s fix for slow 1.8.6 menus on Mac (Arduino issue #7935).  Newer versions of Java on Macintosh are much slower to create menus.  The Arduino developers worked around this problem by creating the menus only once, and they’re merely modified when changes are needed.  Teensyduino 1.43 adds this fix to your copy of 1.8.6.



Teensyduino 1.42 – What’s New

Today PJRC is releasing Teensyduino version 1.42.

Here’s a detailed look at 1.42’s many new features and improvements.

I’d like to thank everyone who contributed & beta tested, especially Defragster!

The 1.42 installers are available now at the downloads page.

Arduino IDE Ports Menu & Serial Monitor

Since 2009 Teensy has supported non-Serial USB types (selected in the Tools > USB Type menu), but Arduino’s Ports menu has worked only with Serial devices.  1.42 extends the Ports menu with a new “Teensy” section capable of showing every USB type Teensy implements.

In this screenshot, 3 Teensy boards are connected, but only 1 is programmed to be Serial.

Teensyduino’s non-Serial modes include a HID interface to emulate serial, so you can still use Serial.print() to the Arduino Serial Monitor.  Arduino’s “Serial ports” list is still present, where you would select “(emulated serial)” to use those other boards.  The new “Teensy” ports list allows you clearly see which boards are really connected and to precisely choose the one you want.

Selections from this new Teensy Ports list are based on the physical USB port, plus any USB hubs.  This info is shown in the lower right corner.

Here “usb2/2-1/2-1.2/2-1.2.2” is a Linux syntax meaning port 2 of a hub plugged into port 1 of the 2nd USB controller.  Similar codes are used on Windows and Macintosh.  These physical location codes allow Arduino to target exactly the board you’ve selected, even when it changes USB type.

Physical location allows Teensy auto-reboot to know exactly which Teensy you wish to upload.  Previously (and still if you don’t select from the Teensy ports list) attempting to reboot required searching and trying to reboot whatever boards were found.  If your Teensy isn’t responding to USB (interrupts disabled, deep sleep, etc) the auto-reboot process won’t search for other boards.  It ends quickly.  Of course no software on a PC or Mac can get your Teensy to report if it’s not communicating on the USB, which is why every Teensy is made with a button to force entering programming mode.

When you open the Arduino Serial Monitor with a board selected in the Teensy Ports list, a special version of the serial monitor customized to Teensy is used.

You can easily tell it apart from the normal serial monitor because it lacks the baud rate drop-down selection.  Teensy USB always communicates at full USB speed, not the serial baud rate.

This new serial monitor has many features you can’t easily see.  If you unplug your Teensy while it’s open, the USB disconnect is automatically detected.  Likewise, reconnecting (on the same physical USB port) is automatically detected.  Access to the hardware is done by a native “teensy_serialmon” helper program, rather than a Java serial library, which is meant to solve rare but difficult communication problems some people encounter.

If you want to use the old way, via the Java serial library, just select from the “Serial ports” part of the Ports menu.  Look for the baud rate drop-down list to confirm you’re using the traditional serial monitor.

256K RAM Usable on Teensy 3.5

Some NXP/Freescale’s documentation for the MK64FX512 chip used on Teensy 3.5 says 192K of RAM.  Other documentation says 256K.  We have recently confirmed all these chips really do have 256K RAM.

Teensyduino 1.42 enables access to all 256K, except the last 8 bytes.  Teensy Loader looks at the initial stack address to deduce which board you selected when compiling.  Future versions may improve how the intended board is communicated.  With 1.42, you get to 65528 more bytes of RAM for variables on Teensy 3.5.

USB Touchscreen Emulation

Many modern PCs have touchscreens, which is distinctly different then simply a mouse, because they can track the position of up to 10 fingers.

Starting with 1.42, Teensy can emulate a 10-finger tracking touchscreen.  This quick video demo shows how it works.

After installing 1.42, click File > Examples > Teensy > USB_Touchscreen > TenFingerCircle to open the example used in this video.

Windows, Linux and some Android systems support multi-touch screens.  Unfortunately no Apple Macintosh computers recognize USB multi-touch devices yet.

Audio Library New Features

Many great new features have been added to the Teensy Audio Library for 1.42.  For this article I had wanted to shoot video demos, but the time required would mean holding up the 1.42 release.  For now, here’s a quick summary with photos.  I hope to bring you another detailed article next week with more details.

Audio: FreeVerb

FreeVerb was added, in both mono and stereo.  It implements the high quality reverb algorithm as published by “Jezar” at Dreamport.  FreeVerb’s quality is better than the reverb effect contributed a couple years ago by Joao Rossi FIlho.  However, it uses more memory.  The stereo FreeVerb requires Teensy 3.5 or 3.6, due to RAM usage.

FreeVerb has 2 tunable parameters for “room size” and “damping” to give you control over the effect.  Of course, you can also add a mixer using the FreeVerb “wet” output with the original “dry” signal to tune how strongly the reverb effect is heard.

Audio: Granular Pitch Shift & Freeze

John-Mike of Bleep Labs contributed a granular processing effect.  In the freeze mode it repeatedly replays a short segment of the sound you recently heard.

Pitch shift mode captures grains continuously and plays them back windows overlapping, interpolated to a different speed.  When the parameters are set well, it results in a pretty good real-time pitch shift.  Of course you can also set the parameters not-so-well if you wish to hear a very grainy output!

Audio: Waveforms

The generic waveform synthesis was greatly improve for 1.42, inspired by Bleep Labs, though in the end new code was written.

Variable Triangle has been added to the waveform synthesis, which allows you to change continuously from a sawtooth to triangle.

A long-standing bug with the phase(angle) function has been fixed in 1.42.  You can now create 2 or more waveforms and control their relative phase shift.  Of course all of the waveforms work down to nearly zero, so any can be used as low frequency oscillators (LFOs) to control or sequence effects or other synthesis, now with full control over relative phase timing.

A new modulated waveform synthesis object has also been added.

Previously only Sine_FM offered modulation.  It was limited to one octave of frequency change, and the modulating signal varied the waveform period, which isn’t the proper “volt per octave” model.

The new waveform modulation allows you modulate the frequency of any of the 9 waveforms.  Up to 12 octaves are available (the range is configurable), allowing you to modulate even a sub-sonic LFO all the way up to the top of human hearing range!  The modulating signal uses proper exponential “volt per octave” scaling.

You can also configure the modulation to affect the waveform phase, for 8 of the 9 waveforms.  The amount of phase shifting is also configurable, up to 9000 degrees (±25 full waveform cycles).

Waveform modulation also has a 2nd input, to allow any signal to modulate the Pulse duty cycle and Variable Triangle waveform shape.

Audio: Pulse Density Modulated (PDM) Input

Some very low cost microphones have a special 1-wire pulse density output signal, which must be low-pass filtered to recover the audio signal.

Teensy now supports these PDM signals.  The low-pass filter is implemented as a single 512-tap FIR filter, which should have much better passband performance than the Cascaded Integrator Comb (CIC) filters typically used.  But this does come at a computation cost, approximately 39% CPU usage when running Teensy at 96 MHz.

Audio: Other Improvements

Support for the WM8731 codec chip has been improved, with the ability to properly select between its microphone vs line input.

The envelope effect now offers status functions to tell if it’s active, and whether its sustain period as ended.  When you use multiple envelopes to create (polyphonic) notes from oscillators or continuous other sound sources, these can help you better select which envelope is not currently “busy” to avoid truncating in-progress sounds.

The WAV file player and wav2sketch utility have been updated to handle unusual WAV files containing junk sections or other metadata before the format section.  Now you can use these WAV files without having to convert them.

A simple “amp” object has been added, meant for switch signals, or amplifying or attenuating.

While this functionality has long been available by using only 1 channel of a mixer, consistent feedback from users has shown that placing a mixer into a graphical design simply does not feel right.  Of course, the amp implements the cases of gain=0 and gain=1.0 by skipping all the math for efficient switching of signals.

Updates have also been made to audio library documentation in the design tool (right side panel).  As the audio library continue to grow, documenting its many features well is becoming ever more important.

Compile Speedup

1.42 has changes to speed up fully recompiling your project.  When Arduino prints “Build options changed, rebuilding all”, you’ll still have to wait, but hopefully not nearly as long.

The main improvement comes from removing “#include <algorithm> from wiring.h”.  Version 1.41 brought a greatly improved map() function which automatically detects if the variable you’re translating is an integer or floating point number.  This magic depends on C++14 features, so wiring.h had this and other includes added.

It turns out nearly all of the extra compile time is due to that one #include <algorithm> header.  It has been removed, and map() still works, still automatically detecting integer versus floating point.

1.42 also changes the build process to use a pre-compiled header for Arduino.h (which in turn includes wiring.h).  This offers some additional speed improvement, but only about a 20% reduction for most programs.

Teensy Loader Improvements

Teensy Loader has a little-known feature to show you detailed information.  Few people know of this because it’s hidden in a place nobody would look, the Help menu.

The Verbose Information window now shows events from the helper programs Teensyduino uses from Arduino, as well as the events from within Teensy Loader itself.

The events are now timestamped with millisecond resolution.  Normally this level of detailed logging isn’t needed, but when “strange” USB problems occur, a log of all the events from every software component can really help.

Teensy Loader has only a few dialog boxes.  The most important ones, alerting you to problems like the wrong board, have long been non-modal to prevent blocking event logging and responding to Arduino.  Help > About and File > Open are also non-modal, completely eliminating modal behavior.

Teensy Loader’s internal graphics handling and memory management were improved.

Miscellaneous Improvements and Fixes

USB Host support on Teensy 3.6 received small improvements.  KurtE updated the Joystick support.  A bug impacting certain hubs was also fixed.

The Serial boolean, used to check if the Arduino Serial Monitor is open, has been improved.

Teensy’s support for X-Plane flight simulator received a fix to FlightSimFloat on Teensy 3.5 and 3.6.  The Flightsim+Joystick USB type was also updated, fixing a problem where it would not be recognized by the TeensyControls X-plane plugin

A small speedup to analogWrite for DAC pins was made.

The startup delay in Teensyduino’s initialization code was reduced from 400 to 300 ms, and changes were made to begin USB enumeration sooner.  While instant startup might seem highly desirable, too-fast startup tends to cause compatibility issues with many Arduino libraries, which do not properly wait for external hardware – because all Arduino boards have slow startup.

A bug in DMAChannel.h transferSize() affecting Teensy LC was fixed.

USB Keyboard KEY_MEDIA_RANDOM_PLAY was fixed.

EthernetClient received a fix for forced connection close.

A subtle timing problem in OctoWS2811 affecting Teensy 3.5 was fixed.

When compiling on 32 bit Teensy boards, “narrowing conversion” is now treated as only a compiler warning, not an error, as has always been done on 8 bit boards.  This allows some poorly written libraries to “just work” even though their code is a bit sloppy.

Ethernet.init(cspin) is now documented in all the Ethernet examples, and on the Ethernet page.  This function is an Adafruit extension which PJRC adopted for Teensy’s version of the Ethernet library, but until now it wasn’t actually documented.

Libraries ADC, OneWire, PS2Keyboard, SerialFlash, Time, TimeAlarms (included in the Teensyduino installer) were updated.

The Macintosh version is now 64 bits software, as required by the newest High Sierra and future versions of MacOS.

Arduino Versions Supported

Support for Arduino 1.8.2 and 1.8.3 and 1.8.4 has been dropped.  The new ports menu and serial monitor are only implemented on Arduino 1.8.5.

Teensyduino is continuing to support 3 old versions of Arduino.  Arduino 1.8.1 was the last version before major changes in Arduino’s “arduino-builder” program.  Arduuino 1.6.5-r5 was the last version before “arduino-builder”, where the entire build process is controlled by the Java code in the Arduino IDE.  Arduino 1.0.6 was the last version of the very old 1.0 series.

Arduino appears to have entered a period of slower release.  Through 2016-2017, Arduino made 12 stable releases.  Since releasing 1.8.5 in September 2017, they started a 1.9 beta but haven’t made any non-beta releases.  If this trend continue, we may explore supporting specific 1.9 beta versions.

At the recent San Mateo Maker Faire, Massimo Banzi announced a developer summit.  PJRC will be participating.  My personal hope is we can move the entire Arduino ecosystem forward with contributions like EventResponder.  I plan to write more detailed articles about this effort as it develops.

Recently work was also done to support Linux 64 ARM (Aarch64), testing on nVidia Jetson TX2.  While Aarch64 support is still considered “experimental” and not part of the stable 1.42 release, if you’re interested in running on Linux 64 bit ARM, please see the last 1.42 beta for an Aarch64 build that’s essentially the same as this 1.42 release.

Non-Blocking WS2812 LED Library

Last weekend I wrote a new WS2812 LED library featuring non-blocking performance.

A common problem with WS2812 / NeoPixel LEDs is creating their control signal with precise timing conflicts with other timing-sensitive software.  Adafruit NeoPixel completely blocks all interrupts.  FastLED can be configured to allow other interrupts, but any other library using interrupts for more than several microseconds can disrupt the WS2812 signal.

OctoWS2811 has offered non-blocking performance on Teensy 3.x since early 2013.  But it consumes 8 pins and places restrictions on 1 or 2 others, which makes it difficult to use in many projects needing some of those pins.  OctoWS2811 is designed for large LED projects (500 to 6000 LEDs), which is “overkill” for many projects using only dozes or even a few hundred LEDs.

Especially for projects using NeoPixel products with the Teensy Audio Library, or trying to receiving incoming serial data (especially DMX lighting control), we have long needed a simple, single-pin, easy-to-use library that doesn’t interfere with interrupts.  For a long time I’ve meant to write this library, and this recent forum conversaton finally gave me the push to get it working to truly solve the NeoPixels+Audio isssue!

Inverted Serial Transmit

WS2812Serial uses one of the hardware serial ports to actually transmit the Ws2812 data.  This idea certainly isn’t new.  This message is the oldest reference I could find of the basic idea.

The serial port is configured to run at 4 Mbit/sec, which is exactly 5 times the 800 kbit/sec speed WS2812 LEDs expect.  Every 5 data bits becomes one cycle of the WS2812 signal.

Standard 8N1 format serial sends 1 start bit, 8 data bits in least-significant-bit-first order, and then 1 stop bit.  In this case, the signal is inverted from the usual TTL level output.  Teensy LC & 3.x have hardware built in to invert the signal.

Since the start bit is always high, to send a zero bit to WS2812 the first 4 data bits are configured low.  To send a one bit, the first 3 are configured high and the 4th low.  The other half of the byte becomes the next WS2812 bit.  Bit 4 must always be high, and bits 5 to 7 control the data seen by WS2812.  The stop bit is always low, which automatically completes the 2nd WS2812 data.

Originally I tried using only 3 bits per WS2812 time slot, with 2.4 Mbit/sec serial baud rate.  Many of the WS2812 datasheets say the timing allows up to 450 ns pulse width, so in theory this 417 ns pulse should work.  In practice it did work with some WS2812 LEDs, but not others.  In the end, I changed to 4 Mbit/sec which allows it to work with all WS2812 / NeoPixel LEDs.

Direct Memory Access (DMA)

To achieve non-blocking performance, and to run efficiently at 4 Mbit/sec baud rate, DMA is used to copy the data directly from memory to the serial port.

The result is a perfectly continuous WS2812 output which does not require any interrupts and leaves the processor free to run other libraries or your program to compute the next frame of LED data.

The need to compute all of the serial data before each update does lead to the one major drawback of this non-blocking approach: memory usage.  Normally with FastLED or Adafruit NeoPixel, only 3 bytes of memory are used per LED.  WS2812Serial requires 15 bytes, the normal 3 for drawing, and 12 for composing the serial data.

Fortunately the code is fairly simple.  Here is the entire show() function which updates the LEDs.  In the middle you can see “x = 0x08” which sets the begin bit for the 2nd half of each byte’s WS2812 output, and then the two logical OR operations which control the groups of 3 bits which are the shaded portion of the drawing above.

In this code sample you can also see my DMAChannel.h abstraction layer for DMA transfers.  It is my attempt to make DMA simple to use, like other Arduino libraries.  Obviously things are not quite there yet, especially for Teensy LC where you can see I had to resort to directly programming the DMA controller registers, rather than using the functions to configure the source, destination, transfer size and count.

At some point I intend to write a detailed article about how DMA works.  Mike from Hackaday has been asking me to do this for years!  If you’d also like to see it, remind me too….

One other possible idea for this library might involve using two DMA channels and their interrupts, to allow a smaller serial buffer.  The basic idea would involve rendering only part of the output, and configuring each DMA channel to send half.  Each each completes and generates an interrupt, another chunk of the output could be generated and the just-finished DMA channel could be quickly reconfigured to send the next chunk.  Ideally, this could allow a relatively small memory buffer.  It would require interrupts, but if they are delayed by other libraries or code, hopefully a user could make a trade-off between memory usage and allowable interrupt latency.

For now, WS2812Serial simply requires a big frame buffer and gives completely non-blocking performance.  No interrupts are ever used.  That does consume extra RAM, but the huge benefit is compatibility with other code or libraries require interrupts or CPU time while the LEDs update.

Starting New Blog

Years ago I used to add photos and links people emailed to this Teensy projects page.  I’ve also occasionally written blog articles on the DorkbotPDX site over the last 9 years.

Recently at Maker Faire I talked with Mike Szczys, about writing and sharing of knowledge in the Maker Community.  I’m determined to step up my writing game with this blog!  Robin & I also want to restart showcasing the many awesome projects people make with Teensy.