barkest_lcd 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a99d7096928cf7602e31e972939a1c563943e3e
+  data.tar.gz: f0dc18d42e43c626695111307ebec7de8af86431
+SHA512:
+  metadata.gz: 0702a57c8942c02aa0bcafd8a1ce43297e41f2f1e067c1f7496853b5326874729a9ed6dce65d88fa01bf1ef29bd5407554de3663fd9c9c8bd1d599a66e974896
+  data.tar.gz: 927118633b5bc710774e8077112a84c8b3f64fdfc2c9f18864e57b6bb267bf2cca88b207be20dc3d69a4287cf8688fae5137dd7ec5abb41e51cf0fd1eb24f847

data/.gitignore

@@ -0,0 +1,11 @@
+.bundle/
+.yardoc
+Gemfile.lock
+_yardoc/
+coverage/
+doc/
+pkg/
+spec/reports/
+tmp/
+.idea/
+/**/.DS_Store

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in barkest_lcd.gemspec
+gemspec
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Beau Barker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# BarkestLcd
+
+This gem is designed to make it easy to interface with some LCD displays.  
+
+I wanted to add a front panel LCD to a server I was building, so I started this project to address interacting with
+the LCD panel I picked up.
+
+Currently it works with the PicoLCD from [www.mini-box.com](http://www.mini-box.com/picoLCD-256x64-Sideshow-CDROM-Bay).
+
+
+## Installation
+
+This gem depends on [HID API](http://www.signal11.us/oss/hidapi/).
+
+Installation of the dependency is specific to the environment.
+
+For OS X (using homebrew):
+
+    $ brew install hidapi
+    
+For Ubuntu/Debian:
+
+    $ sudo apt-get install libhidapi-libusb0
+    $ cd /usr/lib/x86_64-linux-gnu
+    $ sudo ln -s libhidapi-libusb.so.0.0.0 libhidapi.so
+
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'barkest_lcd'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install barkest_lcd
+
+
+## Usage
+
+Let's assume you have one picoLCD 256x64 device attached to your computer.  Usage is fairly simple.
+
+This example will draw a 32x32 rectangle with an X in it.
+
+```ruby
+my_device = BarkestLcd::PicoLcdGraphic.first
+my_device.open
+my_device.draw_rect(40, 4, 32, 32).draw_line(40, 4, 72, 36).draw_line(40, 36, 72, 4)
+my_device.paint
+```
+
+As you can see, most of the methods are chainable.  Unless the method has an explicit return value (like `open?`) then
+the method should be returning the device model.  The `open`, `close`, and `paint` methods are all chainable as well.
+
+There are currently some very basic drawing methods included by the `SimpleGraphic` module.  These include `set_bit`,
+`draw_vline`, `draw_hline`, `draw_line`, and `draw_rect`.  The `clear` method will clear the screen.
+
+Continuing, we will wait for the user to press the OK button.
+
+```ruby
+OK_BUTTON = 6
+ok_pressed = false
+
+# set the callback to process keys when they are released.
+my_device.on_key_up do |key|
+  if key == OK_BUTTON
+    ok_pressed = true
+  end
+end
+
+# use the "loop" function to process events with the device and update the screen.
+until ok_pressed
+  my_device.loop
+end
+```
+
+In this case we set the `on_key_up` callback to set a flag when the OK button is pressed.  If we wanted to do repeating
+keys when a user holds down a button, we may want to set the `on_key_down` or use the `key_state` method within the loop.
+
+Finally, I recommend closing the device when you are finished.  Ruby will close the device when it exits, but if you
+are handling errors and such, closing the device explicitly in an `ensure` block will help to protect you against being
+unable to open the device again.
+
+```ruby
+my_device.clear.paint
+my_device.close
+```
+
+It is not necessary to clear the screen before closing, but doing so ensures that you do not leave weird information
+or screen artifacts up when your application is done.
+
+
+
+## Credits
+
+*   The [picoLCD 256x64 Suite Source](http://resources.mini-box.com/online/picolcd/256x64/1003/PicoLCD256x64_src.zip)
+    provided most of the information needed to make this gem interact with the picoLCD 256x64 from 
+    [mini-box](http://www.mini-box.com).
+*   The [picoLCD256x64](https://github.com/itszero/picoLCD256x64) project provided some inspiration, but I ended up going
+    a completely different direction.
+*   The font came from [Silkscreen](http://www.kottke.org/plus/type/silkscreen/index.html).
+
+## License
+
+Copyright (c) 2016 [Beau Barker](mailto:beau@barkerest.com)
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+

data/barkest_lcd.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'barkest_lcd/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "barkest_lcd"
+  spec.version       = BarkestLcd::VERSION
+  spec.authors       = ["Beau Barker"]
+  spec.email         = ["rtecoder@gmail.com"]
+
+  spec.summary       = "Provides a simple interface to LCD displays."
+  spec.description   = "This gem was originally created to interface with a PicoLCD 256x64 from www.mini-box.com."
+  spec.homepage      = "http://www.barkerest.com/"
+  spec.license       = "MIT"
+
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'libusb',   '~>0.5.1'
+  spec.add_dependency 'hidapi',   '>=0.1.4'
+
+
+  spec.add_development_dependency 'bundler',    '~> 1.12'
+  spec.add_development_dependency 'rake',       '~> 10.0'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "barkest_lcd"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/barkest_lcd.rb

@@ -0,0 +1,10 @@
+require 'barkest_lcd/version'
+require 'hidapi'
+
+module BarkestLcd
+
+end
+
+Dir.glob(File.expand_path('../models/*.rb', __FILE__)).each do |file|
+  require file
+end

data/lib/barkest_lcd/version.rb

@@ -0,0 +1,3 @@
+module BarkestLcd
+  VERSION = "0.4.0"
+end

data/lib/models/error_logger.rb

@@ -0,0 +1,21 @@
+module BarkestLcd
+  module ErrorLogger
+
+    public
+
+    ##
+    # Contains the last 100 errors that have occurred in this instance.
+    def error_history
+      @error_history ||= []
+    end
+
+    protected
+
+    def log_error(code, msg)
+      HIDAPI.debug "Encountered error (#{code.to_s(16).rjust(8, '0')}) #{msg}"
+      error_history << [ code, msg, Time.now ]
+      error_history.delete_at(0) while error_history.count > 100
+    end
+
+  end
+end

data/lib/models/font.rb

@@ -0,0 +1,404 @@
+module BarkestLcd
+  ##
+  # A basic bitmap font.
+  class Font
+
+    ##
+    # Gets or sets the name of this font.
+    attr_accessor :name
+
+    ##
+    # Gets or sets the size of this font.
+    attr_accessor :size
+
+    ##
+    # Gets or sets the bold flag.
+    attr_accessor :bold
+
+    ##
+    # Creates a new bitmap font from a hash.
+    #
+    #   glyphs = {
+    #       :name => "Font Name",   # optional
+    #       :size => 8,             # optional
+    #       :bold => false,         # optional
+    #       97 => {               # ASCII character code.
+    #           :char => "a",     # printed character.
+    #           :width => 8,      # width in pixels
+    #           :height => 8,     # height in pixels
+    #           :data => [        # array containing row data.
+    #               "        ",   # rows may be strings or arrays.
+    #               "        ",   # when strings, non-space characters are set pixels.
+    #               "   **   ",   # when arrays, values of true or 1 are set pixels.
+    #               "     *  ",
+    #               "  ****  ",
+    #               " *   *  ",
+    #               "  ****  ",
+    #               "        ",
+    #           ],
+    #       },
+    #       ...
+    #   }
+    def initialize(glyphs)
+      raise ArgumentError unless glyphs.is_a?(Hash)
+
+      @name = glyphs.delete(:name) || 'Font'
+      @size = glyphs.delete(:size) || 8
+      @bold = glyphs.delete(:bold) || false
+      @glyphs = {}
+
+      glyphs.each do |k,v|
+        k = k.to_i
+        raise ArgumentError, 'hash must have numeric keys greater than or equal to 32 and less than 127' if k < 32 || k > 127
+        raise ArgumentError, 'hash must have hashes as values' unless v.is_a?(Hash)
+        raise ArgumentError, 'hash values must have a :char key' unless v[:char]
+        raise ArgumentError, 'hash values must have a :width key' unless v[:width]
+        raise ArgumentError, 'hash values must have a :height key' unless v[:height]
+        raise ArgumentError, 'hash values must have a :data key' unless v[:data]
+        raise ArgumentError, 'hash :data key must have an array value' unless v[:data].is_a?(Array)
+
+        glyph = {
+            char: v[:char].to_s.freeze,
+            width: v[:width].to_i.freeze,
+            height: v[:height].to_i.freeze,
+            data: []
+        }
+
+        raise ArgumentError, 'hash :data value must have exactly :height members' unless v[:data].length == glyph[:height]
+        v[:data].each_with_index do |row, row_index|
+          raise ArgumentError, 'hash :data value members must be arrays or strings' unless row.is_a?(Array) || row.is_a?(String)
+          raise ArgumentError, 'hash :data value members must have :width values' unless row.length == glyph[:width]
+
+          glyph[:data][row_index] = [ false ] * glyph[:width]
+          if row.is_a?(String)
+            row.chars.each_with_index do |ch, ch_index|
+              glyph[:data][row_index][ch_index] = true unless ch == ' '   # spaces are false, everything else is true.
+            end
+          else
+            row.each_with_index do |bit, bit_index|
+              glyph[:data][row_index][bit_index] = true if bit == true || bit == 1
+            end
+          end
+          glyph[:data][row_index].freeze
+
+        end
+
+        add_glyph_helpers_to glyph
+
+        glyph[:data].freeze
+
+        glyph.freeze
+
+        @glyphs[k] = glyph
+      end
+
+      @height = @glyphs.inject(0) { |h,(key,g)| g.height > h ? g.height : h }
+      @nil_glyph = add_glyph_helpers_to(
+          {
+              char: '',
+              width: 0,
+              height: 0,
+              data: []
+          }
+      ).freeze
+    end
+
+
+    ##
+    # Gets the height of the font.
+    attr_reader :height
+
+    ##
+    # Gets a glyph for the specified character.
+    #
+    # +char+ should be a string containing the character.
+    #
+    # Glyphs are hashes that also include helper methods.
+    #
+    #   g = {
+    #     char: ' ',
+    #     width: 2,
+    #     height: 8,
+    #     data: [[false,false],[false,false],[false,false],[false,false],[false,false],[false,false],[false,false],[false,false]]
+    #   }
+    #   g.char == g[:char]
+    #   g.width == g[:width]
+    #   g.height == g[:height]
+    #   g.data == g[:data]
+    #
+    def glyph(char)
+      char = char.to_s
+      ch = char.getbyte(0).to_i
+      @glyphs[ch] || @nil_glyph
+    end
+
+    ##
+    # Gets the glyphs to draw the specified string with.
+    def glyphs(string)
+      string.to_s.chars.map { |char| glyph(char) }
+    end
+
+    ##
+    # Measures the specified string.
+    #
+    # If you supply a +max_width+ it will try to fit the string into the specified width.
+    #
+    # With a +max_width+ it returns [ width, height, lines ].
+    # Without a +max_width+ it returns [ width, height ].
+    def measure(string, max_width = -1)
+
+      # handle newlines properly.
+      if string.include?("\n")
+        w = 0
+        h = 0
+        lines = []
+        string.split("\n").each do |line|
+          w2, h2, lines2 = measure(line, max_width)
+          w = w2 if w2 > w
+          h += h2
+          lines += lines2 if lines2
+        end
+        return [ w, h, lines ] if max_width > 0
+        return [ w, h ]
+      end
+
+      # convert to string and replace all whitespace with actual spaces.
+      # we don't support tabs or care about carriage returns.
+      # we also want to reduce all whitespace sequences to a single space.
+      string = string.to_s.gsub(/\s/, ' ').gsub(/\s\s+/, ' ')
+
+      if max_width > 0
+        # we are trying to fit the string into a specific width.
+
+        # no need to measure an empty string.
+        return [ 0, height, [ string ]] if string == ''
+
+        # measure the initial string.
+        w, h = measure(string)
+
+        # we fit or there are no spaces to wrap on.
+        if w <= max_width || !string.include?(' ')
+          return [w, h, [ string ]]
+        else
+
+          # prepare to wrap on word boundaries.
+          cur_line,_,next_line = string.rpartition(' ')
+
+          # keep chopping off words until we can't chop any more off or we fit.
+          while true
+            # measure the current line.
+            w, h = measure(cur_line)
+
+            if w <= max_width || !cur_line.include?(' ')
+              # we fit or we can't split anymore.
+
+              # measure up the rest of the string.
+              w2, h2, lines = measure(next_line, max_width)
+
+              # and adjust the size as needed.
+              w = w2 if w2 > w
+              h += h2
+
+              # return the adjusted size and the lines.
+              return [ w, h, [ cur_line ] + lines ]
+            end
+
+            # chop off the next word.
+            cur_line,_,next_word = cur_line.rpartition(' ')
+
+            # add the chopped off word to the beginning of the next line.
+            next_line = next_word + ' ' + next_line
+          end
+        end
+
+
+      else
+        # we are not trying to fit the string.
+
+        # no need to measure an empty string.
+        return [ 0, height ] if string == ''
+
+        h = height
+        w = glyphs(string).inject(0) { |_w,g| _w + g[:width] }
+
+        [w, h]
+      end
+    end
+
+    ##
+    # Generates a hash that can be loaded into a font.
+    def inspect(formatted = false)
+      ret = '{'
+      ret += "\n  " if formatted
+      ret += ":name => #{name.inspect},"
+      ret += "\n  " if formatted
+      ret += ":size => #{size.inspect},"
+      ret += "\n  " if formatted
+      ret += ":bold => #{bold.inspect},"
+      ret += "\n  " if formatted
+      @glyphs.each do |key, glyph|
+        ret += "#{key.inspect} => {"
+        ret += "\n    " if formatted
+        ret += ":char => #{glyph[:char].inspect},"
+        ret += "\n    " if formatted
+        ret += ":width => #{glyph[:width].inspect},"
+        ret += "\n    " if formatted
+        ret += ":height => #{glyph[:height].inspect},"
+        ret += "\n    " if formatted
+        ret += ':data => ['
+        ret += "\n      " if formatted
+        glyph[:data].each do |row|
+          ret += "#{row.map{|bit| bit ? '#' : ' '}.join('').inspect},"
+          ret += "\n      " if formatted
+        end
+        ret = ret.rstrip + "\n    " if formatted
+        ret += '],'
+        ret += "\n  " if formatted
+        ret += '},'
+        ret += "\n  " if formatted
+      end
+      ret = ret.rstrip + "\n" if formatted
+      ret + '}'
+    end
+
+    def to_s # :nodoc:
+      "#{name} #{bold ? 'Bold' : 'Regular'} #{size}pt"
+    end
+
+    def freeze # :nodoc
+      name.freeze
+      size.freeze
+      bold.freeze
+      super
+    end
+
+    ##
+    # Attempts to load and process a font.
+    #
+    # Returns  a Font on success, or nil on failure.
+    #
+    # There is a possibility that it will load an incorrect font.
+    #
+    # REQUIRES: rmagick
+    #
+    # Since the BarkestLcd gem doesn't require 'rmagick', this will always return false by default.
+    # If your application includes the 'rmagick' gem, then you can create fonts.  Or you can use an
+    # IRB console to create fonts.
+    #
+    # The created fonts should be stored as a ruby object.  The constants defined in the BarkestLcd::Font class
+    # were created in this manner.
+    def self.create(font_name = 'Helvetica', size = 8, bold = false)
+      return nil if font_name.to_s == ''
+      return nil if size < 4 || size > 144
+
+      begin
+        require 'rmagick'
+
+        max_black = (Magick::QuantumRange * 0.5).to_i
+
+        img = Magick::Image.new(200,200)
+
+        def img.char_width
+          get_pixels(0, 0, columns, 1).each_with_index do |px, x|
+            return x if px.to_color == 'magenta'
+          end
+          nil
+        end
+
+        def img.char_height
+          get_pixels(0, 0, 1, rows).each_with_index do |px, y|
+            return y if px.to_color == 'magenta'
+          end
+          nil
+        end
+
+        img.background_color = 'magenta'
+        img.erase!
+
+        draw = Magick::Draw.new
+        draw.font = font_name
+        draw.font_weight bold ? 'bold' : 'normal'
+        draw.pointsize = size
+        draw.gravity = Magick::NorthWestGravity
+        draw.text_antialias = false
+        draw.fill = 'black'
+        draw.undercolor = 'white'
+        draw.stroke = 'transparent'
+
+        font = {
+            name: font_name,
+            size: size,
+            bold: !!bold,
+        }
+
+        " 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ(){}[]<>`~!@#$%^&*-_=+\\|;:'\",./?".chars.each do |ch|
+
+          glyph = {
+              char: ch
+          }
+
+          char_code = ch.getbyte(0)
+
+          ch = "\\\\" if ch == "\\"
+          ch = "\\\"" if ch == "\""
+
+          img.erase!
+          draw.annotate img, 0, 0, 0, 0, ch
+
+          width = img.char_width
+          height = img.char_height
+
+          if width.nil?
+            puts "Error on char #{ch.inspect}: no width"
+          elsif height.nil?
+            puts "Error on char #{ch.inspect}: no height"
+          else
+            glyph[:width] = width
+            glyph[:height] = height
+            glyph[:data] = []
+
+            img.get_pixels(0, 0, width, height).each_with_index do |px, index|
+              x = (index % width).to_i
+              y = (index / width).to_i
+
+              glyph[:data][y] ||= []
+              glyph[:data][y][x] = px.intensity <= max_black
+            end
+
+            font[char_code] = glyph
+          end
+
+        end
+
+        Font.new(font)
+      rescue LoadError
+        nil
+      end
+    end
+
+    private
+
+    def add_glyph_helpers_to(glyph)
+      def glyph.char
+        self[:char]
+      end
+      def glyph.width
+        self[:width]
+      end
+      def glyph.height
+        self[:height]
+      end
+      def glyph.data
+        self[:data]
+      end
+      glyph
+    end
+
+  end
+end
+
+
+# Include the components of the model.
+Dir.glob(File.expand_path('../font/*.rb', __FILE__)).each do |file|
+  require file
+end