ws2812 0.0.2

data/ext/ws2812/ws2811.h

@@ -0,0 +1,69 @@
+/*
+ * ws2811.h
+ *
+ * Copyright (c) 2014 Jeremy Garff <jer @ jers.net>
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are permitted
+ * provided that the following conditions are met:
+ *
+ *     1.  Redistributions of source code must retain the above copyright notice, this list of
+ *         conditions and the following disclaimer.
+ *     2.  Redistributions in binary form must reproduce the above copyright notice, this list
+ *         of conditions and the following disclaimer in the documentation and/or other materials
+ *         provided with the distribution.
+ *     3.  Neither the name of the owner nor the names of its contributors may be used to endorse
+ *         or promote products derived from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+ * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+
+#ifndef __WS2811_H__
+#define __WS2811_H__
+
+#include "pwm.h"
+
+
+#define WS2811_TARGET_FREQ                       800000   // Can go as low as 400000
+
+struct ws2811_device;
+
+typedef uint32_t ws2811_led_t;                   //< 0x00RRGGBB
+typedef struct
+{
+    int gpionum;                                 //< GPIO Pin with PWM alternate function, 0 if unused
+    int invert;                                  //< Invert output signal
+    int count;                                   //< Number of LEDs, 0 if channel is unused
+    int brightness;                              //< Brightness value between 0 and 255
+    ws2811_led_t *leds;                          //< LED buffers, allocated by driver based on count
+} ws2811_channel_t;
+
+typedef struct
+{
+    struct ws2811_device *device;                //< Private data for driver use
+    uint32_t freq;                               //< Required output frequency
+    int dmanum;                                  //< DMA number _not_ already in use
+    ws2811_channel_t channel[RPI_PWM_CHANNELS];
+} ws2811_t;
+
+
+int ws2811_init(ws2811_t *ws2811);               //< Initialize buffers/hardware
+void ws2811_fini(ws2811_t *ws2811);              //< Tear it all down
+extern uint8_t ws2811_direct_colors;             //< Set to non-zero to bypass "brightness" [gamma correction] altogether (default is 0)
+int ws2811_render(ws2811_t *ws2811);             //< Send LEDs off to hardware
+extern uint32_t ws2811_dma_error;                //< DMA errors from ws2811_wait go here
+int ws2811_wait(ws2811_t *ws2811);               //< Wait for DMA completion
+
+
+#endif /* __WS2811_H__ */
+

data/lib/ws2812.rb

@@ -0,0 +1,20 @@
+module Ws2812
+	VERSION = "0.0.2"
+end
+
+# to make it all less confusing
+WS2812 = Ws2812
+
+if $__WS2812_SKIP_LL
+	module Ws2812
+		module Lowlevel
+			# XXX: could provide full blown emulation of all calls? :)
+		end
+	end
+else
+	require 'ws2812/lowlevel'
+end
+require 'ws2812/color'
+require 'ws2812/basic'
+require 'ws2812/unicornhat'
+require 'ws2812/gamma_correction'

data/lib/ws2812/basic.rb

