# ws2812b_sync

Library to support a chain of WS2812B chips via USART interface

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

Description

    Library to control a chain of WS2812Bs
    This library uses the USART module with master SYNC 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 DIN wire of the WS2812B must be connected to pin_RX/DT of the PIC.
      - The pin_RX/DT may have to be configured with Peripheral Pin Select (PPS)
        or Alternate Pin Function (APFCON_RXDTSEL),
        (the clock pin is not used).
    - Because the WS2812b requires low-level for reset and the (E)USART
      keeps RXDT high-level in idle-state an external polarity inverter is
      required. The library generates an 'inverted' bitstream.
    - The number of WS2812Bs in the chain must be defined with a constant:
         const WS2812B_NUM = 30               -- for 30 chained WS2812Bs
    - The user program should contain 3 byte arrays of WS2812B_NUM bytes each,
      one for green, one for red, one for blue, e.g.:
         var byte agreen[WS2812B_NUM]
         var byte ared[WS2812B_NUM]
         var byte ablue[WS2812B_NUM]
    - Initialize the interface with procedure ws2812b_sync_init().
    - Procedure ws2812b_refresh() is used to pass the current color settings
      to the WS2812B LEDs.
    - Procedure ws2812b_all_color() can be used to give all LEDs the same
      color (or clear all leds with intensity 0) while keeping
      the color settings in the arrays unchanged.

Notes

    - Warnings are temporary(?) commented out.

Dependencies

- ws2812b_common

## Summary

### Global variables/contants

### Procedures

- `ws2812b_sync_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_sync_init()`

      Title:   Initialize the USART for Synchronous transmit at the required speed
      Input:   (none)
      Notes:   Transmit mode only (clock pin not really used)
      Baudrate rounded up (too fast works better than too slow)

Private

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

      Title:  Transfer 3 color bytes to the WS2812B chain
      Input:  Color intensities of green, red and blue (3 bytes)
      Notes:  - Each WS2812B bit is represented by 3 USART bits:
      (WS2812B '0' = 0b100, WS2812B '1' = 0b110).
       The USART is configured for 9 databits (sync: no start-/stop-bits),
      thus 3 ws2812b-bits fit in a USART databyte (with bit 9 fixed 1).
       The USART transfers data with least significant bit first
      therefore the bit patterns become 0->'001' and 1->'011'
       Because of the required external inverter: 0->'110' and 1->'100'

- `_transfer_byte(byte in data)`

      Title:   Transmit a byte (with 3 WS2812B 'bits')
      Input:   Byte with 3 WS2812B bits as 9 USART bits.
      The 9th bit is fixed, so only 8 bits need be passed.
      Notes: - We do not wait for completion after a write, but we need
      to wait for TXREG being empty before transfer of data.

### Functions

## Related samples

Here are the list of samples which use this library:

12f1840 | 12f1840_ws2812b_sync.jal
18f14k22 | 18f14k22_ws2812b_sync.jal
18f25k22 | 18f25k22_ws2812b_sync.jal