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
  16 The function and orientation configuration is fixed for now but later it should be able to be set via the UI or CLI..
  17
  18 In the future, if someone codes it, they could be used to show GPS navigation status, thrust levels, RSSI, etc.
  19 Lots of scope for ideas and improvements.
  20
  21 Likewise, support for more than 32 LEDs is possible, it just requires additional development.
  22
  23 ## Supported hardware
  24
  25 Only strips of 32 WS2812 LEDs are supported currently.  If the strip is longer than 32 LEDs it does not matter,
  26 but only the first 32 are used.
  27
  28 WS2812 LEDs require an 800khz signal and precise timings and thus requires the use of a dedicated hardware timer.
  29
  30 Note: The initial code may work with WS2801 + External LEDs since the protocol is the same, WS2811/WS2812B should also work but
  31 may require very simple timing adjustments to be made in the source.
  32 Not all WS2812 ICs use the same timings, some batches use different timings.
  33
  34 It could be possible to be able to specify the timings required via CLI if users request it.
  35
  36 ### Tested Hardware
  37
  38 * [Adafruit NeoPixel Jewel 7](https://www.adafruit.com/products/2226) (preliminary testing)
  39   * Measured current consumption in all white mode ~ 350 mA.
  40   * Fits well under motors on mini 250 quads.
  41 * [Adafruit NeoPixel Stick](https://www.adafruit.com/products/1426) (works well)
  42   * Measured current consumption in all white mode ~ 350 mA.
  43
  44 ## Connections
  45
  46 WS2812 LED strips generally require a single data line, 5V and GND.
  47
  48 WS2812 LEDs on full brightness can consume quite a bit of current.  It is recommended to verify the current draw and ensure your
  49 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
  50 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
  51 from another BEC.  Just ensure that the GROUND is the same for all BEC outputs and LEDs.
  52
  53
  54 | Target                | Pin  | LED Strip | Signal |
  55 | --------------------- | ---- | --------- | -------|
  56 | Naze/Olimexino        | RC5  | Data In   | PA6    |
  57 | CC3D                  | RCO5 | Data In   | PB4    |
  58 | ChebuzzF3/F3Discovery | PB8  | Data In   | PB8    |
  59 | Sparky                | PWM5 | Data In   | PA6    |
  60
  61 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.
  62 Additionally, since RC5 is also used for Parallel PWM RC input on both the Naze, Chebuzz and STM32F3Discovery targets, led strips
  63 can not be used at the same time at Parallel PWM.
  64
  65 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
  66 problem occurs because of the difference in voltage between the data signal and the power signal.
  67
  68 If you are using an BEC from an ESC to for the 5v supply check the output is as close to 5v as possible.
  69
  70 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
  71 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.
  72
  73
  74 ## Configuration
  75
  76 Enable the `LED_STRIP` feature via the cli:
  77
  78 ```
  79 feature LED_STRIP
  80 ```
  81
  82 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.
  83
  84 Configure the LEDs using the `led` command.
  85
  86 The `led` command takes either zero or two arguments - an zero-based led number and a pair of coordinates, direction flags and mode flags.
  87
  88 If used with zero arguments it prints out the led configuration which can be copied for future reference.
  89
  90 Each led is configured using the following template: `x,y:ddd:mmm`
  91
  92 `x` and `y` are grid coordinates of a 0 based 16x16 grid, north west is 0,0, south east is 15,15
  93 `ddd` specifies the directions, since an led can face in any direction it can have multiple directions.  Directions are:
  94
  95  `N` - North
  96  `E` - East
  97  `S` - South
  98  `W` - West
  99  `U` - Up
 100  `D` - Down
 101
 102 For instance, an LED that faces South-east at a 45 degree downwards angle could be configured as `SED`.
 103
 104 Note: It is perfectly possible to configure an LED to have all directions `NESWUD` but probably doesn't make sense.
 105
 106 `mmm` specifies the modes that should be applied an LED.  Modes are:
 107
 108 * `W` - `W`warnings.
 109 * `F` - `F`light mode & Orientation
 110 * `I` - `I`ndicator.
 111 * `A` - `A`rmed state.
 112 * `T` - `T`hrust state.
 113
 114 Example:
 115
 116 ```
 117 led 0 0,15:SD:IAW
 118 led 1 15,0:ND:IAW
 119 led 2 0,0:ND:IAW
 120 led 3 0,15:SD:IAW
 121 ```
 122
 123 to erase an led, and to mark the end of the chain, use `0,0::` as the second argument, like this:
 124
 125 ```
 126 led 4 0,0::
 127 ```
 128
 129
 130 ### Modes
 131
 132 #### Warning
 133
 134 This mode simply uses the LEDs to flash when warnings occur.
 135
 136 | Warning | LED Pattern | Notes |
 137 |---------|-------------|-------|
 138 | Arm-lock enabled | flash between green and off | occurs calibration or when unarmed and the aircraft is tilted too much |
 139 | Low Battery | flash red and off | battery monitoring must be enabled.  May trigger temporarily under high-throttle due to voltage drop |
 140 | Failsafe | flash between light blue and yellow | Failsafe must be enabled |
 141
 142 Flash patterns appear in order, so that it's clear which warnings are enabled.
 143
 144 #### Flight Mode & Orientation
 145
 146 This mode shows the flight mode and orientation.
 147
 148 When flight modes are active then the LEDs are updated to show different colors depending on the mode, placement on the grid and direction.
 149
 150 LEDs are set in a specific order:
 151  * LEDs that marked as facing up or down.
 152  * LEDs that marked as facing west or east AND are on the west or east side of the grid.
 153  * LEDs that marked as facing north or south AND are on the north or south side of the grid.
 154
 155 That is, south facing LEDs have priority.
 156
 157 #### Indicator
 158
 159 This mode flashes LEDs that correspond to roll and pitch stick positions.  i.e.  they indicate the direction the craft is going to turn.
 160
 161 #### Armed state
 162
 163 This mode toggles LEDs between green and blue when disarmed and armed, respectively.
 164
 165 Note: Armed State cannot be used with Flight Mode.
 166
 167 #### Thrust state
 168
 169 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
 170 throttle is in the middle position the color is unaffected, thus it can be mixed with orientation colors to indicate orientation and throttle at
 171 the same time.
 172
 173 ## Positioning
 174
 175 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.
 176 e.g. connect 5V out to 5V in, GND to GND and Data Out to Data In.
 177
 178 Orientation is when viewed with the front of the aircraft facing away from you and viewed from above.
 179
 180 ### Example 12 LED config
 181
 182 The default configuration is as follows
 183 ```
 184 led 0 2,2:ES:IA
 185 led 1 2,1:E:WF
 186 led 2 2,0:NE:IA
 187 led 3 1,0:N:F
 188 led 4 0,0:NW:IA
 189 led 5 0,1:W:WF
 190 led 6 0,2:SW:IA
 191 led 7 1,2:S:WF
 192 led 8 1,1:U:WF
 193 led 9 1,1:U:WF
 194 led 10 1,1:D:WF
 195 led 11 1,1:D:WF
 196 ```
 197
 198 Which translates into the following positions:
 199
 200 ```
 201      5             3
 202       \           /
 203        \    4    /
 204         \ FRONT /
 205       6 | 9-12  | 2
 206         /  BACK \
 207        /    8    \
 208       /           \
 209      7             1
 210 ```
 211
 212 LEDs 1,3,5 and 7 should be placed underneath the quad, facing downwards.
 213 LEDs 2, 4, 6 and 8 should be positioned so the face east/north/west/south, respectively.
 214 LEDs 9-10 should be placed facing down, in the middle
 215 LEDs 11-12 should be placed facing up, in the middle
 216
 217 This is the default so that if you don't want to place LEDs top and bottom in the middle just connect the first 8 LEDs.
 218
 219 ### Example 16 LED config
 220
 221 ```
 222 led 0 15,15:SD:IA
 223 led 1 8,8:E:FW
 224 led 2 8,7:E:FW
 225 led 3 15,0:ND:IA
 226 led 4 7,7:N:FW
 227 led 5 8,7:N:FW
 228 led 6 0,0:ND:IA
 229 led 7 7,7:W:FW
 230 led 8 7,8:W:FW
 231 led 9 0,15:SD:IA
 232 led 10 7,8:S:FW
 233 led 11 8,8:S:FW
 234 led 12 7,7:D:FW
 235 led 13 8,7:D:FW
 236 led 14 7,7:U:FW
 237 led 15 8,7:U:FW
 238 ```
 239
 240 Which translates into the following positions:
 241
 242 ```
 243      7             4
 244       \           /
 245        \   6-5   /
 246       8 \ FRONT / 3
 247         | 13-16 |
 248       9 /  BACK \ 2
 249        /  11-12  \
 250       /           \
 251     10             1
 252 ```
 253
 254 LEDs 1,4,7 and 10 should be placed underneath the quad, facing downwards.
 255 LEDs 2-3, 6-5, 8-9 and 11-12 should be positioned so the face east/north/west/south, respectively.
 256 LEDs 13-14 should be placed facing down, in the middle
 257 LEDs 15-16 should be placed facing up, in the middle
 258
 259 ### Exmple 28 LED config
 260
 261 ```
 262 #right rear cluster
 263 led 0 9,9:S:FWT
 264 led 1 10,10:S:FWT
 265 led 2 11,11:S:IA
 266 led 3 11,11:E:IA
 267 led 4 10,10:E:AT
 268 led 5 9,9:E:AT
 269 # right front cluster
 270 led 6 10,5:S:F
 271 led 7 11,4:S:F
 272 led 8 12,3:S:IA
 273 led 9 12,2:N:IA
 274 led 10 11,1:N:F
 275 led 11 10,0:N:F
 276 # center front cluster
 277 led 12 7,0:N:FW
 278 led 13 6,0:N:FW
 279 led 14 5,0:N:FW
 280 led 15 4,0:N:FW
 281 # left front cluster
 282 led 16 2,0:N:F
 283 led 17 1,1:N:F
 284 led 18 0,2:N:IA
 285 led 19 0,3:W:IA
 286 led 20 1,4:S:F
 287 led 21 2,5:S:F
 288 # left rear cluster
 289 led 22 2,9:W:AT
 290 led 23 1,10:W:AT
 291 led 24 0,11:W:IA
 292 led 25 0,11:S:IA
 293 led 26 1,10:S:FWT
 294 led 27 2,9:S:FWT
 295 ```
 296
 297 ```
 298        17-19  10-12
 299 20-22 \           / 7-9
 300        \  13-16  /
 301         \ FRONT /
 302         /  BACK \
 303        /         \
 304 23-25 /           \ 4-6
 305        26-28   1-3
 306 ```
 307
 308 All LEDs should face outwards from the chassis in this configuration.
 309
 310 Note:
 311 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).
 312
 313
 314 ## Troubleshooting
 315
 316 On initial power up the LEDs on the strip will be set to WHITE.  This means you can attach a current meter to verify
 317 the current draw if your measurement equipment is fast enough.  Most 5050 LEDs will draw 0.3 Watts a piece.
 318 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.
 319
 320 After a short delay the LEDs will show the unarmed color sequence and or low-battery warning sequence.
 321
 322 If the LEDs flash intermittently or do not show the correct colors verify all connections and check the specifications of the
 323 LEDs you have against the supported timings (for now, you'll have to look in the source).
 324
 325 Also check that the feature `LED_STRIP` was correctly enabled and that it does not conflict with other features, as above.