» 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

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


03.09.15 [15:32 UTC] by velcrome | 1885 downloads
Dynamic plugin, superfast
Show 3 older revisions

Older Revisions

19.02.14 [00:56 UTC] by velcrome | 853 downloads
Dynamic plugins to do the binary manipulation in high performance
OctoWSControl 1.1.zip
15.06.13 [19:31 UTC] by catweasel | 941 downloads
Added a swapdim to reorder the data so it goes allong the length not from pin to pin
14.06.13 [17:30 UTC] by catweasel | 680 downloads
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?

bo27 03/05/2017 - 16:44

last month we had some fun with teensy, octo and v4

catweasel 18/10/2017 - 15:01

I've found that by using a shared texture and then pipeting that in a 2nd instance of vvvv, you get much better performance, I use the dx11 one of course :)
While we are show and telling, http://www.colour-burst.com/2015/11/frequency-response-1/ this was 20 universe with 4 teensy, I've now started using a version of the BlackLED https://github.com/vertigo-dk/BlackLED but using FastLED instead of octows, and I can get 8 universes from one board. Not as many as the vertigo-dk guys :(

metrowave 18/10/2017 - 15:08

@bo27 @catweasel, Awesome! very clean colors and forms, fast refresh rate. Have you tried APA102 LEDs, they are faster and support octo/teensy boards.

Gareth.Griffiths 26/11/2017 - 00:36

Also wondering about APA102 LEDS.

velcrome 13/12/2017 - 15:12

Paul Stoffregen shared some insight into APA. Supposedly they work just as good, but the length is more restricted than with WS2811.

Also, I took the time to clean up my patches. Let me know what you think, and whether this should be uploaded as the official contrib. It is the fastest and cleanest (yet), but also the most involved (especially with soldering and stuff).
On the up-side it works over Ethernet, and from SD Card, and can be used for arbitrary 3d-LED-Mappings.

Download here

It works for 8x128 LED out of the box, with the wiz820io and the provided Ethernet drivers you can even quadruple that.

derber 01/03/2018 - 18:42

@velcrome please if possible re upload the patch the link no longer works.