@@ -0,0 +1,195 @@
+module Ws2812
+	##
+	# Provides basic interface for so called NeoPixels (ws2812 RGB LED
+	# chips)
+	#
+	# This library internally uses C (and SWIG) extension from Richard Hirst's
+	# version of Jeremy Garff's rpi_ws281x library.
+	#
+	# And this particular class is heavily inspired by the included
+	# <tt>neopixel.py</tt> Python class within these projects.
+	#
+	# See:
+	# [jgarff]        https://github.com/jgarff/rpi_ws281x
+	# [richardghirst] https://github.com/richardghirst/rpi_ws281x
+	# [pimoroni]      https://github.com/pimoroni/unicorn-hat/tree/master/python/rpi-ws281x
+	#
+	#
+	class Basic
+		include Ws2812::Lowlevel
+
+		##
+		# Initializes the basic ws2812 driver for +num+ leds at given +pin+,
+		# with initial +brightness+ (0..255)
+		#
+		# The +options+ hash can contain various additional options
+		# (all keys as symbols):
+		#
+		# [freq]    frequency (Hz) to communicate at, defaults to 800_000
+		# [dma]     dma channel to use, defaults to 5
+		# [invert]  use inverted logic, defaults to false
+		# [channel] which channel to use, defaults to 0 (permissible 0, 1)
+		def initialize(num, pin, brightness = 50, options = {})
+
+			freq = options.fetch(:freq) { 800_000 }
+			dma = options.fetch(:dma) { 5 }
+			invert = options.fetch(:invert) { false }
+			channel = options.fetch(:channel) { 0 }
+
+			@leds = Ws2811_t.new
+			@leds.freq = freq
+			@leds.dmanum = dma
+
+			@channel = ws2811_channel_get(@leds, channel)
+			@channel.count = num
+			@channel.gpionum = pin
+			@channel.invert = invert ? 1 : 0
+			@channel.brightness = brightness
+
+			@count = num
+
+			at_exit { self.close }
+
+			@open = false
+		end
+
+		##
+		# Is gamma correction (brightness) bypassed?
+		def direct?
+			!Ws2812::Lowlevel.ws2811_direct_colors.zero?
+		end
+
+		##
+		# Instruct lowlevel driver to bypass gamma correction (brightness)
+		# and use the color values straight as they are given
+		def direct=(value)
+			Ws2812::Lowlevel.ws2811_direct_colors = !!value ? 1 : 0
+		end
+
+		##
+		# Actually opens (initializes) communication with the LED strand
+		#
+		# Raises an exception when the initialization fails.
+		#
+		# Failure is usually because you don't have root permissions
+		# which are needed to access /dev/mem and to create special
+		# devices.
+		def open
+			return nil if @open
+			resp = ws2811_init(@leds)
+			fail "init failed with code: " + resp.to_s + ", perhaps you need to run as root?" unless resp.zero?
+			@open = true
+			self
+		end
+
+		##
+		# Closes (deinitializes) communication with the LED strand
+		#
+		# Can be called on already closed device just fine
+		def close
+			if @open && @leds
+				@open = false
+				ws2811_fini(@leds)
+				@channel = nil # will GC the memory
+				@leds = nil
+				# Note: ws2811_fini will free mem used by led_data internally
+			end
+			self
+		end
+
+
+		##
+		# Apply all changes since last show
+		#
+		# This method renders all changes (brightness, pixels) done to the
+		# strand since last show
+		def show
+			resp = ws2811_render(@leds)
+			fail "show failed with code: " + resp.to_s unless resp.zero?
+		end
+
+		##
+		# Set given pixel identified by +index+ to +color+
+		#
+		# See +set+ for a method that takes individual +r+, +g+, +b+
+		# components
+		def []=(index, color)
+			if index.respond_to?(:to_a)
+				index.to_a.each do |i|
+					check_index(i)
+					ws2811_led_set(@channel, i, color.to_i)
+				end
+			else
+				check_index(index)
+				ws2811_led_set(@channel, index, color.to_i)
+			end
+		end
+
+		##
+		# Set given pixel identified by +index+ to +r+, +g+, +b+
+		#
+		# See <tt>[]=</tt> for a method that takes +Color+ instance instead
+		# of individual components
+		def set(index, r, g, b)
+			check_index(index)
+			self[index] = Color.new(r, g, b)
+		end
+
+		##
+		# Set brightness used for all pixels
+		#
+		# The value is from +0+ to +255+ and is internally used as a scaler
+		# for all colors values that are supplied via <tt>[]=</tt>
+		def brightness=(val)
+			@channel.brightness = val
+		end
+
+		##
+		# Return brightness used for all pixels
+		#
+		# The value is from +0+ to +255+ and is internally used as a scaler
+		# for all colors values that are supplied via <tt>[]=</tt>
+		def brightness
+			@channel.brightness
+		end
+
+		##
+		# Number of leds it's initialized for
+		#
+		# Method actually passes to low-level implementation for this
+		# value; it doesn't use the parameter passed during construction
+		def count
+			@channel.count
+		end
+
+		##
+		# Return +Color+ of led located at given index
+		#
+		# Indexed from 0 upto <tt>#count - 1</tt>
+		def [](index)
+			if index.respond_to?(:to_a)
+				index.to_a.map do |i|
+					check_index(i)
+					Color.from_i(ws2811_led_get(@channel, i))
+				end
+			else
+				check_index(index)
+				Color.from_i(ws2811_led_get(@channel, index))
+			end
+		end
+
+		##
+		# Verify supplied index
+		#
+		# Raises ArgumentError if the supplied index is invalid
+		# (doesn't address configured pixel)
+		def check_index(index)
+			if 0 <= index && index < @count
+				true
+			else
+				fail ArgumentError, "index #{index} outside of permitted range [0..#{count})"
+			end
+		end
+		private :check_index
+	end
+end

data/lib/ws2812/color.rb

@@ -0,0 +1,33 @@
+module Ws2812
+	##
+	# Simple wrapper class around RGB based color
+	class Color
+		def initialize(r, g, b)
+			@r, @g, @b = r, g, b
+		end
+		attr_accessor :r, :g, :b
+
+		##
+		# Converts color to integer by encoding +r+, +g+, +b+
+		# as 8bit values (in this order)
+		#
+		# Thus <tt>Color.new(1,2,3).to_i # => 66051</tt>
+		def to_i
+			((r & 0xff) << 16) | ((g & 0xff) << 8) | (b & 0xff)
+		end
+
+		##
+		# Converts color from integer +i+ by taking the least significant
+		# 24 bits and using them for r(8), g(8), b(8); in this order.
+		def self.from_i(i)
+			Color.new((i >> 16) & 0xff, (i >> 8) & 0xff, i & 0xff)
+		end
+
+
+		# Makes sense to represent color as hex, right?
+		def to_hex
+			"#%02x%02x%02x" % [r & 0xff, g & 0xff, b & 0xff]
+		end
+		alias_method :to_s, :to_hex
+	end
+end

