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
  17 The function and orientation configuration is fixed for now but later it should be able to be set via the UI or CLI..
  18
  19 In the future, if someone codes it, they could be used to show GPS navigation status, thrust levels, RSSI, etc.
  20 Lots of scope for ideas and improvements.
  21
  22 Likewise, support for more than 32 LEDs is possible, it just requires additional development.
  23
  24 ## Supported hardware
  25
  26 Only strips of 32 WS2811/WS2812 LEDs are supported currently.  If the strip is longer than 32 LEDs it does not matter,
  27 but only the first 32 are used.
  28
  29 WS2812 LEDs require an 800khz signal and precise timings and thus requires the use of a dedicated hardware timer.
  30
  31 Note: Not all WS2812 ICs use the same timings, some batches use different timings.
  32
  33 It could be possible to be able to specify the timings required via CLI if users request it.
  34
  35 ### Tested Hardware
  36
  37 * [Adafruit NeoPixel Jewel 7](https://www.adafruit.com/products/2226) (preliminary testing)
  38   * Measured current consumption in all white mode ~ 350 mA.
  39   * Fits well under motors on mini 250 quads.
  40 * [Adafruit NeoPixel Stick](https://www.adafruit.com/products/1426) (works well)
  41   * Measured current consumption in all white mode ~ 350 mA.
  42
  43 ## Connections
  44
  45 WS2812 LED strips generally require a single data line, 5V and GND.
  46
  47 WS2812 LEDs on full brightness can consume quite a bit of current.  It is recommended to verify the current draw and ensure your
  48 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
  49 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
  50 from another BEC.  Just ensure that the GROUND is the same for all BEC outputs and LEDs.
  51
  52
  53 | Target                | Pin  | LED Strip | Signal |
  54 | --------------------- | ---- | --------- | -------|
  55 | Naze/Olimexino        | RC5  | Data In   | PA6    |
  56 | CC3D                  | RCO5 | Data In   | PB4    |
  57 | ChebuzzF3/F3Discovery | PB8  | Data In   | PB8    |
  58 | Sparky                | PWM5 | Data In   | PA6    |
  59
  60 Since RC5 is also used for SoftSerial on the Naze/Olimexino it means that you cannot use SoftSerial and led strips at the same time.
  61 Additionally, since RC5 is also used for Parallel PWM RC input on both the Naze, Chebuzz and STM32F3Discovery targets, led strips
  62 can not be used at the same time at Parallel PWM.
  63
  64 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
  65 diode on the VIN to the LED strip. The problem occurs because of the difference in voltage between the data signal and the power
  66 signal.  The WS2811 LED's require the data signal (Din) to be MAX 0.7 * VIN.  Data In on the LEDs will allways be around ~3.3v,
  67 so the Vin MAX should be 4.7v (3.3v / 0.7 = 4.71v).  Some LEDs are more tolerant of this than others.
  68
  69
  70 ## Configuration
  71
  72 Enable the `LED_STRIP` feature via the cli:
  73
  74 ```
  75 feature LED_STRIP
  76 ```
  77
  78 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.
  79
  80 Configure the LEDs using the `led` command.
  81
  82 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.
  83
  84 If used with zero arguments it prints out the led configuration which can be copied for future reference.
  85
  86 Each led is configured using the following template: `x,y:ddd:mmm:cc`
  87
  88 `x` and `y` are grid coordinates of a 0 based 16x16 grid, north west is 0,0, south east is 15,15
  89 `ddd` specifies the directions, since an led can face in any direction it can have multiple directions.  Directions are:
  90
  91  `N` - North
  92  `E` - East
  93  `S` - South
  94  `W` - West
  95  `U` - Up
  96  `D` - Down
  97
  98 For instance, an LED that faces South-east at a 45 degree downwards angle could be configured as `SED`.
  99
 100 Note: It is perfectly possible to configure an LED to have all directions `NESWUD` but probably doesn't make sense.
 101
 102 `mmm` specifies the modes that should be applied an LED.  Modes are:
 103
 104 * `W` - `W`warnings.
 105 * `F` - `F`light mode & Orientation
 106 * `I` - `I`ndicator.
 107 * `A` - `A`rmed state.
 108 * `T` - `T`hrust state.
 109 * `R` - `R`ing thrust state.
 110 * `C` - `C`olor.
 111
 112 `cc` specifies the color number (0 based index).
 113
 114 Example:
 115
 116 ```
 117 led 0 0,15:SD:IAW:0
 118 led 1 15,0:ND:IAW:0
 119 led 2 0,0:ND:IAW:0
 120 led 3 0,15:SD:IAW:0
 121 led 4 7,7::C:1
 122 led 5 8,8::C:2
 123 ```
 124
 125 To erase an led, and to mark the end of the chain, use `0,0::` as the second argument, like this:
 126
 127 ```
 128 led 4 0,0:::
 129 ```
 130
 131 It is best to erase all LEDs that you do not have connected.
 132
 133 ### Modes
 134
 135 #### Warning
 136
 137 This mode simply uses the LEDs to flash when warnings occur.
 138
 139 | Warning | LED Pattern | Notes |
 140 |---------|-------------|-------|
 141 | Arm-lock enabled | flash between green and off | occurs calibration or when unarmed and the aircraft is tilted too much |
 142 | Low Battery | flash red and off | battery monitoring must be enabled.  May trigger temporarily under high-throttle due to voltage drop |
 143 | Failsafe | flash between light blue and yellow | Failsafe must be enabled |
 144
 145 Flash patterns appear in order, so that it's clear which warnings are enabled.
 146
 147 #### Flight Mode & Orientation
 148
 149 This mode shows the flight mode and orientation.
 150
 151 When flight modes are active then the LEDs are updated to show different colors depending on the mode, placement on the grid and direction.
 152
 153 LEDs are set in a specific order:
 154  * LEDs that marked as facing up or down.
 155  * LEDs that marked as facing west or east AND are on the west or east side of the grid.
 156  * LEDs that marked as facing north or south AND are on the north or south side of the grid.
 157
 158 That is, south facing LEDs have priority.
 159
 160 The mapping between modes led placement and colors is currently fixed and cannot be changed.
 161
 162 #### Indicator
 163
 164 This mode flashes LEDs that correspond to roll and pitch stick positions.  i.e.  they indicate the direction the craft is going to turn.
 165
 166 | Mode | Direction | LED Color |
 167 |------------|--------|---------------------|
 168 |Orientation | North  | WHITE                   |
 169 |Orientation | East   | DARK VIOLET     |
 170 |Orientation | South  | RED                     |
 171 |Orientation | West   | DEEP PINK               |
 172 |Orientation | Up     | BLUE                    |
 173 |Orientation | Down   | ORANGE          |
 174 | | | |
 175 |Head Free   | North  | LIME GREEN      |
 176 |Head Free   | East   | DARK VIOLET     |
 177 |Head Free   | South  | ORANGE          |
 178 |Head Free   | West   | DEEP PINK       |
 179 |Head Free   | Up     | BLUE                    |
 180 |Head Free   | Down   | ORANGE          |
 181 | | | |
 182 |Horizon     | North  | BLUE                    |
 183 |Horizon     | East   | DARK VIOLET     |
 184 |Horizon     | South  | YELLOW          |
 185 |Horizon     | West   | DEEP PINK       |
 186 |Horizon     | Up     | BLUE                    |
 187 |Horizon     | Down   | ORANGE          |
 188 | | | |
 189 |Angle       | North  | CYAN                    |
 190 |Angle       | East   | DARK VIOLET     |
 191 |Angle       | South  | YELLOW          |
 192 |Angle       | West   | DEEP PINK       |
 193 |Angle       | Up     | BLUE                    |
 194 |Angle       | Down   | ORANGE          |
 195 | | | |
 196 |Mag         | North  | MINT GREEN      |
 197 |Mag         | East   | DARK VIOLET     |
 198 |Mag         | South  | ORANGE          |
 199 |Mag         | West   | DEEP PINK       |
 200 |Mag         | Up     | BLUE                    |
 201 |Mag         | Down   | ORANGE          |
 202 | | | |
 203 |Baro        | North  | LIGHT BLUE      |
 204 |Baro        | East   | DARK VIOLET     |
 205 |Baro        | South  | RED                     |
 206 |Baro        | West   | DEEP PINK       |
 207 |Baro        | Up     | BLUE                    |
 208 |Baro        | Down   | ORANGE          |
 209
 210 #### Armed state
 211
 212 This mode toggles LEDs between green and blue when disarmed and armed, respectively.
 213
 214 Note: Armed State cannot be used with Flight Mode.
 215
 216 #### Thrust state
 217
 218 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
 219 throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
 220 the same time.  Thrust should normally be combined with Color or Mode/Orientation.
 221
 222 #### Thrust ring state
 223
 224 This mode is allows you to use a 12, 16 or 24 leds ring (e.g. NeoPixel ring) for an afterburner effect. When armed the leds use the following sequences: 2 On, 4 Off, 2 On, 4 Off, and so on.  The light pattern rotates clockwise as throttle increases.
 225
 226 A better effect is acheived when LEDs configured for thrust ring have no other functions.
 227
 228 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.
 229
 230 Each LED of the ring can be a different color. The color can be selected between the 16 colors availables.
 231
 232 For example, led 0 is set as a `R`ing thrust state led in color 13 as follow.
 233
 234 ```
 235 led 0 2,2::R:13
 236 ```
 237
 238 LED strips and rings can be combined.
 239
 240 #### Solid Color
 241
 242 The mode allows you to set an LED to be permanently on and set to a specific color.
 243
 244 x,y position and directions are ignored when using this mode.
 245
 246 Other modes will override or combine with the color mode.
 247
 248 For example, to set led 0 to always use color 10 you would issue this command.
 249
 250 ```
 251 led 0 0,0::C:10
 252 ```
 253
 254 ### Colors
 255
 256 Colors can be configured using the cli `color` command.
 257
 258 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).
 259
 260 See http://en.wikipedia.org/wiki/HSL_and_HSV
 261
 262 If used with zero arguments it prints out the color configuration which can be copied for future reference.
 263
 264 The default color configuration is as follows:
 265
 266 | Index | Color       |
 267 | ----- | ----------- |
 268 |     0 | black       |
 269 |     1 | white       |
 270 |     2 | red         |
 271 |     3 | orange      |
 272 |     4 | yellow      |
 273 |     5 | lime green  |
 274 |     6 | green       |
 275 |     7 | mint green  |
 276 |     8 | cyan        |
 277 |     9 | light blue  |
 278 |    10 | blue        |
 279 |    11 | dark violet |
 280 |    12 | magenta     |
 281 |    13 | deep pink   |
 282 |    14 | black       |
 283 |    15 | black       |
 284
 285 ```
 286 color 0 0,0,0
 287 color 1 0,255,255
 288 color 2 0,0,255
 289 color 3 30,0,255
 290 color 4 60,0,255
 291 color 5 90,0,255
 292 color 6 120,0,255
 293 color 7 150,0,255
 294 color 8 180,0,255
 295 color 9 210,0,255
 296 color 10 240,0,255
 297 color 11 270,0,255
 298 color 12 300,0,255
 299 color 13 330,0,255
 300 color 14 0,0,0
 301 color 15 0,0,0
 302 ```
 303
 304 ## Positioning
 305
 306 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.
 307 e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
 308
 309 Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
 310
 311 ### Example 12 LED config
 312
 313 The default configuration is as follows
 314 ```
 315 led 0 15,15:ES:IA:0
 316 led 1 15,8:E:WF:0
 317 led 2 15,7:E:WF:0
 318 led 3 15,0:NE:IA:0
 319 led 4 8,0:N:F:0
 320 led 5 7,0:N:F:0
 321 led 6 0,0:NW:IA:0
 322 led 7 0,7:W:WF:0
 323 led 8 0,8:W:WF:0
 324 led 9 0,15:SW:IA:0
 325 led 10 7,15:S:WF:0
 326 led 11 8,15:S:WF:0
 327 led 12 7,7:U:WF:0
 328 led 13 8,7:U:WF:0
 329 led 14 7,8:D:WF:0
 330 led 15 8,8:D:WF:0
 331 led 16 8,9::R:3
 332 led 17 9,10::R:3
 333 led 18 10,11::R:3
 334 led 19 10,12::R:3
 335 led 20 9,13::R:3
 336 led 21 8,14::R:3
 337 led 22 7,14::R:3
 338 led 23 6,13::R:3
 339 led 24 5,12::R:3
 340 led 25 5,11::R:3
 341 led 26 6,10::R:3
 342 led 27 7,9::R:3
 343 led 28 0,0:::0
 344 led 29 0,0:::0
 345 led 30 0,0:::0
 346 led 31 0,0:::0
 347 ```
 348
 349 Which translates into the following positions:
 350
 351 ```
 352      6             3
 353       \           /
 354        \   5-4   /
 355         \ FRONT /
 356     7,8 | 12-15 | 1,2
 357         /  BACK \
 358        /  10,11  \
 359       /           \
 360      9             0
 361        RING 16-27
 362 ```
 363
 364 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 365 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 366 LEDs 12-13 should be placed facing down, in the middle
 367 LEDs 14-15 should be placed facing up, in the middle
 368 LEDs 16-17 should be placed in a ring and positioned at the rear facing south.
 369
 370 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.
 371
 372 ### Example 16 LED config
 373
 374 ```
 375 led 0 15,15:SD:IA:0
 376 led 1 8,8:E:FW:0
 377 led 2 8,7:E:FW:0
 378 led 3 15,0:ND:IA:0
 379 led 4 7,7:N:FW:0
 380 led 5 8,7:N:FW:0
 381 led 6 0,0:ND:IA:0
 382 led 7 7,7:W:FW:0
 383 led 8 7,8:W:FW:0
 384 led 9 0,15:SD:IA:0
 385 led 10 7,8:S:FW:0
 386 led 11 8,8:S:FW:0
 387 led 12 7,7:D:FW:0
 388 led 13 8,7:D:FW:0
 389 led 14 7,7:U:FW:0
 390 led 15 8,7:U:FW:0
 391 ```
 392
 393 Which translates into the following positions:
 394
 395 ```
 396      6             3
 397       \           /
 398        \   5-4   /
 399       7 \ FRONT / 2
 400         | 12-15 |
 401       8 /  BACK \ 1
 402        /  10-11  \
 403       /           \
 404      9             0
 405 ```
 406
 407 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 408 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 409 LEDs 12-13 should be placed facing down, in the middle
 410 LEDs 14-15 should be placed facing up, in the middle
 411
 412 ### Exmple 28 LED config
 413
 414 ```
 415 #right rear cluster
 416 led 0 9,9:S:FWT:0
 417 led 1 10,10:S:FWT:0
 418 led 2 11,11:S:IA:0
 419 led 3 11,11:E:IA:0
 420 led 4 10,10:E:AT:0
 421 led 5 9,9:E:AT:0
 422 # right front cluster
 423 led 6 10,5:S:F:0
 424 led 7 11,4:S:F:0
 425 led 8 12,3:S:IA:0
 426 led 9 12,2:N:IA:0
 427 led 10 11,1:N:F:0
 428 led 11 10,0:N:F:0
 429 # center front cluster
 430 led 12 7,0:N:FW:0
 431 led 13 6,0:N:FW:0
 432 led 14 5,0:N:FW:0
 433 led 15 4,0:N:FW:0
 434 # left front cluster
 435 led 16 2,0:N:F:0
 436 led 17 1,1:N:F:0
 437 led 18 0,2:N:IA:0
 438 led 19 0,3:W:IA:0
 439 led 20 1,4:S:F:0
 440 led 21 2,5:S:F:0
 441 # left rear cluster
 442 led 22 2,9:W:AT:0
 443 led 23 1,10:W:AT:0
 444 led 24 0,11:W:IA:0
 445 led 25 0,11:S:IA:0
 446 led 26 1,10:S:FWT:0
 447 led 27 2,9:S:FWT:0
 448 ```
 449
 450 ```
 451        16-18  9-11
 452 19-21 \           / 6-8
 453        \  12-15  /
 454         \ FRONT /
 455         /  BACK \
 456        /         \
 457 22-24 /           \ 3-5
 458        25-27   0-2
 459 ```
 460
 461 All LEDs should face outwards from the chassis in this configuration.
 462
 463 Note:
 464 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).
 465
 466
 467 ## Troubleshooting
 468
 469 On initial power up the LEDs on the strip will be set to WHITE.  This means you can attach a current meter to verify
 470 the current draw if your measurement equipment is fast enough.  Most 5050 LEDs will draw 0.3 Watts a piece.
 471 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.
 472
 473 After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
 474
 475 Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.