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