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 #### Armed state
 167
 168 This mode toggles LEDs between green and blue when disarmed and armed, respectively.
 169
 170 Note: Armed State cannot be used with Flight Mode.
 171
 172 #### Thrust state
 173
 174 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
 175 throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
 176 the same time.  Thrust should normally be combined with Color or Mode/Orientation.
 177
 178 #### Thrust ring state
 179
 180 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.
 181
 182 A better effect is acheived when LEDs configured for thrust ring have no other functions.
 183
 184 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.
 185
 186 Each LED of the ring can be a different color. The color can be selected between the 16 colors availables.
 187
 188 For example, led 0 is set as a `R`ing thrust state led in color 13 as follow.
 189
 190 ```
 191 led 0 2,2::R:13
 192 ```
 193
 194 LED strips and rings can be combined.
 195
 196 #### Solid Color
 197
 198 The mode allows you to set an LED to be permanently on and set to a specific color.
 199
 200 x,y position and directions are ignored when using this mode.
 201
 202 Other modes will override or combine with the color mode.
 203
 204 For example, to set led 0 to always use color 10 you would issue this command.
 205
 206 ```
 207 led 0 0,0::C:10
 208 ```
 209
 210 ### Colors
 211
 212 Colors can be configured using the cli `color` command.
 213
 214 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).
 215
 216 See http://en.wikipedia.org/wiki/HSL_and_HSV
 217
 218 If used with zero arguments it prints out the color configuration which can be copied for future reference.
 219
 220 The default color configuration is as follows:
 221
 222 | Index | Color       |
 223 | ----- | ----------- |
 224 |     0 | black       |
 225 |     1 | white       |
 226 |     2 | red         |
 227 |     3 | orange      |
 228 |     4 | yellow      |
 229 |     5 | lime green  |
 230 |     6 | green       |
 231 |     7 | mint green  |
 232 |     8 | cyan        |
 233 |     9 | light blue  |
 234 |    10 | blue        |
 235 |    11 | dark violet |
 236 |    12 | magenta     |
 237 |    13 | deep pink   |
 238 |    14 | black       |
 239 |    15 | black       |
 240
 241 ```
 242 color 0 0,0,0
 243 color 1 0,255,255
 244 color 2 0,0,255
 245 color 3 30,0,255
 246 color 4 60,0,255
 247 color 5 90,0,255
 248 color 6 120,0,255
 249 color 7 150,0,255
 250 color 8 180,0,255
 251 color 9 210,0,255
 252 color 10 240,0,255
 253 color 11 270,0,255
 254 color 12 300,0,255
 255 color 13 330,0,255
 256 color 14 0,0,0
 257 color 15 0,0,0
 258 ```
 259
 260 ## Positioning
 261
 262 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.
 263 e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
 264
 265 Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
 266
 267 ### Example 12 LED config
 268
 269 The default configuration is as follows
 270 ```
 271 led 0 15,15:ES:IA:0
 272 led 1 15,8:E:WF:0
 273 led 2 15,7:E:WF:0
 274 led 3 15,0:NE:IA:0
 275 led 4 8,0:N:F:0
 276 led 5 7,0:N:F:0
 277 led 6 0,0:NW:IA:0
 278 led 7 0,7:W:WF:0
 279 led 8 0,8:W:WF:0
 280 led 9 0,15:SW:IA:0
 281 led 10 7,15:S:WF:0
 282 led 11 8,15:S:WF:0
 283 led 12 7,7:U:WF:0
 284 led 13 8,7:U:WF:0
 285 led 14 7,8:D:WF:0
 286 led 15 8,8:D:WF:0
 287 led 16 8,9::R:3
 288 led 17 9,10::R:3
 289 led 18 10,11::R:3
 290 led 19 10,12::R:3
 291 led 20 9,13::R:3
 292 led 21 8,14::R:3
 293 led 22 7,14::R:3
 294 led 23 6,13::R:3
 295 led 24 5,12::R:3
 296 led 25 5,11::R:3
 297 led 26 6,10::R:3
 298 led 27 7,9::R:3
 299 led 28 0,0:::0
 300 led 29 0,0:::0
 301 led 30 0,0:::0
 302 led 31 0,0:::0
 303 ```
 304
 305 Which translates into the following positions:
 306
 307 ```
 308      6             3
 309       \           /
 310        \   5-4   /
 311         \ FRONT /
 312     7,8 | 12-15 | 1,2
 313         /  BACK \
 314        /  10,11  \
 315       /           \
 316      9             0
 317        RING 16-27
 318 ```
 319
 320 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 321 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 322 LEDs 12-13 should be placed facing down, in the middle
 323 LEDs 14-15 should be placed facing up, in the middle
 324 LEDs 16-17 should be placed in a ring and positioned at the rear facing south.
 325
 326 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.
 327
 328 ### Example 16 LED config
 329
 330 ```
 331 led 0 15,15:SD:IA:0
 332 led 1 8,8:E:FW:0
 333 led 2 8,7:E:FW:0
 334 led 3 15,0:ND:IA:0
 335 led 4 7,7:N:FW:0
 336 led 5 8,7:N:FW:0
 337 led 6 0,0:ND:IA:0
 338 led 7 7,7:W:FW:0
 339 led 8 7,8:W:FW:0
 340 led 9 0,15:SD:IA:0
 341 led 10 7,8:S:FW:0
 342 led 11 8,8:S:FW:0
 343 led 12 7,7:D:FW:0
 344 led 13 8,7:D:FW:0
 345 led 14 7,7:U:FW:0
 346 led 15 8,7:U:FW:0
 347 ```
 348
 349 Which translates into the following positions:
 350
 351 ```
 352      6             3
 353       \           /
 354        \   5-4   /
 355       7 \ FRONT / 2
 356         | 12-15 |
 357       8 /  BACK \ 1
 358        /  10-11  \
 359       /           \
 360      9             0
 361 ```
 362
 363 LEDs 0,3,6 and 9 should be placed underneath the quad, facing downwards.
 364 LEDs 1-2, 4-5, 7-8 and 10-11 should be positioned so the face east/north/west/south, respectively.
 365 LEDs 12-13 should be placed facing down, in the middle
 366 LEDs 14-15 should be placed facing up, in the middle
 367
 368 ### Exmple 28 LED config
 369
 370 ```
 371 #right rear cluster
 372 led 0 9,9:S:FWT:0
 373 led 1 10,10:S:FWT:0
 374 led 2 11,11:S:IA:0
 375 led 3 11,11:E:IA:0
 376 led 4 10,10:E:AT:0
 377 led 5 9,9:E:AT:0
 378 # right front cluster
 379 led 6 10,5:S:F:0
 380 led 7 11,4:S:F:0
 381 led 8 12,3:S:IA:0
 382 led 9 12,2:N:IA:0
 383 led 10 11,1:N:F:0
 384 led 11 10,0:N:F:0
 385 # center front cluster
 386 led 12 7,0:N:FW:0
 387 led 13 6,0:N:FW:0
 388 led 14 5,0:N:FW:0
 389 led 15 4,0:N:FW:0
 390 # left front cluster
 391 led 16 2,0:N:F:0
 392 led 17 1,1:N:F:0
 393 led 18 0,2:N:IA:0
 394 led 19 0,3:W:IA:0
 395 led 20 1,4:S:F:0
 396 led 21 2,5:S:F:0
 397 # left rear cluster
 398 led 22 2,9:W:AT:0
 399 led 23 1,10:W:AT:0
 400 led 24 0,11:W:IA:0
 401 led 25 0,11:S:IA:0
 402 led 26 1,10:S:FWT:0
 403 led 27 2,9:S:FWT:0
 404 ```
 405
 406 ```
 407        16-18  9-11
 408 19-21 \           / 6-8
 409        \  12-15  /
 410         \ FRONT /
 411         /  BACK \
 412        /         \
 413 22-24 /           \ 3-5
 414        25-27   0-2
 415 ```
 416
 417 All LEDs should face outwards from the chassis in this configuration.
 418
 419 Note:
 420 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).
 421
 422
 423 ## Troubleshooting
 424
 425 On initial power up the LEDs on the strip will be set to WHITE.  This means you can attach a current meter to verify
 426 the current draw if your measurement equipment is fast enough.  Most 5050 LEDs will draw 0.3 Watts a piece.
 427 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.
 428
 429 After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
 430
 431 Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.