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