» Realtime LED control with Teensy3.x/OctoWs2811
This site relies heavily on Javascript. You should enable it if you want the full experience. Learn more.

Realtime LED control with Teensy3.x/OctoWs2811

plugin arduino dma led neopixel rs232 serial teensy ws2811 ws2812b
Credits: Paul Stoffregen, catweasel, velcrome


Build your own low cost global DIY video walls, or just control a number of mapped, ultra-bright LED strips along an arbitrary structure!

The OctoWS2811 library is for the Teensy3.x board and can drive 1k of 24bit color LED's at high video frame rates easily.

This contribution allows you to feed your own simple 300W LED real time installation. You'll need the following ingredients (links show the parts we worked with, there might be other, better and worse):

1 running German vvvv
4 China Rolls of 4m LED (each ~€50, check your local suppliers and alibaba, try asking for custom build like waterproof IP67, special lengths or prefab connectors)
1 USA Teensy (€20) with a MicroUSB Cable (>€3)
1 Octows2811 Adapter (€6)
2 halves of a CAT6 cable (€0 if you salvage the healthy ends of a broken cable)
1 5 VCD power supply, slightly overpowered (100€)

Just add solder, connectors, some surface and some strong cables.

Scale as you may, at least eight teensies with 1k RGB-LED each can been controlled even with basic serial interfacing over a solid USB3 hub and the help patch (that'd be >=48 dmx universes). Development towards ethernet control is under way, which promises even better better scalability. Support is welcome!

This European contribution is rollware: if you buy or sell WS2811 rolls (aka WS2812b) while utilizing this code or parts of it, please snailmail additional roll(s) for the authors: one meter for every eight is cool. If you roll your own code with it, leave credit to the authors. Original patch was by catweasel, c# plugins are from velcrome

Flattr also welcome.


WS2811.7z - 03.09.15 [15:32 UTC] by velcrome | 585 downloads
notes: Dynamic plugin, superfast

other/older revisions

OctoWS2811.7z - 19.02.14 [00:56 UTC] by velcrome | 540 downloads
notes: Dynamic plugins to do the binary manipulation in high performance
OctoWSControl 1.1.zip - 15.06.13 [19:31 UTC] by catweasel | 640 downloads
notes: Added a swapdim to reorder the data so it goes allong the length not from pin to pin
OctoWSControl.zip - 14.06.13 [17:30 UTC] by catweasel | 385 downloads
notes: Sends serial data to a Teensy3 running the ws2811 Library

alg 14/06/2013 - 19:29

Thx, very cool board, need to check it.

velcrome 22/08/2013 - 02:21

thanks catweasel. your little project has been an amazing inspiration

i took a bit of your experience and put all the bitshifting in raw plugins. working with byte is just so much faster than converting it to double back and forth.

have a look here: download

also it spreads easily over multiple teensy. bottleneck is the RS232 node now because it blocks the mainloop.



maybe this is the way to go

catweasel 23/08/2013 - 15:19

Hi Velcrome, I did think about plugins for it, but had a load of things all to do concurrently last month, so never did!
https://github.com/scanlime/fadecandy this has also been released which is another project based on the OCto library, it uses less leds per output but gives better color and fades, I havent tried it much yet. I've been trying to get it to compile on my rPi to no avail, 1 Pi could control multiple teenys so could work out cheaper than lots of ethernet ports, I did try a bit of udp into teensy, but the buffers get overloaded, I think the udp library is a little iffy from what I could google (arduino's)
I'll check out your plugins though, cool stuff :D


heres some pictures of my LED's at a tiny festival my friend runs...
Hung off nails *blush* it is no budget ;)

beyon 24/08/2013 - 13:37

Cool, just looked at these libraries (octo and fadecandy) yesterday and have a led display I want to do at some point, using teensy 3s for other stuff atm...

velcrome 28/08/2013 - 17:22

hi catweasel,

the home of pancosmic pyromanticism? haha, that sounds fun.
our work was shown at gamescom in cologne as part of the xbox presence. it totalled about 5k of leds and 8 teensies.

on a side note:
anyone attempting a project like that, make sure you are aware of the electrical demands of an installation like that. if your wires are too flimsy for the massive currents that can build up, you loose too much voltage to maintain stable pwm.
ground ripple proved to be a problem too till we rewired almost everything.