data/lib/ws2812/gamma_correction.rb

@@ -0,0 +1,72 @@
+module Ws2812
+	##
+	# This class implements (on Ruby level) the gamma correction that is
+	# internally used as part of the +brightness+ setup.
+	#
+	# It's especially useful if you want to mess around with pixel brightness
+	# in <em>direct mode</em>. See the <em>digiclock</em> example for more info.
+	class GammaCorrection
+		# correction table thanks to http://rgb-123.com/ws2812-color-output/
+		GAMMA_TABLE = [
+			0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+			0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2,
+			2, 2, 2, 3, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5,
+			6, 6, 6, 7, 7, 7, 8, 8, 8, 9, 9, 9, 10, 10, 11, 11,
+			11, 12, 12, 13, 13, 13, 14, 14, 15, 15, 16, 16, 17, 17, 18, 18,
+			19, 19, 20, 21, 21, 22, 22, 23, 23, 24, 25, 25, 26, 27, 27, 28,
+			29, 29, 30, 31, 31, 32, 33, 34, 34, 35, 36, 37, 37, 38, 39, 40,
+			40, 41, 42, 43, 44, 45, 46, 46, 47, 48, 49, 50, 51, 52, 53, 54,
+			55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70,
+			71, 72, 73, 74, 76, 77, 78, 79, 80, 81, 83, 84, 85, 86, 88, 89,
+			90, 91, 93, 94, 95, 96, 98, 99,100,102,103,104,106,107,109,110,
+			111,113,114,116,117,119,120,121,123,124,126,128,129,131,132,134,
+			135,137,138,140,142,143,145,146,148,150,151,153,155,157,158,160,
+			162,163,165,167,169,170,172,174,176,178,179,181,183,185,187,189,
+			191,193,194,196,198,200,202,204,206,208,210,212,214,216,218,220,
+			222,224,227,229,231,233,235,237,239,241,244,246,248,250,252,255
+		]
+
+		def initialize(brightness)
+			self.brightness = brightness
+		end
+
+		def brightness=(value)
+			raise ArgumentError, "brightness should be within (0..255)" unless (0..255).include?(value.to_i)
+			@brightness = value.to_i
+		end
+		attr_reader :brightness
+
+		def correct(value)
+			if value.kind_of?(Color)
+				Color.new(
+					self.correct(value.r),
+					self.correct(value.g),
+					self.correct(value.b))
+			else
+				raise ArgumentError, "value should be within (0..255)" unless (0..255).include?(value.to_i)
+				(GAMMA_TABLE[value.to_i] * (@brightness + 1)) >> 8
+			end
+		end
+
+		def correct_with_min_max(value, min = nil, max = nil)
+			trim(correct(value), min, max)
+		end
+
+		def trim(value, min = nil, max = nil)
+			if value.kind_of?(Color)
+				Color.new(
+					self.trim(value.r, min && min.r, max && max.r),
+					self.trim(value.g, min && min.g, max && max.g),
+					self.trim(value.b, min && min.b, max && max.b))
+			else
+				if min && value.to_i < min.to_i
+					min.to_i
+				elsif max && value.to_i > max.to_i
+					max.to_i
+				else
+					value.to_i
+				end
+			end
+		end
+	end
+end

data/lib/ws2812/unicornhat.rb

