Merge branch 'iNavFlight:master' into bf_osd_compat
[inav.git] / docs / LedStrip.md
blobb61c2ce5537338302fab8a32d11794b3e7e18d52
1 # LED Strip
3 INAV supports the use of addressable LED strips.  Addressable LED strips allow each LED in the strip to
4 be programmed with a unique and independant color.  This is far more advanced than the normal RGB strips which
5 require that all the LEDs in the strip show the same color.
7 Addressable LED strips can be used to show information from the flight controller system, the current implementation
8 supports the following:
10 * Up to 32 LEDs.
11 * Indicators showing pitch/roll stick positions.
12 * Heading/Orientation lights.
13 * Flight mode specific color schemes.
14 * Low battery warning.
15 * AUX operated on/off switch.
16 * GPS state.
17 * RSSI level.
18 * Battery level.
20 Support for more than 32 LEDs is possible, it just requires additional development.
22 ## Supported hardware
24 Only strips of 32 WS2811/WS2812 LEDs are supported currently.  If the strip is longer than 32 LEDs it does not matter,
25 but only the first 32 are used.
27 WS2812 LEDs require an 800khz signal and precise timings and thus requires the use of a dedicated hardware timer.
29 Note: Not all WS2812 ICs use the same timings, some batches use different timings.
31 It could be possible to be able to specify the timings required via CLI if users request it.
33 ### Tested Hardware
35 * [Adafruit NeoPixel Jewel 7](https://www.adafruit.com/products/2226) (preliminary testing)
36   * Measured current consumption in all white mode ~ 350 mA.
37   * Fits well under motors on mini 250 quads.
38 * [Adafruit NeoPixel Stick](https://www.adafruit.com/products/1426) (works well)
39   * Measured current consumption in all white mode ~ 350 mA.
41 ## Connections
43 WS2812 LED strips generally require a single data line, 5V and GND.
45 WS2812 LEDs on full brightness can consume quite a bit of current.  It is recommended to verify the current draw and ensure your
46 supply can cope with the load.  On a multirotor that uses multiple BEC ESC's you can try use a different BEC to the one the FC
47 uses.  e.g. ESC1/BEC1 -> FC, ESC2/BEC2 -> LED strip.   It's also possible to power one half of the strip from one BEC and the other half
48 from another BEC.  Just ensure that the GROUND is the same for all BEC outputs and LEDs.
51 | Target                | Pin  | LED Strip | Signal |
52 | --------------------- | ---- | --------- | -------|
53 | F3Discovery | PB8  | Data In   | PB8    |
54 | Sparky                | PWM5 | Data In   | PA6    |
56 If you have LEDs that are intermittent, flicker or show the wrong colors then drop the VIN to less than 4.7v, e.g. by using an inline
57 diode on the VIN to the LED strip. The problem occurs because of the difference in voltage between the data signal and the power
58 signal.  The WS2811 LED's require the data signal (Din) to be between 0.3 * Vin (Max) and 0.7 * VIN (Min) to register valid logic
59 low/high signals.  The LED pin on the CPU will always be between 0v to ~3.3v, so the Vin should be 4.7v (3.3v / 0.7 = 4.71v).
60 Some LEDs are more tolerant of this than others.
62 The datasheet can be found here: http://www.adafruit.com/datasheets/WS2812.pdf
64 ## Configuration
66 The led strip feature can be configured via the GUI.
68 GUI:
69 Enable the Led Strip feature via the GUI under setup.
71 Configure the leds from the Led Strip tab in the INAV GUI.
72 First setup how the led's are laid out so that you can visualize it later as you configure and so the flight controller knows how many led's there are available.
74 There is a step by step guide on how to use the GUI to configure the Led Strip feature using the GUI http://blog.oscarliang.net/setup-rgb-led-cleanflight/ which was published early 2015 by Oscar Liang which may or may not be up-to-date by the time you read this.
76 CLI:
77 Enable the `LED_STRIP` feature via the cli:
79 ```
80 feature LED_STRIP
81 ```
83 If you enable LED_STRIP feature and the feature is turned off again after a reboot then check your config does not conflict with other features, as above.
85 Configure the LEDs using the `led` command.
87 The `led` command takes either zero or two arguments - an zero-based led number and a sequence which indicates pair of coordinates, direction flags and mode flags and a color.
89 If used with zero arguments it prints out the led configuration which can be copied for future reference.
91 Each led is configured using the following template: `x,y:ddd:mmm:cc`
93 `x` and `y` are grid coordinates of a 0 based 16x16 grid, north west is 0,0, south east is 15,15
94 `ddd` specifies the directions, since an led can face in any direction it can have multiple directions.  Directions are:
96  `N` - North
97  `E` - East
98  `S` - South
99  `W` - West
100  `U` - Up
101  `D` - Down
103 For instance, an LED that faces South-east at a 45 degree downwards angle could be configured as `SED`.
105 Note: It is perfectly possible to configure an LED to have all directions `NESWUD` but probably doesn't make sense.
107 `mmm` specifies the modes that should be applied an LED.
109 Each LED has one base function:
111 * `C` - `C`olor.
112 * `F` - `F`light mode & Orientation
113 * `A` - `A`rmed state.
114 * `R` - `R`ing thrust state.
115 * `G` - `G`PS state.
116 * `S` - R`S`SSI level.
117 * `L` - Battery `L`evel.
118 * `H` - C`H`annel.
120 And each LED has overlays:
122 * `W` - `W`warnings.
123 * `I` - `I`ndicator.
124 * `T` - `T`hrust state.
125 * `B` - `B`link (flash twice) mode.
126 * `O` - Lars`O`n Scanner (Cylon Effect).
127 * `N` - Blink on la`N`ding (throttle < 50%).
129 `cc` specifies the color number (0 based index), or Channel number to adjust Hue
131 Example:
134 led 0 0,15:SD:AWI:0
135 led 1 15,0:ND:AWI:0
136 led 2 0,0:ND:AWI:0
137 led 3 0,15:SD:AWI:0
138 led 4 7,7::C:1
139 led 5 8,8::C:2
140 led 6 8,9::B:1
141 led 7 8,10::H:6
144 To erase an led, and to mark the end of the chain, use `0,0::` as the second argument, like this:
147 led 4 0,0:::
150 It is best to erase all LEDs that you do not have connected.
152 ### Modes
154 #### Warning
156 This mode simply uses the LEDs to flash when warnings occur.
158 | Warning | LED Pattern | Notes |
159 |---------|-------------|-------|
160 | Arm-lock enabled | flash between green and off | occurs calibration or when unarmed and the aircraft is tilted too much |
161 | Low Battery | flash red and off | battery monitoring must be enabled.  May trigger temporarily under high-throttle due to voltage drop |
162 | Hardware Error | flash blue and off | indicates that at least one of hardware components is not working correctly |
163 | Failsafe | flash between light blue and yellow | Failsafe must be enabled |
165 Flash patterns appear in order, so that it's clear which warnings are enabled.
167 #### GPS state
169 This mode shows the GPS state and satellite count.
171 No fix = red LED
172 3D fix = green LED
174 The LEDs will blink as many times as the satellite count, then pause and start again.
176 #### RSSI level
178 This mode binds the LED color to RSSI level.
180 | Color      |   RSSI   |
181 | ---------- | ---------|
182 | Green      |   100%   |
183 | Lime green |    80%   |
184 | Yellow     |    60%   |
185 | Orange     |    40%   |
186 | Red        |    20%   |
187 | Deep pink  |     0%   |
189 When RSSI is below 50% is reached, LEDs will blink slowly, and they will blink fast when under 20%.
192 #### Battery level
194 This mode binds the LED color to remaining battery capacity.
196 | Color      | Capacity |
197 | ---------- | ---------|
198 | Green      |   100%   |
199 | Lime green |    80%   |
200 | Yellow     |    60%   |
201 | Orange     |    40%   |
202 | Red        |    20%   |
203 | Deep pink  |     0%   |
205 When Warning or Critial voltage is reached, LEDs will blink slowly or fast.
206 Note: this mode requires a current sensor. If you don't have the actual device you can set up a virtual current sensor (see [Battery](Battery.md)).
208 #### Blink
210 This mode blinks the current LED, alternatively from black to the current active color.
212 #### Blink on landing
214 This mode blinks the current LED, alternatively from black to the current active color, when throttle is below 50% and the craft is armed.
216 #### Larson Scanner (Cylon Effect)
218 The Larson Scanner replicates the scanning "eye" effect seen on the mechanical Cylons and on Kitt from Knight Rider.
220 This overlay merely varies the brightness of each LED's current color.
222 #### Flight Mode & Orientation
224 This mode shows the flight mode and orientation.
226 When flight modes are active then the LEDs are updated to show different colors depending on the mode, placement on the grid and direction.
228 LEDs are set in a specific order:
229  * LEDs that marked as facing up or down.
230  * LEDs that marked as facing west or east AND are on the west or east side of the grid.
231  * LEDs that marked as facing north or south AND are on the north or south side of the grid.
233 That is, south facing LEDs have priority.
235 The mapping between modes led placement and colors is currently fixed and cannot be changed.
237 #### Indicator
239 This mode flashes LEDs that correspond to roll and pitch stick positions.  i.e.  they indicate the direction the craft is going to turn.
241 | Mode | Direction | LED Color |
242 |------------|--------|---------------------|
243 |Orientation | North  | WHITE                   |
244 |Orientation | East   | DARK VIOLET     |
245 |Orientation | South  | RED                     |
246 |Orientation | West   | DEEP PINK               |
247 |Orientation | Up     | BLUE                    |
248 |Orientation | Down   | ORANGE          |
249 | | | |
250 |Head Free   | North  | LIME GREEN      |
251 |Head Free   | East   | DARK VIOLET     |
252 |Head Free   | South  | ORANGE          |
253 |Head Free   | West   | DEEP PINK       |
254 |Head Free   | Up     | BLUE                    |
255 |Head Free   | Down   | ORANGE          |
256 | | | |
257 |Horizon     | North  | BLUE                    |
258 |Horizon     | East   | DARK VIOLET     |
259 |Horizon     | South  | YELLOW          |
260 |Horizon     | West   | DEEP PINK       |
261 |Horizon     | Up     | BLUE                    |
262 |Horizon     | Down   | ORANGE          |
263 | | | |
264 |Angle       | North  | CYAN                    |
265 |Angle       | East   | DARK VIOLET     |
266 |Angle       | South  | YELLOW          |
267 |Angle       | West   | DEEP PINK       |
268 |Angle       | Up     | BLUE                    |
269 |Angle       | Down   | ORANGE          |
270 | | | |
271 |Mag         | North  | MINT GREEN      |
272 |Mag         | East   | DARK VIOLET     |
273 |Mag         | South  | ORANGE          |
274 |Mag         | West   | DEEP PINK       |
275 |Mag         | Up     | BLUE                    |
276 |Mag         | Down   | ORANGE          |
277 | | | |
278 |Baro        | North  | LIGHT BLUE      |
279 |Baro        | East   | DARK VIOLET     |
280 |Baro        | South  | RED                     |
281 |Baro        | West   | DEEP PINK       |
282 |Baro        | Up     | BLUE                    |
283 |Baro        | Down   | ORANGE          |
285 #### Armed state
287 This mode toggles LEDs between green and blue when disarmed and armed, respectively.
289 Note: Armed State cannot be used with Flight Mode.
291 #### Thrust state
293 This mode fades the LED current LED color to the previous/next color in the HSB color space depending on throttle stick position.  When the
294 throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
295 the same time.  Thrust should normally be combined with Color or Mode/Orientation.
297 #### Thrust ring state
299 This mode is allows you to use one or multiple led rings (e.g. NeoPixel ring) for an afterburner effect.  The light pattern rotates clockwise as throttle increases.
301 A better effect is acheived when LEDs configured for thrust ring have no other functions.
303 LED direction and X/Y positions are irrelevant for thrust ring LED state.  The order of the LEDs that have the state determines how the LED behaves.
305 Each LED of the ring can be a different color. The color can be selected between the 16 colors availables.
307 For example, led 0 is set as a `R`ing thrust state led in color 13 as follow.
310 led 0 2,2::R:13
313 LED strips and rings can be combined.
315 #### Solid Color
317 The mode allows you to set an LED to be permanently on and set to a specific color.
319 x,y position and directions are ignored when using this mode.
321 Other modes will override or combine with the color mode.
323 For example, to set led 0 to always use color 10 you would issue this command.
326 led 0 0,0::C:10
329 ### Colors
331 Colors can be configured using the cli `color` command.
333 The `color` command takes either zero or two arguments - an zero-based color number and a sequence which indicates pair of hue, saturation and value (HSV).
335 See http://en.wikipedia.org/wiki/HSL_and_HSV
337 If used with zero arguments it prints out the color configuration which can be copied for future reference.
339 The default color configuration is as follows:
341 | Index | Color       |
342 | ----- | ----------- |
343 |     0 | black       |
344 |     1 | white       |
345 |     2 | red         |
346 |     3 | orange      |
347 |     4 | yellow      |
348 |     5 | lime green  |
349 |     6 | green       |
350 |     7 | mint green  |
351 |     8 | cyan        |
352 |     9 | light blue  |
353 |    10 | blue        |
354 |    11 | dark violet |
355 |    12 | magenta     |
356 |    13 | deep pink   |
357 |    14 | black       |
358 |    15 | black       |
361 color 0 0,0,0
362 color 1 0,255,255
363 color 2 0,0,255
364 color 3 30,0,255
365 color 4 60,0,255
366 color 5 90,0,255
367 color 6 120,0,255
368 color 7 150,0,255
369 color 8 180,0,255
370 color 9 210,0,255
371 color 10 240,0,255
372 color 11 270,0,255
373 color 12 300,0,255
374 color 13 330,0,255
375 color 14 0,0,0
376 color 15 0,0,0
379 ### Mode Colors Assignement
381 Mode Colors can be configured using the cli `mode_color` command.
383 - No arguments: lists all mode colors
384 - arguments: mode, function, color
386 First 6 groups of ModeIndexes are :
388 | mode | name        |
389 |------|-------------|
390 | 0    | orientation |
391 | 1    | headfree    |
392 | 2    | horizon     |
393 | 3    | angle       |
394 | 4    | mag         |
395 | 5    | baro        |
396 | 6    | special     |
398 Modes 0 to 5 functions:
400 | function | name  |
401 |----------|-------|
402 | 0        | north |
403 | 1        | east  |
404 | 2        | south |
405 | 3        | west  |
406 | 4        | up    |
407 | 5        | down  |
409 Mode 6 use these functions:
411 | function | name               |
412 |----------|--------------------|
413 | 0        | disarmed           |
414 | 1        | armed              |
415 | 2        | animation          |
416 | 3        | background         |
417 | 4        | blink background   |
418 | 5        | gps: no satellites |
419 | 6        | gps: no fix        |
420 | 7        | gps: 3D fix        |
422 The ColorIndex is picked from the colors array ("palette").
424 Examples (using the default colors):
426 - set armed color to red: ```mode_color 6 1 2```
427 - set disarmed color to yellow: ```mode_color 6 0 4```
428 - set Headfree mode 'south' to Cyan: ```mode_color 1 2 8```
430 ## Positioning
432 Cut the strip into sections as per diagrams below.  When the strips are cut ensure you reconnect each output to each input with cable where the break is made.
433 e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
435 Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
437 ### Example 12 LED config
439 The default configuration is as follows
441 led 0 15,15:ES:IA:0
442 led 1 15,8:E:WF:0
443 led 2 15,7:E:WF:0
444 led 3 15,0:NE:IA:0
445 led 4 8,0:N:F:0
446 led 5 7,0:N:F:0
447 led 6 0,0:NW:IA:0
448 led 7 0,7:W:WF:0
449 led 8 0,8:W:WF:0
450 led 9 0,15:SW:IA:0
451 led 10 7,15:S:WF:0
452 led 11 8,15:S:WF:0
453 led 12 7,7:U:WF:0
454 led 13 8,7:U:WF:0
455 led 14 7,8:D:WF:0
456 led 15 8,8:D:WF:0
457 led 16 8,9::R:3
458 led 17 9,10::R:3
459 led 18 10,11::R:3
460 led 19 10,12::R:3
461 led 20 9,13::R:3
462 led 21 8,14::R:3
463 led 22 7,14::R:3
464 led 23 6,13::R:3
465 led 24 5,12::R:3
466 led 25 5,11::R:3
467 led 26 6,10::R:3
468 led 27 7,9::R:3
469 led 28 0,0:::0
470 led 29 0,0:::0
471 led 30 0,0:::0
472 led 31 0,0:::0
475 Which translates into the following positions:
478      6             3
479       \           /
480        \   5-4   /
481         \ FRONT /
482     7,8 | 12-15 | 1,2
483         /  BACK \
484        /  10,11  \
485       /           \
486      9             0
487        RING 16-27
490 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
491 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
492 LEDs 12-13 should be placed facing down, in the middle
493 LEDs 14-15 should be placed facing up, in the middle
494 LEDs 16-17 should be placed in a ring and positioned at the rear facing south.
496 This is the default so that if you don't want to place LEDs top and bottom in the middle just connect the first 12 LEDs.
498 ### Example 16 LED config
501 led 0 15,15:SD:IA:0
502 led 1 8,8:E:FW:0
503 led 2 8,7:E:FW:0
504 led 3 15,0:ND:IA:0
505 led 4 7,7:N:FW:0
506 led 5 8,7:N:FW:0
507 led 6 0,0:ND:IA:0
508 led 7 7,7:W:FW:0
509 led 8 7,8:W:FW:0
510 led 9 0,15:SD:IA:0
511 led 10 7,8:S:FW:0
512 led 11 8,8:S:FW:0
513 led 12 7,7:D:FW:0
514 led 13 8,7:D:FW:0
515 led 14 7,7:U:FW:0
516 led 15 8,7:U:FW:0
519 Which translates into the following positions:
522      6             3
523       \           /
524        \   5-4   /
525       7 \ FRONT / 2
526         | 12-15 |
527       8 /  BACK \ 1
528        /  10-11  \
529       /           \
530      9             0
533 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
534 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
535 LEDs 12-13 should be placed facing down, in the middle
536 LEDs 14-15 should be placed facing up, in the middle
538 ### Exmple 28 LED config
541 # right rear cluster
542 led 0 9,9:S:FWT:0
543 led 1 10,10:S:FWT:0
544 led 2 11,11:S:IA:0
545 led 3 11,11:E:IA:0
546 led 4 10,10:E:AT:0
547 led 5 9,9:E:AT:0
548 # right front cluster
549 led 6 10,5:S:F:0
550 led 7 11,4:S:F:0
551 led 8 12,3:S:IA:0
552 led 9 12,2:N:IA:0
553 led 10 11,1:N:F:0
554 led 11 10,0:N:F:0
555 # center front cluster
556 led 12 7,0:N:FW:0
557 led 13 6,0:N:FW:0
558 led 14 5,0:N:FW:0
559 led 15 4,0:N:FW:0
560 # left front cluster
561 led 16 2,0:N:F:0
562 led 17 1,1:N:F:0
563 led 18 0,2:N:IA:0
564 led 19 0,3:W:IA:0
565 led 20 1,4:S:F:0
566 led 21 2,5:S:F:0
567 # left rear cluster
568 led 22 2,9:W:AT:0
569 led 23 1,10:W:AT:0
570 led 24 0,11:W:IA:0
571 led 25 0,11:S:IA:0
572 led 26 1,10:S:FWT:0
573 led 27 2,9:S:FWT:0
577        16-18  9-11
578 19-21 \           / 6-8
579        \  12-15  /
580         \ FRONT /
581         /  BACK \
582        /         \
583 22-24 /           \ 3-5
584        25-27   0-2
587 All LEDs should face outwards from the chassis in this configuration.
589 Note:
590 This configuration is specifically designed for the [Alien Spider AQ50D PRO 250mm frame](http://www.goodluckbuy.com/alien-spider-aq50d-pro-250mm-mini-quadcopter-carbon-fiber-micro-multicopter-frame.html).
593 ## Troubleshooting
595 On initial power up the LEDs on the strip will be set to WHITE.  This means you can attach a current meter to verify
596 the current draw if your measurement equipment is fast enough.  Most 5050 LEDs will draw 0.3 Watts a piece.
597 This also means that you can make sure that each R,G and B LED in each LED module on the strip is also functioning.
599 After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
601 Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.