movingsign_api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0a1ad2325eb6653f274649048c8cc87521342cf
+  data.tar.gz: a6c42e582bd97653f85baf448a85db94bed5eaa9
+SHA512:
+  metadata.gz: abef5a49210a9f01bc090de1eb78d5979b0ca2e2969bf45b947309b096a3c047158754c4aee7c6f19e3876ffb752239fb6c93f4138a073f6cf92d9d1b33f93c5
+  data.tar.gz: c1e6bddf3f7a8c86e48dc5f5b1936a7f3713aa7a2099b69a69db5fa4b9720f2d8f174432106c57c863f83ae6bc5e8ac46716587b6fe06508504c6211954f0d86

data/.gitignore

@@ -0,0 +1,22 @@
+*~
+/temp.rb
+
+# Gem/Bundler Defaults
+
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+before_script:
+  - gem install bundler --version "~> 1.3"
+  - bundle install
+script: bundle exec rspec -fd

data/.yardopts

@@ -0,0 +1 @@
+- README.md CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Version History
+
+## Version 0.0.1
+
+#### Added
+
+* Write text command
+* Set date/time command
+* Software reset command
+* Hard reset command
+* Set sound command

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Eric Webb
+
+MIT License
+
+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,60 @@
+# MovingsignApi
+
+MovingSign Communication Protocol V2.1 Implementation in Ruby to control
+[compatible LED signs](http://www.signsdirect.com/Home/LED-Signs-Programmable/7x80-LED-Indoor-Brightness-Sign-Red.html).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'movingsign_api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install movingsign_api
+
+## Usage
+
+Using the MovingsignApi is straight forward.
+
+<!-- include spec/tutorials/readme_1.rb -->
+``` ruby
+require 'movingsign_api'
+
+sign = MovingsignApi::Sign.new '/dev/ttyUSB0'
+
+sign.show_text "Hello World"
+
+```
+
+There are other commands and quite a few options.  See [MovingsignApi::Sign](lib/movingsign_api/sign.rb) or [MovingsignApi::Command](lib/movingsign_api/commands/command.rb) and it's subclasses.
+
+## Versions
+
+A complete version history is in [CHANGELOG.md](CHANGELOG.md).
+
+## Todo
+
+Not all of the Movingsign protocol is implemented.  Some of missing functionality include:
+
+* Text formatting isn't supported
+* Graphics commands aren't supported
+* Some write control commands are not implemented:
+  * Set/Change password
+  * Set/Change device address
+  * Changing the text file display mode
+* Read control commands
+  * Read clock
+  * Read equipment attributes
+
+## Contributing
+
+Make a pull request and be sure to include test cases!
+
+## Other Projects
+
+* [multi_movingsign](https://github.com/webmonarch/multi_movingsign) - to drive multiple Movingsigns at the same time for an information display board

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/movingsign_api/commands/command.rb

@@ -0,0 +1,76 @@
+require 'movingsign_api/commands/internal/sender_receiver_address'
+require 'movingsign_api/commands/internal/utilities'
+
+module MovingsignApi
+  # Command class, subclassed by each MovingsignApi class
+  #
+  # When subclassing, be sure to implement {#command_code} and {#command_payload_bytes}
+  #
+  # Also see some useful subclasses: {WriteTextCommand}, {WriteControlCommand}
+  class Command
+    include Utilities
+
+    # The sender's address.  See {SenderReceiverAddress}
+    attr_accessor :sender
+    # The receiving sign's address.  See {SenderReceiverAddress}
+    attr_accessor :receiver
+
+    def sender=(val)
+      @sender = MovingsignApi::SenderReceiverAddress.parse(val)
+    end
+
+    def receiver=(val)
+      @receiver = MovingsignApi::SenderReceiverAddress.parse(val)
+    end
+
+    # Returns the command identifier string.  See specification for list of valid command codes.
+    #
+    # @return [String]
+    def command_code
+      raise MovingsignApi::NotImplementedError, "Needs to be implemented in subclass."
+    end
+
+    # Returns a byte array representing this command, appropriate for sending to the sign's serial port
+    #
+    # @return [Array<Byte>]
+    def to_bytes
+      # set defaults
+      self.sender ||= :pc
+      self.receiver ||= 1
+
+      bytes = []
+
+      bytes.concat [0x00] * 5                               # start of command
+      bytes.concat [0x01]                                   # <SOH>
+      bytes.concat self.sender.to_bytes                     # Sender Address
+      bytes.concat self.receiver.to_bytes                   # Reciver Address
+      bytes.concat [0x02]                                   # <STX>
+      bytes.concat string_to_ascii_bytes(command_code)      # Command Code
+      bytes.concat command_payload_bytes                    # command specific payload
+      bytes.concat [0x03]                                   # <ETX>
+      bytes.concat generate_checksum_bytes(bytes[10..-1])   # Checksum bytes (4)
+      bytes.concat [0x04]                                   # <EOT>
+
+      bytes
+    end
+
+    private
+
+    # Returns command specific byte array payload
+    #
+    # @return [Array<Byte>]
+    def command_payload_bytes
+      raise MovingsignApi::NotImplementedError, "Needs to be implemented in subclass."
+    end
+
+    # Returns a checksum string (4 characters) appropriate for sending to the serial port
+    #
+    # ie: '12AF' (note capitalization)
+    def generate_checksum_bytes(payload)
+      sum = payload.reduce :+
+      sum_hex = ('%04x' % sum).upcase
+
+      string_to_ascii_bytes sum_hex
+    end
+  end
+end

data/lib/movingsign_api/commands/hard_reset_command.rb

@@ -0,0 +1,16 @@
+require 'movingsign_api/commands/write_control_command'
+
+module MovingsignApi
+  # Performs a hard reset, <b>DELETING ALL DATA ON THE SIGN</b>
+  #
+  # @note The sign will restart after receiving this command
+  class HardResetCommand < WriteControlCommand
+    def subcommand_code
+      'L'
+    end
+
+    def subcommand_payload_bytes
+      []
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/align_mode.rb

@@ -0,0 +1,50 @@
+require 'movingsign_api/commands/internal/pretty_keyable'
+
+module MovingsignApi
+  # Align mode for a sign.
+  #
+  # Valid values are:
+  # * +:left+ or +'1'+
+  # * +:center+ or +'2'+
+  # * +:right+ or +'3+
+  class AlignMode
+    include PrettyKeyable
+
+    # @return [Symbol] align mode (one of {#left}, {#right}, {#center})
+    attr_accessor :key
+
+    protected
+
+    # Registers a specific align mode key and value combo
+    def self.align_mode(key, code)
+      register key, code
+    end
+
+    public
+
+    # @!group Align Mode Constants
+    # @!macro [attach] dm.align_mode
+    #   @!attribute [r] $1
+    #   Align mode +:$1+ (protocol align mode +'$2'+)
+    #   @return [Symbol] +:$1+
+    align_mode :left, '1'
+    align_mode :right, '3'
+    align_mode :center, '2'
+    # @!endgroup
+
+    # @param key [Symbol] one of the valid alignment keys
+    def initialize(key)
+      @key = key
+    end
+
+    # Parses an symbol or string into a valid {AlignMode} instance
+    # @return [AlignMode]
+    def self.parse(input)
+      if key = parse_to_key(input)
+        self.new key
+      else
+        raise InvalidInputError, "Align mode '#{input}' is invalid."
+      end
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/display_mode.rb

@@ -0,0 +1,61 @@
+require 'movingsign_api/commands/internal/pretty_keyable'
+
+module MovingsignApi
+  # Text display mode setting.
+  class DisplayMode
+    include PrettyKeyable
+
+    # @!visibility private
+    def self.display_mode(key, code)
+      register key, code
+    end
+
+    # @!group Display Mode Constants
+    # @!macro [attach] dm.display_mode
+    #   @!attribute [r] $1
+    #   Display mode $1 (protocol display mode +'$2'+)
+    #   @return [Symbol] +:$1+
+    display_mode :auto, 'A'
+    display_mode :flash, 'B'
+    display_mode :hold, 'C'
+    display_mode :interlock, 'D'
+    display_mode :rolldown, 'E'
+    display_mode :rollup, 'F'
+    display_mode :rollin, 'G'
+    display_mode :rollout, 'H'
+    display_mode :rollleft, 'I'
+    display_mode :rollright, 'J'
+    display_mode :rotate, 'K'
+    display_mode :slide, 'L'
+    display_mode :snow, 'M'
+    display_mode :sparkle, 'N'
+    display_mode :spray, 'O'
+    display_mode :starburst, 'P'
+    display_mode :switch, 'Q'
+    display_mode :twinkle, 'R'
+    display_mode :wipedown, 'S'
+    display_mode :wipeup, 'T'
+    display_mode :wipein, 'U'
+    display_mode :wipeout, 'V'
+    display_mode :wipeleft, 'W'
+    display_mode :wiperight, 'X'
+    display_mode :cyclecolor, 'Y'
+    display_mode :clock, 'Z'
+    # @!endgroup
+
+    # @return [Symbol] display mode constant (see attributes {#auto}, {#flash}, {#hold}, etc.)
+    attr_accessor :key
+
+    def initialize(mode)
+      @key = mode
+    end
+
+    def self.parse(input)
+      if key = parse_to_key(input)
+        self.new key
+      else
+        raise InvalidInputError, "Display mode '#{input}' is not valid."
+      end
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/display_pause.rb

@@ -0,0 +1,33 @@
+require 'movingsign_api/commands/internal/pretty_keyable'
+require 'movingsign_api/commands/internal/utilities'
+
+module MovingsignApi
+  # Text display pause setting (in seconds, 0 - 9)
+  class DisplayPause
+    include Utilities
+
+    # @return [Integer] seconds
+    attr_accessor :seconds
+
+    # @param seconds [Integer] Time to pause (in seconds) (0 - 9)
+    def initialize(seconds)
+      @seconds = parse_seconds(seconds)
+    end
+
+    def to_bytes
+      string_to_ascii_bytes self.seconds
+    end
+
+    private
+
+    def parse_seconds(input)
+      if input.kind_of?(String) && input.match(/\A[0-9]\z/)
+        input.to_i
+      elsif input.kind_of?(Fixnum) && input.between?(0, 9)
+        input
+      else
+        raise "Pause time '#{input}' is invalid."
+      end
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/display_speed.rb

@@ -0,0 +1,45 @@
+require 'movingsign_api/commands/internal/pretty_keyable'
+
+module MovingsignApi
+  # Text display mode speed sending
+  class DisplaySpeed
+    include PrettyKeyable
+
+    # @!visibility private
+    def self.display_speed(key, code)
+      register(key, code)
+    end
+
+    # @!group Display speed constants
+
+    # @!macro [attach] dm.display_speed
+    #   @!attribute [r] $1
+    #   Display speed +:$1+ (protocol display speed +'$2'+)
+    #   @return [Symbol] +:$1+
+    display_speed :fastest, '1'
+    display_speed :faster, '2'
+    display_speed :normal, '3'
+    display_speed :slow, '4'
+    display_speed :slower, '5'
+
+    # @!endgroup
+
+    # @return [Symbol] Display speed constant, one of {#faster}, {#normal}, {#slow}
+    attr_accessor :key
+
+    def initialize(speed)
+      @key = speed
+    end
+
+    # Parses the supplied input into a {DisplaySpeed} instance if possible
+    # @raise InvalidInputError on invalid input
+    # @return [DisplaySpeed]
+    def self.parse(input)
+      if key = parse_to_key(input)
+        self.new key
+      else
+        raise InvalidInputError, "Display speed '#{input}' is invalid."
+      end
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/file_handle.rb

@@ -0,0 +1,54 @@
+require 'movingsign_api/commands/internal/utilities'
+
+module MovingsignApi
+  # Text file handle
+  #
+  # Valid values are:
+  # * Integer - (0 - 35)
+  # * String '0' - '9', 'A' - 'Z'
+  class FileHandle
+    include Utilities
+
+    # @return [Integer] the file hander integer
+    attr_accessor :handle
+
+    def initialize(input)
+      self.handle = self.class.parse_file_handle(input)
+    end
+
+    # Returns the file handle as an integer when given a file handle string
+    def self.code_to_handle(code)
+      if code.match /[0-9]/
+        code.to_i
+      else
+        (code.unpack('C')[0] - 'A'.unpack('C')[0]) + 10
+      end
+    end
+
+    # Returns a file handle string when given a file handle integer
+    def self.handle_to_code(handle)
+      if handle.between?(0,9)
+        handle.to_s
+      else
+        (0x41 + handle - 10).chr
+      end
+    end
+
+    def to_bytes
+      string_to_ascii_bytes self.class.handle_to_code(self.handle)
+    end
+
+    private
+
+    def self.parse_file_handle(input)
+      if input.kind_of?(Fixnum) && input.between?(0, 35)
+        input
+      elsif input.kind_of?(String) && input.match(/\A[0-9A-Z]\z/)
+        code_to_handle(input)
+      else
+        raise InvalidInputError, "File handle '#{input}' is invalid."
+      end
+    end
+
+  end
+end

data/lib/movingsign_api/commands/internal/pretty_keyable.rb

@@ -0,0 +1,50 @@
+require 'movingsign_api/commands/internal/utilities'
+
+module MovingsignApi
+  module PrettyKeyable
+    include Utilities
+
+    # @!visibility private
+    def self.included(other)
+      other.class_variable_set(:@@KEYS, [])
+      other.class_variable_set(:@@CODES, [])
+
+      other.extend ClassMethods
+    end
+
+    # @!visibility private
+    def to_bytes
+      string_to_ascii_bytes self.class.codes[self.class.keys.index(self.key)]
+    end
+
+    private
+
+    module ClassMethods
+      # registers the specified key and code pair as synonymous
+      def register(key, code)
+        keys << key
+        codes << code
+
+        define_singleton_method(key) do
+          key
+        end
+      end
+
+      def parse_to_key(input)
+        if index = (keys.index(input) || codes.index(input))
+          keys[index]
+        else
+          nil
+        end
+      end
+
+      def keys
+        class_variable_get(:@@KEYS)
+      end
+
+      def codes
+        class_variable_get(:@@CODES)
+      end
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/sender_receiver_address.rb

@@ -0,0 +1,82 @@
+require 'movingsign_api/commands/internal/utilities'
+
+module MovingsignApi
+  # Represents a sender or receiver identifier for a {Command}
+  #
+  # A address can be represented as an integer between 0 and 255, or per the spec as a two character hex string: '00' - 'FF'.
+  #
+  # Valid inputs include:
+  # - Integer - +0+ - +255+
+  # - Symbol - +:broadcast+ or +:pc+
+  # - String - +'00'+ - +'FF'+
+  #
+  # Some notes:
+  #
+  # - Broadcast Address: (+:broadcast+, +0+, or +'00'+) is a broadcast identifier and shouldn't be used as a sender
+  # - PC Address: (+:pc+, +255+, or +'FF''+) is reserved to represent the "PC address" and shouldn't be used as a recipient
+  #
+  class SenderReceiverAddress
+    include Utilities
+
+    # @return [Integer] the address repsented as an integer
+    attr_accessor :identifier
+
+    # @param identifier [String] Identifier hex string, or hex string with wildcard
+    def initialize(identifier)
+      @identifier = identifier
+    end
+
+    # Parses the specified input value returning an appropriate {SenderReceiver} instance or raises.
+    #
+    # @raise [InvalidInputError] on invalid input
+    # @return [SenderReceiverAddress]
+    def self.parse(input)
+      raise MovingsignApi::InvalidInputError, "nil not allowed" if input.nil?
+
+      value = nil
+      if input.kind_of? Fixnum
+        if input.between?(0, 255)
+          value = ('%02x' % input).upcase
+        else
+          raise MovingsignApi::InvalidInputError, "Integer #{input} is out of the valid range."
+        end
+      elsif input.kind_of? Symbol
+        if input == :broadcast
+          value = '00'
+        elsif input == :pc
+          value = 'FF'
+        else
+          raise MovingsignApi::InvalidInputError, "Symbol :#{input} isn't supported"
+        end
+      elsif input.kind_of? String
+        if (value = input.upcase.match /\A[0-9,A-F\?]{2}\z/)
+          value = value[0]
+        else
+          raise MovingsignApi::InvalidInputError, "Parsing string '#{input}' isn't supported"
+        end
+      else
+        raise MovingsignApi::InvalidInputError, "Parsing '#{input.class}' isn't supported"
+      end
+
+      self.new(value)
+    end
+
+    # Returns true if this represents the special 'broadcast' address
+    def broadcast?
+      self.identifier == '00'
+    end
+
+    # Returns true if this represents the special 'pc' address
+    def pc?
+      self.identifier = 'FF'
+    end
+
+    def to_s
+      self.identifier
+    end
+
+    def to_bytes
+      string_to_ascii_bytes self.identifier
+    end
+  end
+end

data/lib/movingsign_api/commands/internal/utilities.rb

@@ -0,0 +1,8 @@
+module MovingsignApi
+  module Utilities
+  # @!visibility private
+  def string_to_ascii_bytes(input)
+      input.to_s.unpack('C*')
+    end
+  end
+end

data/lib/movingsign_api/commands/set_clock_command.rb

@@ -0,0 +1,32 @@
+require 'movingsign_api/commands/write_control_command'
+
+module MovingsignApi
+  # Sets the signs date + time
+  class SetClockCommand < WriteControlCommand
+    # @return [Time]
+    attr_accessor :datetime
+
+    def subcommand_code
+      'A'
+    end
+
+    private
+
+    def subcommand_payload_bytes
+      bytes = []
+
+      # date
+      bytes.concat string_to_ascii_bytes(self.datetime.year)
+      bytes.concat string_to_ascii_bytes('%02d' % self.datetime.month)
+      bytes.concat string_to_ascii_bytes('%02d' % self.datetime.day)
+      # time
+      bytes.concat string_to_ascii_bytes('%02d' % self.datetime.hour)
+      bytes.concat string_to_ascii_bytes('%02d' % self.datetime.min)
+      bytes.concat string_to_ascii_bytes('%02d' % self.datetime.sec)
+      # day of week
+      bytes.concat string_to_ascii_bytes(self.datetime.wday)
+
+      bytes
+    end
+  end
+end

data/lib/movingsign_api/commands/set_sound_command.rb

@@ -0,0 +1,21 @@
+require 'movingsign_api/commands/write_control_command'
+
+module MovingsignApi
+  # Sets the sound on/off property of the sign
+  class SetSoundCommand < WriteControlCommand
+    attr_accessor :on
+
+    # @param sound_on [Boolean] +true+ to turn sound on, +false+ otherwise
+    def initialize(sound_on)
+      @on = sound_on
+    end
+
+    def subcommand_code
+      'J'
+    end
+
+    def subcommand_payload_bytes
+      string_to_ascii_bytes(@on ? '1' : '0')
+    end
+  end
+end