docs/LedStrip.md

   1 # LED Strip
   2
   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.
   6
   7 Addressable LED strips can be used to show information from the flight controller system, the current implementation
   8 supports the following:
   9
  10 * Up to 128 LEDs. _If using more than 20 LEDs, you should look to use a separate power supply._
  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.
  19
  20 Support for more than 128 LEDs is possible, it just requires additional development.
  21
  22 ## Supported hardware
  23
  24 Only strips of 128 WS2811/WS2812 LEDs are supported currently.  If the strip is longer than 128 LEDs it does not matter,
  25 but only the first 128 are used.
  26
  27 WS2812 LEDs require an 800khz signal and precise timings and thus requires the use of a dedicated hardware timer.
  28
  29 Note: Not all WS2812 ICs use the same timings, some batches use different timings.
  30
  31 It could be possible to be able to specify the timings required via CLI if users request it.
  32
  33 ### Tested Hardware
  34
  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.
  40
  41 ## Connections
  42
  43 WS2812 LED strips generally require a single data line, 5V and GND.
  44
  45 WS2812 LEDs on full brightness can consume quite a bit of current.  **It is recommended to verify the current draw of you LEDs and ensure your supply can cope with the load. Remember, your flight controller will likely be using the same BEC to operate.** Check the specs of the LED chips. Some are more power hungry than others. Remember that if using the flight controller's 5v supply. This is also powering other components on your flight controller. Make sure there is enough overhead so that they don't brownout.
  46
  47 On a multirotor that uses multiple BEC ESC's you can try use a different BEC to the one the FC 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 from another BEC. Just ensure that the GROUND is the same for all BEC outputs and LEDs.
  48
  49 If using a large number of LEDs. It would be more efficient to use 12v LEDs and power them with a separate regulated supply. Especially if using long strips. You would use the data line (LED pad) from the flight controller. Make sure there is continuity between the ground on the LEDS and the ground on the flight controller.
  50
  51 | Target                | Pin  | LED Strip | Signal |
  52 | --------------------- | ---- | --------- | -------|
  53 | F3Discovery | PB8  | Data In   | PB8    |
  54 | Sparky                | PWM5 | Data In   | PA6    |
  55
  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.
  61
  62 The datasheet can be found here: http://www.adafruit.com/datasheets/WS2812.pdf
  63
  64 ## Configuration
  65
  66 The led strip feature can be configured via the GUI.
  67
  68 GUI:
  69 Enable the Led Strip feature via the GUI under setup.
  70
  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.
  73
  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.
  75
  76 CLI:
  77 Enable the `LED_STRIP` feature via the cli:
  78
  79 ```
  80 feature LED_STRIP
  81 ```
  82
  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.
  84
  85 Configure the LEDs using the `led` command.
  86
  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.
  88
  89 If used with zero arguments it prints out the led configuration which can be copied for future reference.
  90
  91 Each led is configured using the following template: `x,y:ddd:mmm:cc`
  92
  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:
  95
  96  `N` - North
  97  `E` - East
  98  `S` - South
  99  `W` - West
 100  `U` - Up
 101  `D` - Down
 102
 103 For instance, an LED that faces South-east at a 45 degree downwards angle could be configured as `SED`.
 104
 105 Note: It is perfectly possible to configure an LED to have all directions `NESWUD` but probably doesn't make sense.
 106
 107 `mmm` specifies the modes that should be applied an LED.
 108
 109 Each LED has one base function:
 110
 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.
 119
 120 And each LED has overlays:
 121
 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%).
 128 * `E` - Strob`E` Blink white on top of selected color.
 129
 130 `cc` specifies the color number (0 based index), or Channel number to adjust Hue
 131
 132 Example:
 133
 134 ```
 135 led 0 0,15:SD:AWI:0
 136 led 1 15,0:ND:AWI:0
 137 led 2 0,0:ND:AWI:0
 138 led 3 0,15:SD:AWI:0
 139 led 4 7,7::C:1
 140 led 5 8,8::C:2
 141 led 6 8,9::B:1
 142 led 7 8,10::H:6
 143 ```
 144
 145 To erase an led, and to mark the end of the chain, use `0,0::` as the second argument, like this:
 146
 147 ```
 148 led 4 0,0:::
 149 ```
 150
 151 It is best to erase all LEDs that you do not have connected.
 152
 153 ### Modes
 154
 155 #### Warning
 156
 157 This mode simply uses the LEDs to flash when warnings occur.
 158
 159 | Warning | LED Pattern | Notes |
 160 |---------|-------------|-------|
 161 | Arm-lock enabled | flash between green and off | occurs calibration or when unarmed and the aircraft is tilted too much |
 162 | Low Battery | flash red and off | battery monitoring must be enabled.  May trigger temporarily under high-throttle due to voltage drop |
 163 | Hardware Error | flash blue and off | indicates that at least one of hardware components is not working correctly |
 164 | Failsafe | flash between light blue and yellow | Failsafe must be enabled |
 165
 166 Flash patterns appear in order, so that it's clear which warnings are enabled.
 167
 168 #### GPS state
 169
 170 This mode shows the GPS state and satellite count.
 171
 172 No fix = red LED
 173 3D fix = green LED
 174
 175 The LEDs will blink as many times as the satellite count, then pause and start again.
 176
 177 #### RSSI level
 178
 179 This mode binds the LED color to RSSI level.
 180
 181 | Color      |   RSSI   |
 182 | ---------- | ---------|
 183 | Green      |   100%   |
 184 | Lime green |    80%   |
 185 | Yellow     |    60%   |
 186 | Orange     |    40%   |
 187 | Red        |    20%   |
 188 | Deep pink  |     0%   |
 189
 190 When RSSI is below 50% is reached, LEDs will blink slowly, and they will blink fast when under 20%.
 191
 192
 193 #### Battery level
 194
 195 This mode binds the LED color to remaining battery capacity.
 196
 197 | Color      | Capacity |
 198 | ---------- | ---------|
 199 | Green      |   100%   |
 200 | Lime green |    80%   |
 201 | Yellow     |    60%   |
 202 | Orange     |    40%   |
 203 | Red        |    20%   |
 204 | Deep pink  |     0%   |
 205
 206 When Warning or Critial voltage is reached, LEDs will blink slowly or fast.
 207 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
 209 #### Blink
 210
 211 This mode blinks the current LED, alternatively from black to the current active color.
 212
 213 #### Blink on landing
 214
 215 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
 217 #### Larson Scanner (Cylon Effect)
 218
 219 The Larson Scanner replicates the scanning "eye" effect seen on the mechanical Cylons and on Kitt from Knight Rider.
 220
 221 This overlay merely varies the brightness of each LED's current color.
 222
 223 #### Flight Mode & Orientation
 224
 225 This mode shows the flight mode and orientation.
 226
 227 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
 229 LEDs are set in a specific order:
 230  * LEDs that marked as facing up or down.
 231  * LEDs that marked as facing west or east AND are on the west or east side of the grid.
 232  * LEDs that marked as facing north or south AND are on the north or south side of the grid.
 233
 234 That is, south facing LEDs have priority.
 235
 236 The mapping between modes led placement and colors is currently fixed and cannot be changed.
 237
 238 #### Indicator
 239
 240 ##### For fixed wing (INAV 6.1 onwards)
 241
 242 This mode flashes LEDs that correspond to the roll stick position. Rolling left will flash any `indicator` LED on the left half of the grid. Rolling right will flash any `indicator` on the right side of the grid.
 243
 244 ##### For other platforms (all platforms pre INAV 6.1)
 245
 246 This mode flashes LEDs that correspond to roll and pitch stick positions.  i.e.  they indicate the direction the craft is going to turn.
 247
 248 | Mode | Direction | LED Color |
 249 |------------|--------|---------------------|
 250 |Orientation | North  | WHITE                   |
 251 |Orientation | East   | DARK VIOLET     |
 252 |Orientation | South  | RED                     |
 253 |Orientation | West   | DEEP PINK               |
 254 |Orientation | Up     | BLUE                    |
 255 |Orientation | Down   | ORANGE          |
 256 | | | |
 257 |Head Free   | North  | LIME GREEN      |
 258 |Head Free   | East   | DARK VIOLET     |
 259 |Head Free   | South  | ORANGE          |
 260 |Head Free   | West   | DEEP PINK       |
 261 |Head Free   | Up     | BLUE                    |
 262 |Head Free   | Down   | ORANGE          |
 263 | | | |
 264 |Horizon     | North  | BLUE                    |
 265 |Horizon     | East   | DARK VIOLET     |
 266 |Horizon     | South  | YELLOW          |
 267 |Horizon     | West   | DEEP PINK       |
 268 |Horizon     | Up     | BLUE                    |
 269 |Horizon     | Down   | ORANGE          |
 270 | | | |
 271 |Angle       | North  | CYAN                    |
 272 |Angle       | East   | DARK VIOLET     |
 273 |Angle       | South  | YELLOW          |
 274 |Angle       | West   | DEEP PINK       |
 275 |Angle       | Up     | BLUE                    |
 276 |Angle       | Down   | ORANGE          |
 277 | | | |
 278 |Mag         | North  | MINT GREEN      |
 279 |Mag         | East   | DARK VIOLET     |
 280 |Mag         | South  | ORANGE          |
 281 |Mag         | West   | DEEP PINK       |
 282 |Mag         | Up     | BLUE                    |
 283 |Mag         | Down   | ORANGE          |
 284 | | | |
 285 |Baro        | North  | LIGHT BLUE      |
 286 |Baro        | East   | DARK VIOLET     |
 287 |Baro        | South  | RED                     |
 288 |Baro        | West   | DEEP PINK       |
 289 |Baro        | Up     | BLUE                    |
 290 |Baro        | Down   | ORANGE          |
 291
 292 #### Armed state
 293
 294 This mode toggles LEDs between green and blue when disarmed and armed, respectively.
 295
 296 Note: Armed State cannot be used with Flight Mode.
 297
 298 #### Thrust state
 299
 300 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
 301 throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
 302 the same time.  Thrust should normally be combined with Color or Mode/Orientation.
 303
 304 #### Thrust ring state
 305
 306 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.
 307
 308 A better effect is acheived when LEDs configured for thrust ring have no other functions.
 309
 310 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.
 311
 312 Each LED of the ring can be a different color. The color can be selected between the 16 colors availables.
 313
 314 For example, led 0 is set as a `R`ing thrust state led in color 13 as follow.
 315
 316 ```
 317 led 0 2,2::R:13
 318 ```
 319
 320 LED strips and rings can be combined.
 321
 322 #### Solid Color
 323
 324 The mode allows you to set an LED to be permanently on and set to a specific color.
 325
 326 x,y position and directions are ignored when using this mode.
 327
 328 Other modes will override or combine with the color mode.
 329
 330 For example, to set led 0 to always use color 10 you would issue this command.
 331
 332 ```
 333 led 0 0,0::C:10
 334 ```
 335
 336 ### Colors
 337
 338 Colors can be configured using the cli `color` command.
 339
 340 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).
 341
 342 See http://en.wikipedia.org/wiki/HSL_and_HSV
 343
 344 If used with zero arguments it prints out the color configuration which can be copied for future reference.
 345
 346 The default color configuration is as follows:
 347
 348 | Index | Color       |
 349 | ----- | ----------- |
 350 |     0 | black       |
 351 |     1 | white       |
 352 |     2 | red         |
 353 |     3 | orange      |
 354 |     4 | yellow      |
 355 |     5 | lime green  |
 356 |     6 | green       |
 357 |     7 | mint green  |
 358 |     8 | cyan        |
 359 |     9 | light blue  |
 360 |    10 | blue        |
 361 |    11 | dark violet |
 362 |    12 | magenta     |
 363 |    13 | deep pink   |
 364 |    14 | black       |
 365 |    15 | black       |
 366
 367 ```
 368 color 0 0,0,0
 369 color 1 0,255,255
 370 color 2 0,0,255
 371 color 3 30,0,255
 372 color 4 60,0,255
 373 color 5 90,0,255
 374 color 6 120,0,255
 375 color 7 150,0,255
 376 color 8 180,0,255
 377 color 9 210,0,255
 378 color 10 240,0,255
 379 color 11 270,0,255
 380 color 12 300,0,255
 381 color 13 330,0,255
 382 color 14 0,0,0
 383 color 15 0,0,0
 384 ```
 385
 386 ### Mode Colors Assignement
 387
 388 Mode Colors can be configured using the cli `mode_color` command.
 389
 390 - No arguments: lists all mode colors
 391 - arguments: mode, function, color
 392
 393 First 6 groups of ModeIndexes are :
 394
 395 | mode | name        |
 396 |------|-------------|
 397 | 0    | orientation |
 398 | 1    | headfree    |
 399 | 2    | horizon     |
 400 | 3    | angle       |
 401 | 4    | mag         |
 402 | 5    | baro        |
 403 | 6    | special     |
 404
 405 Modes 0 to 5 functions:
 406
 407 | function | name  |
 408 |----------|-------|
 409 | 0        | north |
 410 | 1        | east  |
 411 | 2        | south |
 412 | 3        | west  |
 413 | 4        | up    |
 414 | 5        | down  |
 415
 416 Mode 6 use these functions:
 417
 418 | function | name               |
 419 |----------|--------------------|
 420 | 0        | disarmed           |
 421 | 1        | armed              |
 422 | 2        | animation          |
 423 | 3        | background         |
 424 | 4        | blink background   |
 425 | 5        | gps: no satellites |
 426 | 6        | gps: no fix        |
 427 | 7        | gps: 3D fix        |
 428
 429 The ColorIndex is picked from the colors array ("palette").
 430
 431 Examples (using the default colors):
 432
 433 - set armed color to red: ```mode_color 6 1 2```
 434 - set disarmed color to yellow: ```mode_color 6 0 4```
 435 - set Headfree mode 'south' to Cyan: ```mode_color 1 2 8```
 436
 437 ## Positioning
 438
 439 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.
 440 e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
 441
 442 Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
 443
 444 ### Example 12 LED config
 445
 446 The default configuration is as follows
 447 ```
 448 led 0 15,15:ES:IA:0
 449 led 1 15,8:E:WF:0
 450 led 2 15,7:E:WF:0
 451 led 3 15,0:NE:IA:0
 452 led 4 8,0:N:F:0
 453 led 5 7,0:N:F:0
 454 led 6 0,0:NW:IA:0
 455 led 7 0,7:W:WF:0
 456 led 8 0,8:W:WF:0
 457 led 9 0,15:SW:IA:0
 458 led 10 7,15:S:WF:0
 459 led 11 8,15:S:WF:0
 460 led 12 7,7:U:WF:0
 461 led 13 8,7:U:WF:0
 462 led 14 7,8:D:WF:0
 463 led 15 8,8:D:WF:0
 464 led 16 8,9::R:3
 465 led 17 9,10::R:3
 466 led 18 10,11::R:3
 467 led 19 10,12::R:3
 468 led 20 9,13::R:3
 469 led 21 8,14::R:3
 470 led 22 7,14::R:3
 471 led 23 6,13::R:3
 472 led 24 5,12::R:3
 473 led 25 5,11::R:3
 474 led 26 6,10::R:3
 475 led 27 7,9::R:3
 476 led 28 0,0:::0
 477 led 29 0,0:::0
 478 led 30 0,0:::0
 479 led 31 0,0:::0
 480 ```
 481
 482 Which translates into the following positions:
 483
 484 ```
 485      6             3
 486       \           /
 487        \   5-4   /
 488         \ FRONT /
 489     7,8 | 12-15 | 1,2
 490         /  BACK \
 491        /  10,11  \
 492       /           \
 493      9             0
 494        RING 16-27
 495 ```
 496
 497 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 498 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 499 LEDs 12-13 should be placed facing down, in the middle
 500 LEDs 14-15 should be placed facing up, in the middle
 501 LEDs 16-17 should be placed in a ring and positioned at the rear facing south.
 502
 503 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.
 504
 505 ### Example 16 LED config
 506
 507 ```
 508 led 0 15,15:SD:IA:0
 509 led 1 8,8:E:FW:0
 510 led 2 8,7:E:FW:0
 511 led 3 15,0:ND:IA:0
 512 led 4 7,7:N:FW:0
 513 led 5 8,7:N:FW:0
 514 led 6 0,0:ND:IA:0
 515 led 7 7,7:W:FW:0
 516 led 8 7,8:W:FW:0
 517 led 9 0,15:SD:IA:0
 518 led 10 7,8:S:FW:0
 519 led 11 8,8:S:FW:0
 520 led 12 7,7:D:FW:0
 521 led 13 8,7:D:FW:0
 522 led 14 7,7:U:FW:0
 523 led 15 8,7:U:FW:0
 524 ```
 525
 526 Which translates into the following positions:
 527
 528 ```
 529      6             3
 530       \           /
 531        \   5-4   /
 532       7 \ FRONT / 2
 533         | 12-15 |
 534       8 /  BACK \ 1
 535        /  10-11  \
 536       /           \
 537      9             0
 538 ```
 539
 540 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 541 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 542 LEDs 12-13 should be placed facing down, in the middle
 543 LEDs 14-15 should be placed facing up, in the middle
 544
 545 ### Exmple 28 LED config
 546
 547 ```
 548 # right rear cluster
 549 led 0 9,9:S:FWT:0
 550 led 1 10,10:S:FWT:0
 551 led 2 11,11:S:IA:0
 552 led 3 11,11:E:IA:0
 553 led 4 10,10:E:AT:0
 554 led 5 9,9:E:AT:0
 555 # right front cluster
 556 led 6 10,5:S:F:0
 557 led 7 11,4:S:F:0
 558 led 8 12,3:S:IA:0
 559 led 9 12,2:N:IA:0
 560 led 10 11,1:N:F:0
 561 led 11 10,0:N:F:0
 562 # center front cluster
 563 led 12 7,0:N:FW:0
 564 led 13 6,0:N:FW:0
 565 led 14 5,0:N:FW:0
 566 led 15 4,0:N:FW:0
 567 # left front cluster
 568 led 16 2,0:N:F:0
 569 led 17 1,1:N:F:0
 570 led 18 0,2:N:IA:0
 571 led 19 0,3:W:IA:0
 572 led 20 1,4:S:F:0
 573 led 21 2,5:S:F:0
 574 # left rear cluster
 575 led 22 2,9:W:AT:0
 576 led 23 1,10:W:AT:0
 577 led 24 0,11:W:IA:0
 578 led 25 0,11:S:IA:0
 579 led 26 1,10:S:FWT:0
 580 led 27 2,9:S:FWT:0
 581 ```
 582
 583 ```
 584        16-18  9-11
 585 19-21 \           / 6-8
 586        \  12-15  /
 587         \ FRONT /
 588         /  BACK \
 589        /         \
 590 22-24 /           \ 3-5
 591        25-27   0-2
 592 ```
 593
 594 All LEDs should face outwards from the chassis in this configuration.
 595
 596 Note:
 597 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).
 598
 599
 600 ## Troubleshooting
 601
 602 On initial power up the LEDs on the strip will be set to WHITE.  This means you can attach a current meter to verify
 603 the current draw if your measurement equipment is fast enough.  Most 5050 LEDs will draw 0.3 Watts a piece.
 604 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.
 605
 606 After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
 607
 608 Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.