the teensy part is quite straight forward, though, thanks to the incredible work of Paul Stoffregen

Alec 10/02/2014 - 21:59

I want to control different led matrices with the same patch. How can I send different pipet data to different Teensy boards?


velcrome 17/02/2014 - 05:27

you can pipet colors and cons them as much as you want, as long as you make sure you fill each individual teensy board to a color slice count of 1024.

if you channel the filled color spread into my module, the precalced data will come out of it spreaded. use that as input of the RS232 and spread the COM-Port input as well.

Alec 17/02/2014 - 15:19

@velcrome: I'm looking at your module. Can I spread also LED Strip Lenght with different values to control different matrices? Tomorrow I will test your module with my 28x16 led matrix and then I will report here.

Another question: what is SlaveMode?

Thanks for the help!

velcrome 17/02/2014 - 18:36

if a teensy operates on slave mode, it needs a connected master teensy on pin 12. only then it will push the pwm data, otherwise it will keep the last frame. this is to ensure framesync if you use multiple teensy in one big matrix.

as for the strip length: try it, i dont know if it works. probably not. i always filled it up, just to be sure.

Alec 18/02/2014 - 12:32

Hey velcrome,
I tested your module with my 28x16 led matrix (56 leds x 8 Teensy pins) but only first 8 strips (4 Teensy pins) work. The other leds are off.

Working leds also flashing.

Catweasel module works fine with the same setup. Any suggestion?

Please look at the simple attached patch.

velcrome 18/02/2014 - 16:51

i added a new version. please download and test and let us know if it works.

Alec 24/02/2014 - 12:59

@velcrome: sorry for the delay. Today I tested your new version. For me nothing is changed from the previous module version. I have the same feedback. Half matrix working and blinking leds. I saw also that TeensyCount is not connected so the module is no longer spreadable for control multiple Teensy.

velcrome 24/02/2014 - 21:04

Did you change the LED count in the firmware too?

TeensyCount is not needed anymore because it is implied in the color slicecount. But you have to make sure LedCount per pin in the patch and the firmware match.

Alec 25/02/2014 - 11:28

