train-serial 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 192c2f9e6fa2af8ac0c3aede2f018333bbb13cf623258aebde8e19fe311ac836
+  data.tar.gz: 6506c0c27a00f789a20e40ab6cb73e2fbd14b0bae667e61eafe2b51fb4eeab11
+SHA512:
+  metadata.gz: e223acc177c1a39595cf1f09ea301293509e1884cf10c0b08004172fb8034695f2c603a096f0e799286ed3da4f79490fb116eba6fe91ed7f749200c90520cc63
+  data.tar.gz: 1fbb7448ef03448ad839ffe314985116cb54ee49ca70abd8d4c238fa1f7705f7b7d592d85e8dd4843aa8e1b03ba44a71a6a14a0625aebac2408c7a838c972b38

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "pry"
+  gem "bundler"
+  gem "rake"
+  gem "chefstyle"
+end

data/README.md

@@ -0,0 +1,59 @@
+# train-serial - Train Plugin for connecting to serial interfaces
+
+This plugin allows applications that rely on Train to communicate with devices
+connected over serial interfaces. This could be the console port of network gear
+or embedded systems.
+
+## Installation
+
+You will have to build this gem yourself to install it as it is not yet on
+Rubygems.Org. For this there is a rake task which makes this a one-liner:
+
+```bash
+rake install:local
+```
+
+## Transport parameters
+
+| Option           | Explanation                  | Default          |
+| ---------------- | ---------------------------- | ---------------- |
+| `device`         | Device to connect to         | `/dev/ttyUSB0`   |
+| `baud`           | Baud rate                    | `9600`           |
+| `data_bits`      | Data Bits for connection     | `8`              |
+| `parity`         | Parity (:none, :even, :odd)  | `:none`          |
+| `stop_bits`      | Stop Bits for connection     | `1`              |
+| `buffer_size`    | Number of bytes per read     | `1024`           |
+| `buffer_wait`    | Wait between reads           | `250`            |
+| `buffer_retries` | Retries until stopping reads | `3`              |
+| `setup`          | Commands to issue on open    |                  |
+| `teardown`       | Commands to issue on close   |                  |
+| `raw_output`     | Suppress stdout processing   | `false`          |
+| `error_pattern`  | Regex to match error lines   | `ERROR.*`        |
+| `prompt_pattern` | Regex to match device prompt | `[-a-zA-Z0-9]+(?:\((?:config\|config-[a-z]+\|vlan)\))?[#>]\s*$` |
+
+## Example use
+
+This will work for some Cisco devices on /dev/ttyUSB0:
+```ruby
+require 'train'
+train  = Train.create('serial', {
+            device:   '/dev/ttyUSB0',
+            setup:    %Q[
+              enable
+              #{ENV['ENABLE_PASSWORD']}
+              terminal pager 0
+            ],
+            teardown: "disable",
+            logger:   Logger.new($stdout, level: :info)
+         })
+conn   = train.connection
+result = conn.run_command("show version\n")
+conn.close
+```
+
+## Useful Setup/Teardown Patterns
+
+| Device         | Setup                                                       | Teardown  |
+| -------------- | ----------------------------------------------------------- | --------- |
+| Cisco Catalyst | `enable\nterminal length 0\n`                               | `disable` |
+| Cisco ASA      | `enable\n#{ENV['ENABLE_PASSWORD']}\nterminal pager 0\n`     | `disable` |

data/lib/train-serial.rb

@@ -0,0 +1,7 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require "train-serial/version"
+
+require "train-serial/transport"
+require "train-serial/connection"

data/lib/train-serial/connection.rb

