# ws2812b_async

Library to support a chain of ws2812b chips via USART Asynchronous interface

Author | Rob Hamerling, Copyright © 2014..2014, all rights reserved.
Adapted-by |
Compiler | 2.4q2

Description

    Library to control a chain of WS2812Bs
    This library uses the USART module with Asynchronous protocol.
    - A PIC with Fosc of at least 32 MHz is required.
    - A high speed USART is required (BRG16 bit in BAUDCON)
    - The first or only USART interface is used and initialized automatically.
    - The USART must be able to invert the polarity of the USART output
      (have a CKTXP or TXCKP bit in BAUDCON, like with many 18Fs,
       or the SCKP bit in BAUDCON like the midrnage and other 18Fs).
      Alternatively an external signal inverter is required.
    - The DIN wire of the WS2812B chain must be connected to pin_TX of the PIC
      and this pin must be configured for digital I/O.
      Notes: - The pin_TX/CK may have to be configured with Peripheral Pin Select (PPS)
               or Alternate Pin Function (APFCON_TXCKSEL).
             - pin_RX is not used.
    - Initialize the interface with procedure ws2812b_async_init().
    - The number of WS2812Bs in the chain must be specified, e.g.:
         const byte WS2812B_NUM = 30       -- for 30 chained WS2812Bs
    - The user program should contain 3 byte arrays of WS2812B_NUM bytes each, e.g.:
         var byte agreen[WS2812B_NUM]
         var byte ared[WS2812B_NUM]
         var byte ablue[WS2812B_NUM]
      and call the procedure ws2812b_refresh() to pass the current color settings
      to the WS2812B LEDs.
    - Procedure ws2812b_all_color() can be used to set all LEDs to the same color
      while keeping the color settings in the arrays unchanged.

Notes

    - Warnings temporary(?) commented out.

Dependencies

- ws2812b_common

## Summary

### Global variables/contants

### Procedures

- `ws2812b_async_init()`

Private

- `_ws2812b_write_pixel(byte in green, byte in red, byte in blue)`
- `_transfer_byte(byte in data)`

### Functions

## API details

### Global variables/contants

### Procedures

- `ws2812b_async_init()`

      Title:   Initialize the USART for Asynchronous transmit at the required speed
      Input:   (none)

Private

- `_ws2812b_write_pixel(byte in green, byte in red, byte in blue)`

      Title:  Transfer 3 color bytes to the WS2812B
      Input:  Three color values (bytes: green, red, blue)
      Notes:  - Each WS2812B bit is transferred as 3 USART data bits:
      a '0' as 0b100, a '1' as 0b110.
       The USART transfers least significant data bits first.
       The startbit (=1) and stopbit (=0) are part of the USART signal.
       1st WS2812B 'bit': startbit + bit0 + bit1
       2nd              : bit2 + bit3 + bit4
       3rd              : bit5 + bit6 + bit7 (+ stopbit)
      The last WS2812B 'bit' is represented by 4 USART bits,
      which proved to be acceptable for the WS2812B!
       USART data polarity is negative (0-bit = high, 1-bit = low),
      but we need positive polarity. Since polarity of start- and stop-bits
      is fixed and part of the signal to the ws2812b, the data-bits
      are in inverted polarity ('0' = 0b011, '1' = 0b001') and
      a polarity inverter is required. The polarity inverted can be an
      external circuit, but when BAUDCON_CKTXP/TXCKP is present with
      this PIC it is used to invert the signal.

- `_transfer_byte(byte in data)`

      Title:   Transmit a byte (with 3 WS2812B 'bits')
      Input:   Byte with 3 WS2812B bits in the form of 9 USART bits.
      The startbit is fixed 1, so only 8 bits need be passed.
      Notes: - We do not wait for completion immediately after a write, but
      wait for completion of the previous write before the next write!
      This allows to execute instructions during the transfer time to
      prepare for the transmission of the next byte.

### Functions

## Related samples

Here are the list of samples which use this library:

12f1840 | 12f1840_ws2812b_async.jal
18f14k22 | 18f14k22_ws2812b_async.jal
18f25k22 | 18f25k22_ws2812b_async.jal