matrixorbital-glk 0.0.1

data/COPYING

@@ -0,0 +1,57 @@
+The Matrix Orbital GLK Ruby Gem is copyrighted free software
+by Nicholas J Humfrey <njh@aelius.com>.
+You can redistribute it and/or modify it under either the terms of the GPL
+version 2 (see the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/NEWS

@@ -0,0 +1,5 @@
+= Matrix Orbital GLK Ruby Gem
+
+== MatrixOrbital-GLK Version 0.0.1 (2008-09-20)
+
+Initial Release.

data/README

@@ -0,0 +1,36 @@
+== MatrixOrbital::GLK
+
+MatrixOrbital::GLK is a ruby gem for controlling 
+the GLK serial of LCD screens made by Matrix Orbital.
+
+For more information about GLK series MatrixOrbital displays, please visit:
+http://www.matrixorbital.ca/products/glk_Series/
+
+Please note that I am not an employee and have nothing to do with MatrixOrbital,
+other than being a happy customer.
+
+RubyForge Project Page  http://rubyforge.org/projects/matrixorbital/
+
+
+== Installing
+
+You may get the latest stable version from Rubyforge. Source gems are also available.
+
+  $ gem install matrixorbital-glk
+
+
+=== Loading matrixorbital-glk gem Itself
+
+You have installed the gem already, yeah?
+
+ require 'rubygems'
+ require 'matrixorbital/glk'
+
+
+== Contact
+
+Author::     Nicholas J Humfrey
+Email::      njh@aelius.com 
+Home Page::  http://www.aelius.com/njh/
+License::    Distributes under the same terms as Ruby
+

data/Rakefile

@@ -0,0 +1,83 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+NAME = "matrixorbital-glk"
+VERS = "0.0.1"
+CLEAN.include ['pkg', 'rdoc']
+
+Gem::manage_gems
+
+spec = Gem::Specification.new do |s|
+  s.name              = NAME
+  s.version           = VERS
+  s.author            = "Nicholas J Humfrey"
+  s.email             = "njh@aelius.com"
+  s.homepage          = "http://matrixorbital.rubyforge.org"
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = "A ruby gem to interface Matrix Orbital's GLK series of LCD Screens." 
+  s.rubyforge_project = "matrixorbital" 
+  s.files             = FileList["Rakefile", "lib/matrixorbital/glk.rb", "examples/*"]
+  s.require_path      = "lib"
+  
+  # rdoc
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = ["README", "NEWS", "COPYING"]
+  
+  # Dependencies
+  s.add_dependency "rake"
+end
+
+desc "Default: package up the gem."
+task :default => :package
+
+task :build_package => [:repackage]
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = true
+  pkg.gem_spec = spec
+end
+
+desc "Run :package and install the resulting .gem"
+task :install => :package do
+  sh %{sudo gem install --local pkg/#{NAME}-#{VERS}.gem}
+end
+
+desc "Run :clean and uninstall the .gem"
+task :uninstall => :clean do
+  sh %{sudo gem uninstall #{NAME}}
+end
+
+
+
+## Testing
+#desc "Run all the specification tests"
+#Rake::TestTask.new(:spec) do |t|
+#  t.warning = true
+#  t.verbose = true
+#  t.pattern = 'spec/*_spec.rb'
+#end
+  
+desc "Check the syntax of all ruby files"
+task :check_syntax do
+  `find . -name "*.rb" |xargs -n1 ruby -c |grep -v "Syntax OK"`
+  puts "* Done"
+end
+
+## Documentation
+desc "Generate documentation for the library"
+Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = "Matrix Orbital GLK Documentation"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.main = "README"
+  rdoc.rdoc_files.include("README", "NEWS", "COPYING", "lib/matrixorbital/glk.rb")
+}
+
+desc "Upload rdoc to rubyforge"
+task :upload_rdoc => [:rdoc] do
+  sh %{/usr/bin/scp -r -p rdoc/* matrixorbital.rubyforge.org:/var/www/gforge-projects/matrixorbital}
+end

data/examples/identify.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby
+#
+# Script to display information about the connected LCD Module
+#
+# Author::    Nicholas J Humfrey  (mailto:njh@aelius.com)
+# Copyright:: Copyright (c) 2008 Nicholas J Humfrey
+# License::   Distributes under the same terms as Ruby
+#
+
+$:.unshift File.dirname(__FILE__)+'/../lib'
+
+require 'matrixorbital/glk'
+
+
+glk = MatrixOrbital::GLK.new(ARGV[0]||'/dev/ttyUSB0')
+puts "Serial Port:    #{glk.serialport}"
+puts "Baud Rate:      #{glk.baudrate}"
+puts "LCD Type:       #{glk.lcd_type}"
+puts "LCD Dimensions: #{glk.lcd_dimensions.join('x')}"
+puts "LCD Firmware:   #{glk.firmware_version}"

data/examples/load-usb-driver.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+#
+# Linux Script to load USB serial port driver for the GLK19264-7T-1U
+#
+
+sudo modprobe ftdi_sio vendor=0x1b3d product=0x0127

data/lib/matrixorbital/glk.rb

@@ -0,0 +1,470 @@
+#!/usr/bin/ruby
+#
+# A ruby gem to interface Matrix Orbital's GLK series of LCD Screens.
+#
+# Author::    Nicholas J Humfrey  (mailto:njh@aelius.com)
+# Copyright:: Copyright (c) 2008 Nicholas J Humfrey
+# License::   Distributes under the same terms as Ruby
+#
+
+module MatrixOrbital
+
+class GLK < File
+  attr_reader :serialport, :baudrate
+  
+  # Connect to an LCD screen.
+  # All of the parametes are optional.
+  # By default the LCD screen type will be detected automatically.
+  def initialize(serialport='/dev/ttyS0', baudrate=19200, manual_lcd_type=nil)
+  
+    # Does the device exist?
+    @serialport = serialport
+    unless File.exists? serialport
+      raise "Serial port '#{serialport}' does not exist."
+    end
+  
+    # Use the lcd_type given, or ask the module
+    unless manual_lcd_type.nil?
+      @lcd_type = manual_lcd_type
+    end
+
+    # Store the baudrate
+    
+    # Configure the serial port
+    # FIXME: use pure ruby
+    @baudrate = baudrate
+    system("stty -F #{serialport} raw speed #{baudrate} cs8 -ixon -echo cbreak -isig -parenb > /dev/null") or
+      raise "Failed to set parameters on the serial port."
+
+    # Now, open the serial port
+    super(serialport, "rb+")
+
+    # Disable buffering
+    self.sync = true
+    
+    # Flush the input buffer
+    
+  end
+
+  # This command sets the I2C write address of the module between 0x00 
+  # and 0xFF. The I2C write address must be an even number and the read 
+  # address is automatically set to one higher. For example if the I2 C write 
+  # address is set to 0x50, then the read address is 0x51.
+  def i2c_slave_address=(address)
+    raise "I2C slave address is out of range" if (value<0 or value>255)
+    send_command( 0x33, address )
+  end
+
+  # This command sets the lcd's RS-232 port to the specified <em>baudrate</em>.
+  # The change takes place immediately.
+  def lcd_baudrate=(lcd_baudrate)
+    case lcd_baudrate
+      when 9600 then
+        send_command( 0x39, 0xCF )
+      when 14400 then
+        send_command( 0x39, 0x8A )
+      when 19200 then
+        send_command( 0x39, 0x67 )
+      when 28800 then
+        send_command( 0x39, 0x44 )
+      when 38400 then
+        send_command( 0x39, 0x33 )
+      when 57600 then
+        send_command( 0x39, 0x22 )
+      when 76800 then
+        send_command( 0x39, 0x19 )
+      when 115200 then
+        send_command( 0x39, 0x10 )
+      else
+        raise "Invalid/unsupported baud rate: #{lcd_baudrate}"
+    end
+  end
+
+
+  # Turn flow control on or off.
+  def flow_control=(state)
+    if state
+      raise "Flow control is unsupported"
+      #  send_command( 0x3A )
+    else
+      send_command( 0x3B )
+    end
+  end
+
+  
+  # Turn the LCD backlight on/off immediately and stay on/off.
+  def backlight=(state)
+    if state
+      # FIXME: backlight hard coded to stay on permanently
+      send_command( 0x42, 0 )
+    else
+      send_command( 0x46 )
+    end
+  end
+  
+  # This command moves the text insertion point to the top left of the 
+  # display area, based on the current font metrics.
+  def cursor_home
+    send_command( 0x48 )
+  end
+
+  # This command sets the text insertion point to the [col] and [row] 
+  # specified. The insertion point is positioned using the base size of 
+  # the current font (this command does not position the insertion 
+  # point at a specific pixel).
+  #
+  # Example:
+  #
+  #  lcd.cursor_position = [10,4]
+  #
+  def cursor_position=(params)
+    col,row = params
+    send_command( 0x47, col, row )
+  end
+
+  # This command positions the insertion point at a specific pixel (X,Y), 
+  # which references the top left corner of the font insertion point.
+  #
+  # Example:
+  #
+  #  lcd.cursor_coordinate = [100,40]
+  #
+  def cursor_coordinate=(params)
+    x,y = params
+    send_command( 0x79, x, y )
+  end
+  
+  # This command sets the display's contrast to <em>value</em>, 
+  # where <em>value</em> is a value between 0 to 255. 
+  # Lower values cause 'on' elements in the display area to appear 
+  # lighter, while higher values cause 'on' elements to appear darker.
+  def contrast=(value)
+    raise "Contrast value is out of range" if (value<0 or value>255)
+    send_command( 0x50, value )
+  end
+  
+  # Like the <em>contrast=</em> method, only this command saves the 
+  # value so that it is not lost after power down.
+  def save_contrast(value)
+    raise "Contrast value is out of range" if (value<0 or value>255)
+    send_command( 0x91, value )
+  end
+  
+  # This command sets the display's brightness to <em>value</em>, 
+  # where <em>value</em> is a value between 0 to 255. 
+  def brightness=(value)
+    raise "Brightness value is out of range" if (value<0 or value>255)
+    send_command( 0x99, value )
+  end
+  
+  # Like the <em>brightness=</em> method, only this command saves the 
+  # value so that it is not lost after power down.
+  def save_brightness(brightness)
+    raise "Brightness value is out of range" if (value<0 or value>255)
+    send_command( 0x98, brightness )
+  end
+  
+  # This command enabled and disables autoscrolling.
+  # When auto scrolling is on, it causes the display to shift the entire 
+  # display's contents up to make room for a new line of text when the text 
+  # reaches the end of the scroll row defined in the font metrics (the bottom 
+  # right character position)
+  def autoscroll=(state)
+    if state
+      send_command( 0x51 )
+    else
+      send_command( 0x52 )
+    end
+  end
+
+  # This command clears any unread key presses.
+  def clear_key_buffer
+    send_command( 0x45 )
+  end
+  
+  # When auto transmit key presses is turned on all key presses are sent 
+  # immediately to the host system without the use of the <em>poll_keypad</em> 
+  # method. This is the default mode on power up. 
+  #
+  # When auto transmit key presses is turned off up to 10 key presses are 
+  # buffered until the unit is polled by the host system.
+  def auto_transmit_key_presses=(state)
+    if state
+      send_command( 0x41 )
+    else
+      send_command( 0x4F )
+    end
+  end
+  
+  # This command sets the time (in miliseconds) between key press and key read.
+  # All key types with the exception of latched piezo switches will 'bounce' 
+  # for a varying time, depending on their physical characteristics.
+  def debounce_time=(ms)
+    time = (ms.to_f / 6.554).to_i
+    raise "Debounce time is out of range" if (value<0 or value>255)
+    send_command( 0x63, value )
+  end
+  
+  # This command sets the drawing color for subsequent graphic commands 
+  # that do not have the drawing color passed as a parameter. The parameter 
+  # <em>color</em> is the value of the color where white is <em>false<em>
+  # and black <em>true<em>.
+  def drawing_color=(color)
+    send_command( 0x63, color ? 0 : 1 )
+  end
+
+  # This command clears the display and resets the text insertion position to 
+  # the top left position of the screen defined in the font metrics.
+  def clear_screen
+    send_command( 0x58 )
+  end
+
+  # This command will draw a bitmap that is located in the on board memory.
+  # The bitmap is referenced by the bitmaps reference identification number, 
+  # which is established when the bitmap is uploaded to the display module. 
+  # The bitmap will be drawn beginning at the top left, 
+  # from the specified <em>x</em>,<em>y</em> coordinates.
+  def draw_bitmap(refid, x, y)
+    send_command( 0x62, refid, x, y )
+  end
+  
+  # This command will draw a pixel at <em>x</em>, <em>y</em> using 
+  # the current drawing color.
+  def draw_pixel(x, y)
+    send_command( 0x70, x, y )
+  end
+  
+  # This command will draw a line from <em>x1</em>, <em>y1</em>
+  # to <em>x2</em>, <em>y2</em> using the current drawing color. 
+  # Lines may be drawn from any part of the display to any other part. 
+  # However, it may be important to note that the line may in-terpolate 
+  # differently right to left, or left to right. 
+  # This means that a line drawn in white from right to left may not 
+  # fully erase the same line drawn in black from left to right.
+  def draw_line(x1, y1, x2, y2)
+    send_command( 0x6C, x1, y1, x2, y2 )
+  end
+  
+  # This command will draw a line with the current drawing color from 
+  # the last line end (x2,y2) to <em>x</em>, <em>y</em>.
+  # This command uses the global drawing color.
+  def draw_line_continue(x, y)
+    send_command( 0x65, x, y )
+  end
+  
+  # This command draws a rectangular box in the specified <em>color</em>. 
+  # The top left corner is specified by <em>x1</em>, <em>y1</em> and 
+  # the bottom right corner by <em>x2</em>, <em>y2</em>.
+  def draw_rect(color, x1, y1, x2, y2)
+    send_command( 0x72, color, x1, y1, x2, y2 )
+  end
+  
+  # This command erases a single bitmap file from the LCD's internal memory.
+  def delete_bitmap(refid)
+    send_command( 0xAD, 0x01, refid )
+  end
+  
+  # This command erases a single font file from the LCD's internal memory.
+  def delete_font(refid)
+    send_command( 0xAD, 0x00, refid )
+  end
+
+  # Set the current font to the specified font refernce identifer.
+  # The font ID is es-tablished when the font is saved to the display.
+  def font=(refid)
+    send_command( 0x31, refid )
+  end
+  
+  # This command completely erases the display's non-volatile memory. It 
+  # removes all fonts, font metrics, bitmaps, and settings (current font, 
+  # cursor position, communication speed, etc.).
+  def wipe_filesystem
+    send_command( 0x21, 0x59, 0x21 )
+  end
+  
+  # This command will return the number of bytes that are 
+  # remaining in the on board memory.
+  def filesystem_space
+    send_command( 0xAF )
+  
+    #my count = getint()
+    
+    #count |= ( & 0xFF) << 0;
+    #count |= (getchar() & 0xFF) << 8;
+    #count |= (getchar() & 0xFF) << 16;
+    #count |= (getchar() & 0xFF) << 24;
+    #
+    #return count;
+  end
+  
+  # This command will return a directory of the contents of the file system.
+  # It returns an array of directory entires, where each entry is a hash.
+  def filesystem_directory
+    send_command( 0xB3 )
+  
+    #my lsb = getchar()
+    
+    #my @bytes = getbytes( 4 )
+  
+    #my count = 0;
+    #count |= (@bytes[0] & 0xFF) << 0;
+    #count |= (@bytes[1] & 0xFF) << 8;
+    #count |= (@bytes[2] & 0xFF) << 16;
+    #count |= (@bytes[3] & 0xFF) << 24;
+    
+    #return count;
+    
+    #return lsb;
+  end
+  
+  # This command draws a solid rectangle in the specified <em>color</em>. 
+  # The top left corner is specified by <em>x1</em>, <em>y1</em> and the bottom 
+  # right corner by <em>x2</em>, <em>y2</em>. Since this command involves 
+  # considerable processing overhead, we strongly recommend the use of flow 
+  # control, particularly if the command is to be repeated frequently.
+  def draw_solid_rect(color, x1, y1, x2, y2)
+    send_command( 0x78, color, x1, y1, x2, y2 )
+  end
+
+  # This command turns Off general purpose output <em>num</em>.
+  def gpo_off(num)
+     send_command( 0x56, num )
+  end
+
+  # This command turns On general purpose output <em>num</em>.
+  def gpo_on(num)
+    send_command( 0x57, num )
+  end
+  
+
+
+  # Send a raw command to the display, where <em>args<em> is an
+  # array of integer bytes to be sent to the lcd module.
+  def send_command(command, *args)
+    args.unshift(0xFE, command)
+    self.print( args.pack('C*') )
+  end
+  
+  # Send text string to display and STDOUT too
+  def puts_stdout(*args)
+    $stdout.puts(*args)
+    self.puts(*args)
+  end
+
+
+  # Turn LED number <em>num</em> off.
+  #
+  # The command is only supported on LCD modules with 
+  # on-board LEDS (such as the GLK19264-7T-1U)
+  def led_off(num)
+    gpo_base = led_gpo_base(num)
+    gpo_on( gpo_base )
+    gpo_on( gpo_base+1 )
+  end
+  
+  # Turn LED number <em>num</em> on - Red.
+  #
+  # The command is only supported on LCD modules with 
+  # on-board LEDS (such as the GLK19264-7T-1U)
+  def led_red(num)
+    gpo_base = led_gpo_base(num)
+    gpo_off( gpo_base )
+    gpo_on( gpo_base+1 )
+  end
+  
+  # Turn LED number <em>num</em> on - Green.
+  #
+  # The command is only supported on LCD modules with 
+  # on-board LEDS (such as the GLK19264-7T-1U)
+  def led_green(num)
+    gpo_base = led_gpo_base(num)
+    gpo_on( gpo_base )
+    gpo_off( gpo_base+1 )
+  end
+  
+  # Turn LED number <em>num</em> on - Yellow.
+  #
+  # The command is only supported on LCD modules with 
+  # on-board LEDS (such as the GLK19264-7T-1U)
+  def led_yellow(num)
+    gpo_base = led_gpo_base(num)
+    gpo_off( gpo_base )
+    gpo_off( gpo_base+1 )
+  end
+  
+
+  # Returns the firmware version of the LCD module that you are 
+  # communicating with as a dotted integer (for example '5.4').
+  def firmware_version
+    return @firmware_version unless @firmware_version.nil?
+
+    # Request firmware version number
+    send_command( 0x36 )
+
+    # Read back one byte
+    value = getc
+    major = (value & 0xF0) >> 4
+    minor = value & 0x0F
+    return @firmware_version = "#{major}.#{minor}"
+  end
+
+
+  TYPEMAP = {
+    0x10 => 'GLC12232',
+    0x13 => 'GLC24064',
+    0x15 => 'GLK24064-25',
+    0x22 => 'GLK12232-25',
+    0x24 => 'GLK12232-25-SM',
+    0x26 => 'GLK24064-16-1U',
+    0x27 => 'GLK19264-7T-1U',
+    0x28 => 'GLK12232-16',
+    0x29 => 'GLK12232-16-SM',
+    0x72 => 'GLK240128-25'
+  }
+
+  # Return the Product Idenfier for the LCD module (for example 'GLK24064-25').
+  # This can be determined automatically or passed as a parameter to new().
+  def lcd_type
+    return @lcd_type unless @lcd_type.nil?
+
+    # Request LCD module type
+    send_command( 0x37 )
+
+    # Read back one byte
+    type = getc
+    if TYPEMAP.has_key?(type)
+      @lcd_type = TYPEMAP[type]
+    else
+      @lcd_type = "Unknown-#{type}"
+    end
+  end   
+  
+  # Returns the dimensions (in pixels) of the LCD module you are talking 
+  # to as an array, width followed by height.
+  def lcd_dimensions
+    # Parse the LCD type to work out the dimensions
+    if (lcd_type =~ /^(GLC|GLK)(\d{3})(\d{2})-|$/)
+      return [$2,$3]
+    else
+      raise "Can't get screen dimensions: unknown LCD module"
+    end
+  end
+
+private
+
+  # Private method to get the base GPO bit for specified LED number
+  def led_gpo_base(num)
+    case num.to_i
+      when 0
+        1
+      when 1
+        3
+      when 2
+        5
+      else
+        raise 'Invalid LED number'
+    end
+  end
+
+end # GLK
+end # MatrixOrbital

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: matrixorbital-glk
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Nicholas J Humfrey
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-20 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: njh@aelius.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- NEWS
+- COPYING
+files: 
+- Rakefile
+- lib/matrixorbital/glk.rb
+- examples/identify.rb
+- examples/load-usb-driver.sh
+- README
+- NEWS
+- COPYING
+has_rdoc: true
+homepage: http://matrixorbital.rubyforge.org
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: matrixorbital
+rubygems_version: 0.9.5
+signing_key: 
+specification_version: 2
+summary: A ruby gem to interface Matrix Orbital's GLK series of LCD Screens.
+test_files: []
+