Yes, I did. :( I'm working with a 28x16 led matrix attached to Teensy with 56 leds per 8 strips with led layout 1. Parameters in the firmware are:

LED_WIDTH      28   

As code says "ledsPerStrip = LED_WIDTH * LED_HEIGHT / 8;"

As your OctoWS2811 (RS232) help patch I send to the module a spread of 448 colors, LED StripLenght set to 56 and PinCount to 8.

Where am I wrong?

P.S. Would be great if we could spread StripLenght with different values to control different Matrix setups on different Teensy (always with PinCount set to 8 as OctoWS2811 conventions). I don't know if it is possible.

velcrome 03/09/2015 - 15:31

hey friends, hey @Alec

I finally found the time to fix the issues that were related to strip lengths other than 128. As a side product, it is all a single plugin now with a noticable performance gain.

Please note, that I still don't see a need to follow Paul Stoffregens example to split strips into substrips that somehow have to follow an arbitrary interleaving system. Instead, just freely patch the spread of Pipet coordinates according to your physical layout.

This allows for arbitrary coordinate based color picking from a EX9 or DX11 renderer.
In my experience the Sync at pin12 ("SlaveMode") is not needed as long as your framerate is high enough.

Set the Strip Length both in the VideoDisplay.ino file and the patch to the maximum physical strip length (if you have some 56er, some 108 and a single 128 -> pick 128) and the rows to 8 (always). This might sound wasteful, but at least it is safe, because any superfluous data through the teensy will be ignored by the strips themselves.
Make sure to fill up sufficient color slices in the input spread.

Pro Tip: You can use the accompanied Splitter (Raw) to package smartly for other protocols (like artnet's 510byte), or even cut out parts that you are sure you don't want to send (this and a + (Raw Advanced) would be a performant way to handle custom situations similar to the one from @alec).

metrowave 08/09/2015 - 23:46

@velcrome, @catweasel thanks for this guys!

derber 25/03/2016 - 20:57

Hey Velcrome, hey Catweasel.
There was a further development of FastLED library and now it can be used in conjunction with Octows2811 for apparently faster communication:https://github.com/FastLED/FastLED/wiki/Parallel-Output#making-octows2811-faster-with-fastled
The library includes an example code that makes use of it.
Apart from it I also found another arduino sketch that is used to communicate with TouchDesigner.
Unfortunately I could not figure out what is needed to be changed in your plugin/patch in order to make it work.
Maybe you can have a quick look into it?
I am not sure if this is worthwhile but any performance gain is a good thing.
This is the link to the sketch I found. https://www.dropbox.com/s/badm3dl4hg2ethn/ledPixelController_400.ino?dl=0
Thanks for the help!

catweasel 27/03/2016 - 20:21

Looks good, I've mostly been using art net to control them recently, I'll try and check it out soon, thanks for the heads up!

derber 04/04/2016 - 19:08

Hey Catweasel how many leds could you drive via art-net? Do you use more than one universe? If so what node do you use? Could you elaborate your setup please?

catweasel 05/04/2016 - 18:34


Heres a sketch for 4 outputs via art net using fastLED, I've recently got 7 working with octoWS via art net, using the example in the teensy WS examples.
I'll try and work out if I can get more universe from fastLED soon hopefully.
I use the DMX(artnet) node and set the IP to the controller you want to control (this means changing it per teensy if your using multiples) you need 1 per universe.
1 Universe will control 170pixels

velcrome 20/06/2016 - 22:14

I decided against Artnet and made my own UPD based packet system. Each packet prepends a byte indicating the position of the "stripes' chunk" and a flag, if it should refresh all LED or not. The chunk design is prepared in a way, so OctoWS2811 can use a single fast memcopy, instead of going through SetRGB for each led (much more like catweasels first contrib on this page).

Each chunk describes 8 stripes by 32 LED, and we commonly use 8 chunks for a total of 2048 LED per teensy. Eight teensies can be driven at 60Hz now.

Oh, the things we do for Fusion...

brax401gbz 21/06/2016 - 23:54

Hey velcrome,

very interesting, i just found this whole thing today, very cool, i was building dmx-ws2811 converters and found myself being out of universes quit quickly...

maybe we can meet up a fusion and have a chat :D

isdzaurov 20/04/2017 - 19:11

Hello friends!
I would like to manage 7,200 diodes.
For this I need 8 teenagers and OctoWS?
Will the computer and vvvv cope with this?

velcrome 20/04/2017 - 20:52

are you coming to node? you know, for a friendly show me yours, I show you mine?

there are a couple potential bottlenecks

1. the pipet to select colors from a given texture (this is useful because you can define a unique coordinate for each led, and select the color from a texture)
2. the octows algorithm to prepare the data chunks (this is highly efficient by now, all bitshifting is done in a single plugin)
3. the transfer to the teensy (by rs232 this will be a major bottleneck, by udp not so much)

without much optimisations, I'd say that 4 teensys with 1k LED is the sane limit. if you find a fast usb3 hub, maybe even 8, but framerate will be no more than around 25fps
with optimisations, the only bottleneck that really matters is the pipet, driving a couple teensies with 4k LED each at 60Hz is entirely possible. at fusion we had half a dozen of them.

isdzaurov 20/04/2017 - 21:06

Thnak you velcrome
I think 25fps is not bad for simple task?

anonymous user login


~13h ago

drehwurm: Nevermind... my fault.. had an old DX11 pack installed

~13h ago

drehwurm: Nevermind... my fault.. had an old DX11 pack installed

~13h ago

drehwurm: PointEditor (DX11 2d) help needs a checkup. Replace Renderstate with Rasterizer?

~1d ago

joreg: @mediadog: indeed, fixed that!

~1d ago

mediadog: @microdee @joreg Aha! I had glanced at that list, but assignment was lurking beyond the scrollbar. Athankew!

~1d ago

joreg: first-come-first-serve tickets are now sold out except the "delegate" ones. others are still available from here: https://nodeforum.org/journal/node17-tickets/

~1d ago

~1d ago

microdee: @mediadog: default is set via assignment (equal sign)

~2d ago

mediadog: No default for effect parameters, just min and max?

~2d ago

microdee: regular *fcfs tickets for #node17 are already sold out, and non lowered regular ticket isn't available straight from main page