nickel-silver-server 0.0.1

data/History.txt

@@ -0,0 +1,6 @@
+== 0.0.1 2008-03-18
+
+* 3 major enhancements:
+  * Initial release
+  * Complete LocoNetOverTCP version 1 implementation
+  * Support for the LocoBuffer-USB

data/License.txt

@@ -0,0 +1,3 @@
+Nickel-Silver is distributed under the same terms as Ruby.
+
+Copyright (c) 2008 Tobin Richard

data/Manifest.txt

@@ -0,0 +1,22 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/nickel-silver-server.rb
+lib/nickel-silver-server/version.rb
+lib/LocoBufferUSB.rb
+lib/LocoNetServer.rb
+log/debug.log
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+test/test_helper.rb
+test/test_nickel-silver-server.rb
+

data/README.txt

@@ -0,0 +1,43 @@
+= nickel-silver-server
+
+* http://rubyforge.org/projects/nickel-silver/
+
+== DESCRIPTION:
+
+Ruby, literally, on rails! A Ruby implementation of the LocoNetOverTCP protocol allowing remote clients to connect to Digitrax based model railway layouts. Also included are a number of tools for LocoNet logging and locomotive control.
+
+== FEATURES/PROBLEMS:
+
+* Complete support for LocoNetOverTCP version 1
+
+== SYNOPSIS:
+
+  require 'rubygems'
+	require 'nickel-silver-server'
+  
+	# connect to a LocoBufferUSB on the virtual serial port /dev/tty.serialport
+	interface = LocoBufferUSB.new( '/dev/tty.serialport' )
+  
+	# create a server using the default port (i.e. 5626, 'loco' spelt on a phone keypad)
+	# using our freshly connected LocoBuffer-USB
+	server = LocoNetServer.new( interface )
+  
+	# start the server
+	server.start
+  
+	# wait for the server to stop before exiting
+	server.join
+
+== REQUIREMENTS:
+
+* ruby-serialport is needed to connect with LocoBuffer-USB hardware http://rubyforge.org/projects/ruby-serialport/ 
+
+== INSTALL:
+
+* sudo gem install nickel-silver-server
+
+== LICENSE:
+
+Nickel Silver is distributed under the same terms as Ruby.
+
+Copyright (c) 2008 Tobin Richard

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,70 @@
+require 'nickel-silver-server/version'
+
+AUTHOR = 'Tobin Richard'  # can also be an array of Authors
+EMAIL = "tobin.richard@gmail.com"
+DESCRIPTION = "A Ruby implementation of a LocoNetOverTCP server."
+GEM_NAME = 'nickel-silver-server' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'nickel-silver' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = NickelSilver::Server::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'nickel-silver-server documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'nickel-silver-server'

data/lib/LocoBufferUSB.rb

@@ -0,0 +1,63 @@
+# Explicitly call Kernel#require because the serialport library explodes with rubygem's implementation.
+Kernel.require 'serialport'
+
+module NickelSilver
+  module Server
+    module Interface
+      
+      # A simple IO wrapper for the LocoBuffer-USB.
+      #
+      # See the documentation for LocoNetServer for details on how this should be used.
+      #
+      # = Stand-alone usage
+      #   lb = LocoBufferUSB.new( '/dev/ttys0' )
+      #   
+      #   lb.run
+      #   
+      #   loop do
+      #     sleep(1)
+      #     
+      #     until lb.input_buffer.empty? do
+      #       lb.io_mutex.synchronize do
+      #         puts "Got byte #{ format( '%02x', lb.input_buffer.shift ) } from LocoNet"
+      #       end
+      #     end
+      #   end
+      #
+      class LocoBufferUSB
+        attr_accessor :input_buffer, :output_buffer, :io_mutex
+  
+        # Connect to a LocoBuffer-USB using the specified serial port.
+        def initialize( serial_port )
+          @locobuffer = SerialPort.new( serial_port, 57_600 )
+    
+          # these may be modified at any time by the server
+          @input_buffer = []
+          @output_buffer = []
+    
+          # only make changes when locked using @io_mutex
+          @io_mutex = @iomutex = Mutex.new
+        end
+  
+        # Handle packets moving in and out of the LocoBuffer-USB.
+        def run
+          loop do
+            while select( [@locobuffer], nil, nil, 0 ) do
+              @io_mutex.synchronize do
+                @input_buffer << @locobuffer.getc
+              end
+            end
+  
+            # puts "outbuf length = #{output_buffer.length}"
+            until output_buffer.empty? do
+              @io_mutex.synchronize do
+                @locobuffer.putc( @output_buffer.shift )
+              end
+            end
+          end
+        end
+      end
+    
+    end
+  end
+end

