Updated documentation

EXTREMELY_IMPORTANT_WARNINGS.txt

@@ -1,3 +1,6 @@
+Original Warning from https://github.com/626Pilot/RaspberryPi-NeoPixel-WS2812
+but included here because it's useful information!
+
 You are using this at your OWN RISK. I believe this software is reasonably safe to use (aside
 from the intrinsic risk to those who are photosensitive - see below), although I can't be certain
 that it won't trash your hardware or cause property damage.

c/README.md

@@ -0,0 +1,20 @@
+Unicorn Hat C Example
+=====================
+
+This example shows the ws2812 library being used within a C application.
+
+You'll need to install libpng before building unicorn.c
+
+Build with:
+
+    make
+
+Then run unicorn for pretty lights!
+
+Notes
+-----
+
+If you plan on writing your own C applications to control ws2812 LEDs then please pay special attention
+to how unicorn.c handles exit signals and terminates cleanly.
+
+You absolutely must call terminate() on the ws2812 library when exiting!

python/UnicornHat/README.md

@@ -0,0 +1,31 @@
+Unicorn Hat Python Library
+==========================
+
+This library wraps the ws2812 python driver for UnicornHat, handling conversion of X/Y coordinates to pixel index
+and exposing the basic methods you need to set pixels and update UnicornHat.
+
+
+Installing
+----------
+
+** PIP **
+
+    sudo pip install unicornhat
+
+** GitHub **
+
+    sudo ./setup.py install
+
+
+Usage
+-----
+
+Just import UnicornHat, it'll set up ws2812 for you!
+
+Then all you need is:
+
+* UnicornHat.set_pixel( x, y, red, blue, green ) - Set a pixel in the buffer to the specified colour
+* UnicornHat.show - Update UnicornHat with the current buffer
+* UnicornHat.clear - Turn off all the pixels in the buffer and update UnicornHat
+
+See the examples for more advanced usage.

python/UnicornHat/UnicornHat.py

@@ -1,45 +1,84 @@
 import ws2812, atexit
 
 def clean_shutdown():
-  clear()
-  # Call the cleanup function
+  '''
+  Registered at exit to ensure ws2812 cleans up after itself
+  and all pixels are turned off.
+  '''
+  off()
   ws2812.terminate(0)
 
 atexit.register(clean_shutdown)
 
+'''
+Initialize ws2812 with a buffer of 64 pixels ( 8x8 )
+'''
 ws2812.init(64)
 
+'''
+Store a map of pixel indexes for
+translating x, y coordinates.
+'''
+map = [
+  [7 ,6 ,5 ,4 ,3 ,2 ,1 ,0 ],
+  [8 ,9 ,10,11,12,13,14,15],
+  [23,22,21,20,19,18,17,16],
+  [24,25,26,27,28,29,30,31],
+  [39,38,37,36,35,34,33,32],
+  [40,41,42,43,44,45,46,47],
+  [55,54,53,52,51,50,49,48],
+  [56,57,58,59,60,61,62,63]
+]
+
+def brightness(b = 0.2):
+  '''
+  Set the display brightness between 0.0 and 1.0
+  0.2 is highly recommended, UnicornHat can get painfully bright!
+  '''
+  if b > 1 or b < 0:
+    raise ValueError('Brightness must be between 0.0 and 1.0')
+    return
+  ws2812.setBrightness(b)
+
 def clear():
-  # Clear the display
+  '''
+  Clear the buffer
+  '''
   for x in range(64):
     ws2812.setPixelColor(x,0,0,0)
-  ws2812.show()
+
+def off():
+  '''
+  Clear the buffer and immediately update UnicornHat to
+  turn off all pixels.
+  '''
+  clear()
+  show()
 
 def get_index_from_xy(x, y):
-  if x > 7:
+  '''
+  Convert an x, y value to an index on the display
+  '''
+  if x > 7 or x < 0:
     raise ValueError('X position must be between 0 and 7')
     return
-  if y > 7:
+  if y > 7 or y < 0:
     raise ValueError('Y position must be between 0 and 7')
     return
 
-  map = [
-    [7 ,6 ,5 ,4 ,3 ,2 ,1 ,0 ],
-    [8 ,9 ,10,11,12,13,14,15],
-    [23,22,21,20,19,18,17,16],
-    [24,25,26,27,28,29,30,31],
-    [39,38,37,36,35,34,33,32],
-    [40,41,42,43,44,45,46,47],
-    [55,54,53,52,51,50,49,48],
-    [56,57,58,59,60,61,62,63]
-  ]
-
   return map[x][y]
 
 def set_pixel(x, y, r, g, b):
+  '''
+  Set a single pixel to RGB colour
+  '''
   index = get_index_from_xy(x, y)
   if index != None:
     ws2812.setPixelColor(index, r, g, b)
 
 def show():
+  '''
+  Update UnicornHat with the contents
+  of the display buffer
+  '''
   ws2812.show()

python/ws2812/README.md

@@ -38,3 +38,17 @@ Reference
 * theaterChase(color, wait) - Animate a colour across pixels
 
 * terminate(0) - Should ideally be called upon exiting to clean up hardware
+
+Changes
+-------
+
+Please do not modify ws2812-RPi_wrap.c or ws2812.py directly.
+
+You should change only the bindings file: ws2812-RPi.i
+
+Changes to this file will let you use SWIG to auto-generate the correct bindings:
+
+   swig2.0 -python ws2812-RPi.i
+
+If you wish to add any Python methods for a specific product or application, then it's
+recommended that you create a separate module ( like UnicornHat ).

python/ws2812/lib/ws2812-RPi.h

@@ -394,7 +394,7 @@ void * map_peripheral(uint32_t base, uint32_t len);
 // =================================================================================================
 
 // Brightness - I recommend 0.2 for direct viewing at 3.3v.
-#define DEFAULT_BRIGHTNESS 0.9
+#define DEFAULT_BRIGHTNESS 0.2
 float brightness;
 
 // LED buffer (this will be translated into pulses in PWMWaveform[])

python/ws2812/ws2812-RPi.i

@@ -28,6 +28,8 @@ extern void rainbowCycle(uint8_t wait);
 extern void theaterChase(Color_t c, uint8_t wait);
 extern void theaterChaseRainbow(uint8_t wait);
 
+extern unsigned char setBrightness(float b);
+
 extern Color_t RGB2Color(unsigned char r, unsigned char g, unsigned char b);
 extern Color_t Color(unsigned char r, unsigned char g, unsigned char b);
 extern unsigned char setPixelColor(unsigned int pixel, unsigned char r, unsigned char g, unsigned char b);