added wiring documentation

added documentation for the python module tlc5947

README.md

@@ -10,6 +10,14 @@ This is a driver for the [TLC5947](http://www.ti.com/product/TLC5947) 24 Channel
 
 ## Getting Started <a name = "getting_started"></a>
 
+### Wiring
+This driver is designed for driving RGB LED's that are connected to a TLC5947.
+The Wiring of the RGB led's is currently fixed to the order RGB (Red/Green/Blue).
+
+<p align="center"><img src="doc/schematic.png" alt="doc/schematic.png"></p>
+
+If your application requires a different type of wiring, please submit an issue.
+
 ### Prerequisites
 This driver is designed for [micropython](https://github.com/micropython/micropython).
 
@@ -65,4 +73,4 @@ The module is available by just importing tlc5947:
 import tlc5947
 ```
 
-The module documentation is coming soon!
+The documentation for the module is [here](doc/tlc5947.md).

doc/format.md

@@ -0,0 +1 @@
+# WIP

doc/tlc5947.md

@@ -0,0 +1,189 @@
+# TLC5947 RGB LED driver
+
+## tlc5947.tlc5947(spi, xlat, blank)
+Constructs a tlc5947 object with the given spi bus and config pins for
+the tlc5947. The SPI object must be configured before it is given to
+the constructor, this allows any SPI config to be used with this
+module. The `xlat`/`blank` pins must also be configured before they
+are passed to the constructor.
+
+```python
+from tlc5947 import tlc5947
+from pyb import SPI, Pin
+
+spi = SPI(2, SPI.MASTER, baudrate=20000000)
+xlat = Pin(Pin.board.TLC5947_XLAT, Pin.OUT_PP)
+blank = Pin(Pin.board.TLC5947_BLANK, Pin.OUT_OD)
+
+tlc = tlc5947(spi, xlat, blank)
+```
+
+The SPI baudrate can be chosen anywhere at or below 20000000, since
+this is the fastest baudrate supported by the tlc5947. If possible it
+should be as chosen as high as possible.
+
+The minimum SPI baudrate is calculated as follows:
+```python
+frequency = 100 # see __call__
+bits = 288      # the tlc buffer is 288 bits
+minumum_baudrate = frequency * (bits + bits * 0.1)
+```
+
+This leaves barely any room for other applications and should only be
+used when absolutely required.
+
+This setup allows the `tlc5947` object to be used without requiring
+any knowledge about the `xlat` or `blank` pins or how to configure the
+SPI peripheral.
+
+
+### tlc5947.tlc5947().\_\_call\_\_() -> None
+This is the call() method of the tlc5947 object, it is the method that
+causes anything to happen, all other methods just read/write the
+internal state. When this method is called, every pattern is advanced
+one step forward all LED's are updated with their new colors if there
+are new colors, and then they are written out to the TLC5947 device
+and latched onto the Gray-scale registers.
+
+This method should be called in regular intervals, the exact frequency
+depends on the particular application. The frequency must be a
+multiple of the fastest desired update rate.
+
+example: If you want to fade an LED from one to another color in 100
+steps, in 1 second, the frequency must be N*100Hz. N can be 1, there
+is no reason for a faster frequency if it is not needed. But be aware
+that any change will happen at this frequency.
+
+```python
+from pyb import Timer
+
+timer = Timer(7, freq=100) # call 100 times per second
+timer.callback(tlc)        # register the __call__ method
+```
+
+Any reference to `tick` in this documentation refers to this, in this
+example the frequency of the timer is the tick rate of the driver.
+
+
+### tlc5947.tlc5947().blank(self, val) -> None
+This method just sets and clears the BLANK pin of the TLC5947 device.
+Use this method and not the pyb.Pin() directly, since this makes it
+possible for the driver to stop sending the data over the SPI bus
+while the driver is BLANK'ed.
+
+This optimization is not implemented for now, but it is possible.
+
+
+### tlc5947.tlc5947().set(self, leds, pattern) -> int
+This method set's LED's or a single led to a specific pattern. The
+leds can be given as a single int representing an individual led, or a
+list of int's representing any number of led's.
+
+The pattern is a string that must be a valid Pattern format.
+For a description of the Pattern format see [this](format.md).
+
+```python
+pid1 = tlc.set(1, "#FF0000")
+pid2 = tlc.set([2, 3, 4], "#FF0000")
+pid3 = tlc.set([7], "#FF0000")
+```
+
+This method returns a so called pattern ID. This pattern ID can be
+used in the next methods to refer back to the pattern set here.
+
+
+### tlc5947.tlc5947().replace(self, pattern\_id, pattern) -> int
+This method can be used to replace an existing pattern with a new
+pattern while keeping the same pattern ID.
+
+```python
+pid = tlc.set(1, "@;") # set a transparent and infinite pattern
+                       # this basically reserves the pattern ID
+
+# do other stuff
+
+tlc.replace(pid, "#F0F0F0;")
+```
+
+This method returns the same pid that was passed in.
+
+Why this method is usefull is described [here](format.md).
+
+
+### tlc5947.tlc5947().delete(self, pattern\_id) -> bool
+This method deletes a pattern, returns true on success.
+
+If this method returns false, the pattern ID either did not exist or
+was not valid.
+
+Infinite Patterns (see [here](format.md)) can only be removed directly
+with this method (Or by replacing it by a finite pattern).
+
+
+### tlc5947.tlc5947().get(self, led) -> str
+This method return's the current color of the LED.
+
+The color is taken directly from the internal copy of the tlc5947
+buffer. If a pattern is running that changes the RGB value of the
+LED, this method can be used to get the current color.
+
+```
+from time import sleep
+
+# color fade from red to black(off)
+pid = tlc.set(1, "<5[#FF0000<10[|50\b-0.1-]>-|50]")
+
+while tlc.exists(pid):
+    # Print the current RGB value of LED 1
+    print(tlc.get(1))
+    sleep(0.05)
+```
+
+
+### tlc5947.tlc5947().exists(self, pattern\_id) -> bool
+This checks if the pattern ID given exists and is still in use. This
+can be used for timed patterns to see when they are finished.
+
+```python
+# This pattern takes 50 ticks
+pid1 = tlc.set(1, "#FF0000|50#0000FF")
+
+while tlc.exists(pid):
+    pass
+print("Pattern Done")
+```
+
+It is important to keep in mind that pattern ID's while they are
+unique, meaning one pattern ID refers to one pattern, they can be
+reused.
+The pattern ID is a unsigned 16bit integer, the ID's are sequential
+starting at 1 and once ID 65535 is reached overflowing back to 1.
+
+
+### tlc5947.tlc5947().set\_id\_map(self, map) -> None
+This method allows the order of the LED's to be remapped to a
+different LED index.
+
+The default configuration maps LED D1 to index 1 e.g.:
+
+<p align="center"><img src="doc/schematic.png" alt="doc/schematic.png"></p>
+
+```python
+tlc.set(1, "#0000FF;") # LED D1
+tlc.set(3, "#00FF00;") # LED D3
+tlc.set(6, "#FF0000;") # LED D6
+```
+
+If your application arranges the LED's differently, it may be easier
+to address the LED's in a different order. This can be achieved with
+the `id_map`.
+
+```python
+map = [4, 3, 2, 1, -1, -1, 7, 8]
+
+tlc.set_id_map(map)
+
+tlc.set(1, "#0000FF;") # LED D4
+tlc.set(3, "#00FF00;") # LED D2
+tlc.set(6, "#FF0000;") # -> ValueError("led not in id_map")
+```