data/lib/LocoNetServer.rb

@@ -0,0 +1,247 @@
+require 'gserver'
+require 'stringio'
+
+module NickelSilver
+  module Server
+    
+    # = Summary
+    # An implementation of the LoconetOverTcp protocol version 1 for use with the
+    # LocoBuffer-USB awailable from RR-CirKits (http://www.rr-cirkits.com).
+    #
+    # This simple protocol allows clients connected via TCP to access a LocoNet netowrk.
+    # Both sending and receiving of packets is supported.
+    #
+    # Author::    Tobin Richard (mailto:tobin.richard@gmail.com)
+    # Copyright:: Copyright (c) 2008
+    # License::   Distributes under the same terms as Ruby
+    #
+    # = Usage
+    # The following creates a server listening on the default port of 5626 ('loco' spelt on a phone keypad)
+    # using a LocoBuffer-USB connected to the serial port <tt>tty.serialport</tt>.
+    #
+    #   require 'rubygems'
+    #   require 'nickel-silver-server'
+    #   
+    #   # connect to a LocoBufferUSB on the virtual serial port /dev/tty.serialport
+    #   interface = LocoBufferUSB.new( '/dev/tty.serialport' )
+    #   
+    #   # create a server using the default port (i.e. 5626, 'loco' spelt on a phone keypad)
+    #   # using our freshly connected LocoBuffer-USB
+    #   server = LocoNetServer.new( interface )
+    # 
+    #   # start the server
+    #   server.start
+    # 
+    #   # wait for the server to stop before exiting
+    #   server.join
+    #
+    # If you want logging of connections, disconnections and other activity then
+    # add <tt>server.audit = true</tt> before <tt>server.start</tt>.
+    # 
+    # = Protocol
+    # For full details of the LoconetOverTcp protocol see
+    # http://loconetovertcp.sourceforge.net/Protocol/LoconetOverTcp.html
+    #
+    # Information is exchanged between the server and clients as plain ASCII strings. The server
+    # ignores invalid commands and empty lines.
+    #
+    # Clients may send the following commands to the server, as per the protocol specification:
+    #
+    # SEND Send a packet out over the LocoNet connection. The packet is not checked for correctness
+    # before transmission. E.g. <tt>SEND a0 2f 00 70</tt>
+    # 
+    # The server may send the following information to clients, as per the protocol specification:
+    #
+    # VERSION: Sent to new clients immediately after they connect. The string which follows
+    # describes the LocoNetOverTcp server's name and version.
+    # E.g. <tt>VERSION NickelSilver version 0.1</tt>
+    #
+    # RECEIVE: Sent when a packet is received by the LocoBuffer-USB. E.g. <tt>RECEIVE 83 7c</tt>
+    #
+    # SENT: Sent to clients after an attempt has been made to process a SEND command. First
+    # parameter is always <tt>OK</tt> or <tt>ERROR</tt> and may be followed by a string describing
+    # details fo the transmission. E.g. <tt>SENT ERROR Could not communicate with LocoBuffer-USB</tt>
+    #
+    class LocoNetServer < GServer
+      
+      # Creates a new LocoNetOverTCP server.
+      # 
+      # You must supply an interface object and you may specify a port if the default of 5626
+      # does not suit your environment.
+      #
+      # See the full documentation for this class for an exmaple using the LocoBuffer-USB.
+      def initialize( interface, tcp_port=5626, *args )
+        # we maintain a list of clients to be notified of LocoNet packets
+        @clients = []
+    
+        # we will require access to the interface's buffers
+        @interface = interface
+  
+        # start the interface buffering in another thread
+        Thread.new { @interface.run }
+  
+        # process incoming packets in another thread
+        Thread.new { process_packets }
+    
+        super( tcp_port, *args )
+      end
+  
+      private
+  
+      # Serve a client.
+      #
+      # The client is registered with the server so it may be notified of LocoNet packets.
+      #
+      # Only this method may read from clients.
+      def serve( io )
+        # create a mutex to control access to this clients IO
+        semaphore = Mutex.new
+    
+        # store the client and mutex for notification of LocoNet packets
+        client = { :io => io, :mutex => semaphore }
+        @clients << client
+    
+        # ouput VERSION to client
+        semaphore.synchronize do
+          io.puts( 'VERSION NickelSilver version 0.1' )
+        end
+    
+        # read, execute loop
+        loop do
+          # get any pending input
+          # if nil is returned then the client must have disconnected
+          line = io.gets
+          break if line.nil?
+      
+          command = line.split( ' ' )
+      
+          # LocoNet over TCP Version 1 only supports a single command, SEND
+          # ignore all other commands/lines
+          if command[0] == 'SEND'
+            # convert command into bytes
+            packet = command[ 1..command.length ]
+            packet.map! { |b| b.to_i(16) }
+        
+            # send packet to loconet
+            begin
+              send_packet( packet )
+              semaphore.synchronize do
+                io.puts( 'SENT OK' )
+              end
+            rescue
+              semaphore.synchronize do
+                io.puts( 'SENT ERROR' )
+              end
+            end          
+          end
+        end
+    
+        # client has disconnected, remove it from the notification list
+        @clients.delete( client )
+      end
+  
+      # Send a packet to the LocoBuffer-USB connection.
+      #
+      # Does not check the packet format, checksum or anything else.
+      #
+      # Waits for the the packet sent to be RECEIVE'd back from the LocoBuffer
+      def send_packet( packet )
+        # create a pipe and mutex and add ourselves as a fake client so we can
+        # check the packet is RECEIVE'd back by the LocoBuffer-USB
+        reader, writer = IO.pipe
+        client = { :io => writer , :mutex => Mutex.new }
+        @clients << client
+    
+        # output the bytes
+        @interface.io_mutex.synchronize do
+          @interface.output_buffer += packet
+        end
+    
+        # keep waiting for packets either for 2 seconds passes or we get a match
+        start = Time.now
+        matched = false
+        until Time.now - start > 2.0 || matched
+          # break it up and remove the leading RECEIVE
+          if select( [reader], nil, nil, 0 )
+            in_packet = reader.gets().split( ' ' )
+            in_packet.delete_at( 0 )
+            in_packet.map! { |b| b.to_i(16) }
+        
+            # check for a match
+            matched = in_packet == packet
+          end
+        end
+    
+        # remove the fake client from the notification list
+        @clients.delete( client )
+    
+        # raise an exception if the packet didn't send
+        raise "Did not receive echo from LocoBuffer" unless matched
+      end
+  
+      # Determine if a packet is complete. That is, determine if it has the correct
+      # length as determined by its opcode (and possibly its second byte)
+      def packet_complete?( packet )
+        # if less than two bytes packet can't be finished
+        return false if packet.length < 2
+    
+        # Determine correct length. See LocoNet Personal Use Edition 1.0 for
+        # information on packet lengths.
+        case 0b0110_0000 & packet[0]
+          when 0b0000_0000 # two byte packet
+            packet.length == 2
+          when 0b0010_0000 # four byte packet
+            packet.length == 4
+          when 0b0100_0000 # six byte packet
+            packet.length == 6
+          when 0b0110_0000 # lower seven bits of second byte are message length
+            packet.length == packet[1]
+        end
+      end
+  
+  
+      # Process incoming packets and notficy clients.
+      def process_packets
+        packet = []
+        loop do
+          # wait for data in the buffer
+          # sleep long enough to avoid pegging the CPU 
+          while @interface.input_buffer.empty?
+            sleep(0.1)
+          end
+      
+          # get the next byte out of the buffer
+          byte = 0
+          @interface.io_mutex.synchronize do
+            byte = @interface.input_buffer.shift
+          end
+                  
+          # if this is the first byte it must have its msb set
+          packet << byte unless packet.empty? && byte < 0b1000_0000
+      
+          # if we somehow got another opcode before completing a packet
+          # then dump the current broken packet and start over
+          packet = [byte] if byte >= 0b1000_0000
+      
+          # notify clients if the packet is complete
+          if packet_complete?( packet )
+            notify_clients( packet )
+        
+            # reset cuurent packet
+            packet = []
+          end
+        end
+      end
+  
+      # Notify all clients of a received packet.
+      def notify_clients( packet )
+        @clients.each do |client|
+          client[:mutex].synchronize do
+            client[:io].puts( 'RECEIVE ' + packet.map{ |b| format( '%02x', b ) }.join( ' ' ) )
+          end
+        end
+      end
+    end
+    
+  end
+end

