docs/LedStrip.md

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