@@ -0,0 +1,209 @@
+module Ws2812
+	##
+	# Provides interface for *Unicorn HAT* (a 8x8 ws2812 matrix by Pimoroni)
+	#
+	# This particular class is heavily inspired by the <tt>unicornhat.py</tt>
+	# class from UnicornHat's repo.
+	#
+	# See:
+	# [unicornhat] https://github.com/pimoroni/unicorn-hat
+	#
+	class UnicornHAT
+		UHAT_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]
+		]
+		##
+		# Initializes the matrix ws2812 driver at given +pin+,
+		# with initial +brightness+ (0..255)
+		#
+		# The +options+ hash can contain various additional options,
+		# see +Basic+ class' description of options for more details.
+		def initialize(pin = 18, brightness = 50, options = {})
+			@hat = Basic.new(64, pin, brightness, options)
+			@hat.open
+
+			@rotation = 0
+			@pixels = Array.new(8) { |x| Array.new(8) { |y| Color.new(0,0,0) } }
+			push_all_pixels
+		rescue Object
+			@hat = nil
+			raise
+		end
+
+		# Query direct mode. See <em>Ws2812::Basic</em> for explanation.
+		def direct?
+			@hat.direct?
+		end
+
+		##
+		# Set direct mode. See <em>Ws2812::Basic</em> for explanation.
+		def direct=(value)
+			@hat.direct = value
+		end
+
+		##
+		# Closes (deinitializes) communication with the matrix
+		#
+		# Can be called on already closed device just fine
+		def close
+			if @hat
+				@hat.close
+				@hat = nil
+			end
+			self
+		end
+
+		##
+		# Apply all changes since last show
+		#
+		# This method renders all changes (brightness, pixels, rotation)
+		# done to the strand since last show
+		def show
+			@hat.show
+		end
+
+		##
+		# Set given pixel identified by +x+, +y+ to +color+
+		#
+		# See +set+ for a method that takes individual +r+, +g+, +b+
+		# components.
+		#
+		# You still have to call +show+ to make the changes visible.
+		def []=(x, y, color)
+			check_coords(x, y)
+			@pixels[x][y] = color
+			@hat[map_coords(x, y)] = color
+		end
+
+		##
+		# Set given pixel identified by +x+, +y+ to +r+, +g+, +b+
+		#
+		# See <tt>[]=</tt> for a method that takes +Color+ instance instead
+		# of individual components.
+		#
+		# You still have to call +show+ to make the changes visible.
+		def set(x, y, r, g, b)
+			check_coords(x, y)
+			self[x, y] = Color.new(r, g, b)
+		end
+
+		##
+		# Set brightness used for all pixels
+		#
+		# The value is from +0+ to +255+ and is internally used as a scaler
+		# for all colors values that are supplied via <tt>[]=</tt>
+		#
+		# You still have to call +show+ to make the changes visible.
+		def brightness=(val)
+			@hat.brightness = val
+		end
+
+		##
+		# Return brightness used for all pixels
+		#
+		# The value is from +0+ to +255+ and is internally used as a scaler
+		# for all colors values that are supplied via <tt>[]=</tt>
+		def brightness
+			@hat.brightness
+		end
+
+		##
+		# Return +Color+ of led located at given +x+, +y+
+		def [](x, y)
+			@pixels[x][y]
+		end
+
+		##
+		# Returns current rotation as integer; one of: [0, 90, 180, 270]
+		def rotation
+			@rotation
+		end
+
+		##
+		# Set rotation of the Unicorn HAT to +val+
+		#
+		# Permissible values for rotation are [0, 90, 180, 270] (mod 360).
+		#
+		# You still have to call +show+ to make the changes visible.
+		def rotation=(val)
+			permissible = [0, 90, 180, 270]
+			fail ArgumentError, "invalid rotation, permissible: #{permissible.join(', ')}" unless permissible.include?(val % 360)
+			@rotation = val % 360
+			push_all_pixels
+		end
+
+		##
+		# Clears all pixels (sets them to black) and calls +show+ if +do_show+
+		def clear(do_show = true)
+			set_all(Color.new(0, 0, 0))
+			show if do_show
+		end
+
+		##
+		# Sets all pixels to +color+
+		#
+		# You still have to call +show+ to make the changes visible.
+		def set_all(color)
+			0.upto(7) do |x|
+				0.upto(7) do |y|
+					self[x, y] = color
+				end
+			end
+		end
+
+		##
+		# Pushes all pixels from buffer to the lower level (physical device)
+		#
+		# This is internally used when changing rotation but it can be useful
+		# when you set several pixels to the same Color instance and then
+		# manipulate those pixels' color all at once.
+		def push_all_pixels
+			0.upto(7) do |x|
+				0.upto(7) do |y|
+					@hat[map_coords(x, y)] = @pixels[x][y]
+				end
+			end
+		end
+
+
+		##
+		# Maps +x+, +y+ coordinates to index on the physical matrix
+		# (takes rotation into account)
+		def map_coords(x, y)
+			check_coords(x, y)
+			y = 7 - y
+			case rotation
+			when 90
+				x, y = y, 7 - x
+			when 180
+				x, y = 7 - x, 7 - y
+			when 270
+				x, y = 7 - y, x
+			end
+
+			UHAT_MAP[x][y]
+		end
+		private :map_coords
+
+		##
+		# Verify supplied coords +x+ and +y+
+		#
+		# Raises ArgumentError if the supplied coords are invalid
+		# (doesn't address configured pixel)
+		def check_coords(x, y)
+			if 0 <= x && x < 8 && 0 <= y && y < 8
+				true
+			else
+				fail ArgumentError, "coord (#{x},#{y}) outside of permitted range ((0..7), (0..7))"
+			end
+		end
+		private :check_coords
+	end
+end