data/lib/nickel-silver-server/version.rb

@@ -0,0 +1,11 @@
+module NickelSilver #:nodoc:
+  module Server #:nodoc:
+    module VERSION #:nodoc:
+      MAJOR = 0
+      MINOR = 0
+      TINY  = 1
+
+      STRING = [MAJOR, MINOR, TINY].join('.')
+    end
+  end
+end

data/lib/nickel-silver-server.rb

@@ -0,0 +1,13 @@
+$:.unshift File.dirname(__FILE__)
+
+module NickelSilver
+  module Server
+    # nothing here yet
+    # all the action is in LocoNetServer.rb
+    
+    module Interface
+      # nothing here yet
+      # all the action is in LocoBufferUSB.rb
+    end
+  end
+end

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/script/txt2html

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+begin
+  require 'newgem'
+rescue LoadError
+  puts "\n\nGenerating the website requires the newgem RubyGem"
+  puts "Install: gem install newgem\n\n"
+  exit(1)
+end
+require 'redcloth'
+require 'syntax/convertors/html'
+require 'erb'
+require File.dirname(__FILE__) + '/../lib/nickel-silver-server/version.rb'
+
+version  = Nickel-silver-server::VERSION::STRING
+download = 'http://rubyforge.org/projects/nickel-silver-server'
+
+class Fixnum
+  def ordinal
+    # teens
+    return 'th' if (10..19).include?(self % 100)
+    # others
+    case self % 10
+    when 1: return 'st'
+    when 2: return 'nd'
+    when 3: return 'rd'
+    else    return 'th'
+    end
+  end
+end
+
+class Time
+  def pretty
+    return "#{mday}#{mday.ordinal} #{strftime('%B')} #{year}"
+  end
+end
+
+def convert_syntax(syntax, source)
+  return Syntax::Convertors::HTML.for_syntax(syntax).convert(source).gsub(%r!^<pre>|</pre>$!,'')
+end
+
+if ARGV.length >= 1
+  src, template = ARGV
+  template ||= File.join(File.dirname(__FILE__), '/../website/template.rhtml')
+  
+else
+  puts("Usage: #{File.split($0).last} source.txt [template.rhtml] > output.html")
+  exit!
+end
+
+template = ERB.new(File.open(template).read)
+
+title = nil
+body = nil
+File.open(src) do |fsrc|
+  title_text = fsrc.readline
+  body_text = fsrc.read
+  syntax_items = []
+  body_text.gsub!(%r!<(pre|code)[^>]*?syntax=['"]([^'"]+)[^>]*>(.*?)</\1>!m){
+    ident = syntax_items.length
+    element, syntax, source = $1, $2, $3
+    syntax_items << "<#{element} class='syntax'>#{convert_syntax(syntax, source)}</#{element}>"
+    "syntax-temp-#{ident}"
+  }
+  title = RedCloth.new(title_text).to_html.gsub(%r!<.*?>!,'').strip
+  body = RedCloth.new(body_text).to_html
+  body.gsub!(%r!(?:<pre><code>)?syntax-temp-(\d+)(?:</code></pre>)?!){ syntax_items[$1.to_i] }
+end
+stat = File.stat(src)
+created = stat.ctime
+modified = stat.mtime
+
+$stdout << template.result(binding)