@@ -0,0 +1,132 @@
+require "rubyserial"
+require "train"
+
+module TrainPlugins
+  module Serial
+    class Connection < Train::Plugins::Transport::BaseConnection
+
+      def initialize(options)
+        super(options)
+      end
+
+      def close
+        return if @session.nil?
+
+        unless @options[:teardown].empty?
+          logger.debug format("[Serial] Sending teardown command to %s", @options[:device])
+          execute_on_channel(@options[:teardown])
+        end
+
+        logger.info format("[Serial] Closed connection %s", @options[:device])
+        session.close
+      ensure
+        @session = nil
+      end
+
+      def uri
+        "serial://#{@options[:port]}/#{@options[:baud]}"
+      end
+
+      def run_command_via_connection(cmd, &data_handler)
+        reset_session if session.closed?
+
+        logger.debug format("[Serial] Sending command to %s", @options[:device])
+        exit_status, stdout, stderr = execute_on_channel(cmd, &data_handler)
+
+        CommandResult.new(stdout, stderr, exit_status)
+      end
+
+      def execute_on_channel(cmd, &data_handler)
+        stdout = ""
+        stderr = ""
+        exit_status = 0
+
+        if @options[:debug_serial]
+          logger.debug "[Serial] => #{cmd}\n"
+        end
+
+        session.write(cmd + "\n")
+
+        retries = 0
+        loop do
+          chunk = session.read(@options[:buffer_size])
+          if chunk.empty?
+            if @options[:debug_serial]
+              logger.debug format("[Serial] Buffering on %s (attempt %d/%d, %d bytes received)", @options[:device], retries + 1, @options[:buffer_retries], stdout.size)
+            end
+            retries += 1
+            sleep @options[:buffer_wait] / 1000.0
+          else
+            retries = 0
+          end
+          break if retries >= @options[:buffer_retries]
+
+          stdout << chunk
+        end
+
+        # Remove \r in linebreaks
+        stdout.delete!("\r")
+
+        if @options[:debug_serial]
+          logger.debug "[Serial] <= '#{stdout}'"
+        end
+
+        # Extract command output only (no leading/trailing prompts)
+        unless @options[:raw_output]
+          stdout = stdout.match(/#{Regexp.quote(cmd.strip)}\n(.*?)\n#{@options[:prompt_pattern]}/m)&.captures&.first
+        end
+        stdout = "" if stdout.nil?
+
+        # Simulate exit code and stderr
+        errors = stdout.match(/^(#{@options[:error_pattern]})/)
+        if errors
+          exit_status = 1
+          stderr = errors.captures.first
+          stdout.gsub!(/^#{@options[:error_pattern]}/, "")
+        end
+
+        [exit_status, stdout, stderr]
+      end
+
+      def session(retry_options = {})
+        @session ||= create_session
+      end
+
+      def create_session
+        logger.info format("[Serial] Opening connection %s (%s)", @options[:device], readable_config)
+        @session = ::Serial.new(
+          @options[:device],
+          @options[:baud],
+          @options[:data_bits],
+          @options[:parity],
+          @options[:stop_bits]
+        )
+
+        unless @options[:setup].empty?
+          logger.debug format("[Serial] Sending setup command to %s", @options[:device])
+
+          execute_on_channel(@options[:setup])
+        end
+
+        @session
+      end
+
+      def reset_session
+        session.close unless session.nil?
+        @session = nil
+      end
+
+      def readable_config
+        parity = "N"
+        parity = "E" if @options[:parity] == :even
+        parity = "O" if @options[:parity] == :odd
+
+        format("%d %d%s%d",
+          @options[:baud],
+          @options[:data_bits],
+          parity,
+          @options[:stop_bits])
+      end
+    end
+  end
+end

data/lib/train-serial/transport.rb

@@ -0,0 +1,32 @@
+require "train-serial/connection"
+
+module TrainPlugins
+  module Serial
+    class Transport < Train.plugin(1)
+      name "serial"
+
+      option :device,         default: "/dev/ttyUSB0"
+      option :baud,           default: 9600
+      option :data_bits,      default: 8
+      option :parity,         default: :none
+      option :stop_bits,      default: 1
+
+      option :buffer_size,    default: 1024
+      option :buffer_wait,    default: 250
+      option :buffer_retries, default: 3
+
+      option :setup,          default: ""
+      option :teardown,       default: ""
+      option :error_pattern,  default: "ERROR: .*$"
+      option :raw_output,     default: false
+      option :prompt_pattern, default: "[-a-zA-Z0-9]+(?:\((?:config|config-[a-z]+|vlan)\))?[#>]\s*$"
+
+      # Non documented options for development
+      option :debug_serial,   default: false
+
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::Serial::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-serial/version.rb

@@ -0,0 +1,5 @@
+module TrainPlugins
+  module Serial
+    VERSION = "0.2.0".freeze
+  end
+end

data/train-serial.gemspec

@@ -0,0 +1,24 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "train-serial/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "train-serial"
+  spec.version       = TrainPlugins::Serial::VERSION
+  spec.authors       = ["Thomas Heinen"]
+  spec.email         = ["theinen@tecracer.de"]
+  spec.summary       = "Train Transport for serial/USB interfaces"
+  spec.description   = "Allows applications using Train to speak to serial interaces, like console ports"
+  spec.homepage      = "https://github.com/tecracer_theinen/train-serial"
+  spec.license       = "Apache-2.0"
+
+  spec.files = %w{
+    README.md train-serial.gemspec Gemfile
+  } + Dir.glob(
+    "lib/**/*", File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "train", "~> 2.0"
+  spec.add_dependency "rubyserial", "~> 0.6"
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: train-serial
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Thomas Heinen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubyserial
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Allows applications using Train to speak to serial interaces, like console
+  ports
+email:
+- theinen@tecracer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-serial.rb
+- lib/train-serial/connection.rb
+- lib/train-serial/transport.rb
+- lib/train-serial/version.rb
+- train-serial.gemspec
+homepage: https://github.com/tecracer_theinen/train-serial
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Train Transport for serial/USB interfaces
+test_files: []