kiss-tnc 2.1.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ae672ec1ac60f99d3a1f00f8dcd50ab5c1d038a0dd3e5ee4bb2b4daecf2c43
-  data.tar.gz: de6a210464d037b0e4b3abb13d2b965a1dd29d811272aae626eb2ee0a39943c7
+  metadata.gz: 61dbec4bf66f1db239d96585ba818fb83bb42f657c24cd01dfa51c6df0ced59d
+  data.tar.gz: 3f3ee940d016ba7c7f138cf0f9decc38d5f56b4506d94c51aae78aa60df27add
 SHA512:
-  metadata.gz: 0ccc9c74f19bc05acb707d8410d2ec2eaafb1ed9c5fd33ae5af9182e7549f899a3e7e2b71f4f995cfcb4dca799c77ee80f664f2b07c30b6b6aa539cef6230042
-  data.tar.gz: cacc2a22ac9dcce2989f466402b370077660bca521deb70344716e0c26d399287534f0299c4cb3e4a32c115ca473d91a3dc3968cb15994843e81a67de1ef2df1
+  metadata.gz: 99031072302ad853d9129aab307df24246adc382fb6b87f8c246d412fa2e49973bbba4c69df783040418dbfcc5accb7a85e3157c06b98811b986fd500e780afc
+  data.tar.gz: d9250c3e5708faa3e2a71336e008111f8b600e31d67e7ab6e211f54de2c6733a0c6fc70562139c940fb307b24e5d727cde5a226d6a4fc5cbd2d837afc01df6de

data/.gitignore

@@ -6,3 +6,4 @@ Gemfile.lock
 .idea/
 *.gem
 /public/
+/vendor/

data/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
+## 3.0.0
+* Moved all elements of AX.25 out into its own library (https://git.qoto.org/digipex/ax25).
+* No longer backwards compatible with older versions.
+
 ## 2.1.3
 
-* Had to revert some of the changes fromt he last release... KissAbstract now uses include again and kind_of should now work (unit test added to confirm).
+* Had to revert some of the changes from the last release... KissAbstract now uses include again and kind_of should now work (unit test added to confirm).
 
 ## 2.1.2
 

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/kiss-tnc.svg)](https://badge.fury.io/rb/kiss-tnc)
+
 # Kiss
 
 Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/apex`. To experiment with that code, run `bin/console` for an interactive prompt.
@@ -20,17 +22,18 @@ Or install it yourself as:
 
     $ gem install kiss-tnc
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+To run tests do the following:
+
+```bash
+bundle exec rspec
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Syncleus/kiss-tnc
-

data/kiss-tnc.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
     spec.version = Kiss::VERSION
     spec.licenses = ['Apache-2.0']
     spec.authors = ['Jeffrey Phillips Freeman']
-    spec.email = ['jeffrey.freeman@syncleus.com']
+    spec.email = ['the@jeffreyfreeman.me']
 
     spec.summary = %q{Library for KISS communication with TNCs.}
     spec.description = %q{Ruby library for KISS communication with Terminal Node Controllers.}
@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
     spec.files = `git ls-files -z`.split("\x0").reject do |f|
         f.match(%r{^(test|spec|features)/})
     end
-    spec.bindir = 'exe'
+    spec.bindir = 'bin'
     spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
     spec.require_paths = ['lib']
 

data/lib/kiss/app_info.rb

@@ -1,3 +1,3 @@
 module Kiss
-    VERSION = "2.1.3"
+    VERSION = "3.0.0"
 end

data/lib/kiss/kiss.rb

@@ -4,6 +4,101 @@ module Kiss
   module Kiss
     include Abstractify::Abstract
 
-    abstract :write_interface, :read_interface, :connect, :close
+    abstract :write_interface, :read_interface, :connect, :close, :read_datagram, :write_generic_command, :write_datagram, :write_tx_delay, :write_persistence, :write_slot_time, :write_tx_tail, :write_full_duplex, :write_set_hardware, :write_exit_kiss_mode
+
+    ##
+    # Reads raw data as a byte array off the underlying stream. This data is
+    # before escapaing, or extracting from the frame.
+    protected
+    def read_interface(*args, **kwargs)
+    end
+
+    ##
+    # Writes raw bytes to the underlying stream. The bytes should already begin
+    # escaped and framed by this point.
+    protected
+    def write_interface(data, *args, **kwargs)
+    end
+
+    ##
+    # Prepares the underlying connection for reading and writing. What this
+    # means depends on the underlying implementation. It may do nothing if
+    # there are no initialization steps. Otherwise it will initiate the
+    # connection to the TNC and send the initial data needed to get it to
+    # enter KISS mode.
+    public
+    def connect(mode_init=nil, *args, **kwargs)
+    end
+
+    ##
+    # Closes the underlying connection and frees up any relevant resources.
+    # After the connection is closed read and write opperations will usually
+    # fail.
+    public
+    def close(*args, **kwargs)
+    end
+
+    ##
+    # Read and return the next datagram waiting in the buffer. Nil if there
+    # is no datagram waiting.
+    public
+    def read_datagram(*args, **kwargs)
+    end
+
+    ##
+    # This method sends any command to the underlying KISS device. All
+    # outgoing calls, methods with write_*, ultimately calls this method
+    # as the underlying call to KISS.
+    public
+    def write_generic_command(command, port, value, *args, **kwargs)
+    end
+
+    ##
+    # This command nibble should be set anytime a datagram is being sent for transmission.
+    public
+    def write_datagram(packet_data, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # The amount of time to wait between keying the transmitter and beginning to send data (in 10 ms units).
+    public
+    def write_tx_delay(tx_delay, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # The persistence parameter. Persistence=Data*256-1. Used for CSMA.
+    public
+    def write_persistence(persistence, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # Slot time in 10 ms units. Used for CSMA.
+    public
+    def write_slot_time(slot_time, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # The length of time to keep the transmitter keyed after sending the data (in 10 ms units).
+    public
+    def write_tx_tail(tx_tail, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # True to turn on full_duplex, false to turn it off.
+    public
+    def write_full_duplex(full_duplex, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # The meaning of this command is device dependent.
+    public
+    def write_set_hardware(value, port = 0, *args, **kwargs)
+    end
+
+    ##
+    # The meaning of this command is device dependent.
+    public
+    def write_exit_kiss_mode(*args, **kwargs)
+    end
   end
 end

data/lib/kiss/kiss_abstract.rb

@@ -57,138 +57,10 @@ module Kiss
         end
 
         private
-        def self.extract_path(start, raw_frame)
-            full_path = []
-
-            (2...start).each do |i|
-                path = identity_as_string(extract_callsign(raw_frame[i * 7..-1]))
-                if path and path.length > 0
-                    if raw_frame[i * 7 + 6] & 0x80 != 0
-                        full_path << [path, '*'].join
-                    else
-                        full_path << path
-                    end
-                end
-            end
-            return full_path
-        end
-
-        private
-        def self.parse_identity_string(identity_string)
-            # If we are parsing a spent token then first lets get rid of the astresick suffix.
-            if identity_string[-1] == '*'
-                identity_string = identity_string[0..-1]
-            end
-
-            if identity_string.include? '-'
-                call_sign, ssid = identity_string.split('-')
-            else
-                call_sign = identity_string
-                ssid = 0
-            end
-
-            return {:callsign => call_sign, :ssid => ssid.to_i}
-        end
-
-        private
-        def self.identity_as_string(identity)
-            if identity[:ssid] and identity[:ssid] > 0
-                return [identity[:callsign], identity[:ssid].to_s].join('-')
-            else
-                return identity[:callsign]
-            end
-        end
-
-        private
-        def self.extract_callsign(raw_frame)
-            callsign_as_array = raw_frame[0...6].map { |x| (x >> 1).chr }
-            callsign = callsign_as_array.join.strip
-            ssid = (raw_frame[6] >> 1) & 0x0f
-            ssid = (ssid == nil or ssid == 0 ? nil : ssid)
-            return {:callsign => callsign, :ssid => ssid}
-        end
-
-        private
-        def self.encode_callsign(callsign)
-            call_sign = callsign[:callsign]
-
-            enc_ssid = (callsign[:ssid] << 1) | 0x60
-
-            if call_sign.include? '*'
-                call_sign.gsub!(/\*/, '')
-                enc_ssid |= 0x80
-            end
-
-            while call_sign.length < 6
-                call_sign = [call_sign, ' '].join
-            end
-
-            return call_sign.chars.map { |p| p.ord << 1 } + [enc_ssid]
-        end
-
-        private
-        def self.encode_frame(frame)
-            enc_frame = encode_callsign(parse_identity_string(frame[:destination].to_s)) + encode_callsign(parse_identity_string(frame[:source].to_s))
-
-            frame[:path].each do |hop|
-                enc_frame += encode_callsign(parse_identity_string(hop.to_s))
-            end
-
-            return enc_frame[0...-1] + [enc_frame[-1] | 0x01] + [SLOT_TIME] + [0xf0] + frame[:payload].chars.map { |c| c.ord }
-        end
-
-        private
-        def self.decode_frame(raw_frame)
-            frame_len = raw_frame.length
-
-            if frame_len > 16
-                (0...frame_len - 2).each do |raw_slice|
-                    # Is address field length correct?
-                    if raw_frame[raw_slice] & 0x01 != 0 and ((raw_slice + 1) % 7) == 0
-                        i = (raw_slice.to_f + 1.0) / 7.0
-                        # Less than 2 callsigns?
-                        if 1.0 < i and i < 11.0
-                            if raw_frame[raw_slice + 1] & 0x03 == 0x03 and [0xf0, 0xcf].include? raw_frame[raw_slice + 2]
-                                payload_as_array = raw_frame[raw_slice + 3..-1].map { |b| b.chr }
-                                payload = payload_as_array.join
-                                destination = identity_as_string(extract_callsign(raw_frame))
-                                source = identity_as_string(extract_callsign(raw_frame[7..-1]))
-                                path = extract_path(i.to_i, raw_frame)
-                                return {:source => source, :destination => destination, :path => path, :payload => payload}
-                            end
-                        end
-                    end
-                end
-            end
-            return nil
-        end
-
-        private
-        def self.valid_frame(raw_frame)
-            frame_len = raw_frame.length
-
-            if frame_len > 16
-                (0...frame_len - 2).each do |raw_slice|
-                    # Is address field length correct?
-                    if raw_frame[raw_slice] & 0x01 != 0 and ((raw_slice + 1) % 7) == 0
-                        i = (raw_slice.to_f + 1.0) / 7.0
-                        # Less than 2 callsigns?
-                        if 1.0 < i and i < 11.0
-                            if raw_frame[raw_slice + 1] & 0x03 == 0x03 and [0xf0, 0xcf].include? raw_frame[raw_slice + 2]
-                                return true
-                            end
-                        end
-                    end
-                end
-            end
-            return false
-        end
-
-        private
-        def fill_buffer
+        def fill_buffer(*args, **kwargs)
             new_frames = []
             read_buffer = []
-            read_data = read_interface
+            read_data = read_interface(*args, **kwargs)
             while read_data and read_data.length > 0
                 split_data = [[]]
                 read_data.each do |read_byte|
@@ -229,7 +101,7 @@ module Kiss
                     end
                 end
                 # Get anymore data that is waiting
-                read_data = read_interface
+                read_data = read_interface(*args, **kwargs)
             end
 
             new_frames.each do |new_frame|
@@ -245,7 +117,7 @@ module Kiss
         private
         def read_bytes(*args, **kwargs)
               if @frame_buffer.length == 0
-                  fill_buffer
+                  fill_buffer(*args, **kwargs)
               end
 
               if @frame_buffer.length > 0
@@ -257,48 +129,99 @@ module Kiss
               end
         end
 
-        private
-        def write_bytes(frame_bytes, port=0, *args, **kwargs)
-              kiss_packet = [FEND] + [KissAbstract.command_byte_combine(port, DATA_FRAME)] +
-                  KissAbstract.escape_special_codes(frame_bytes) + [FEND]
+        public
+        def write_generic_command(command, port, value, *args, **kwargs)
+          @lock.synchronize do
+            raise ArgumentError.new ("command can not be nil") if command.nil?
+            raise RangeError.new("command must be an integer between 0 (inclusive) and 15 (inclusive) instead we got #{command}") if command < 0 or command >= 16 or command&0x0f!=command
+            raise ArgumentError.new ("port can not be nil") if port.nil?
+            raise RangeError.new("port must be an integer between 0 (inclusive) and 15 (inclusive) instead we got #{port}") if port < 0 or port >= 16 or port&0x0f!=port
 
-              write_interface(kiss_packet)
+            if value.nil?
+              write_interface([FEND] + [KissAbstract.command_byte_combine(port, command)] +[FEND], *args, **kwargs)
+            else
+              write_interface([FEND] + [KissAbstract.command_byte_combine(port, command)] + KissAbstract.escape_special_codes(value) + [FEND], *args, **kwargs)
+            end
+          end
         end
 
-        protected
-        def write_setting(command, value)
-            write_interface([FEND] + [command] + KissAbstract.escape_special_codes(value) + [FEND])
+        public
+        def write_datagram(packet_data, port = 0, *args, **kwargs)
+          raise TypeError.new("packet_data can not be nil") if packet_data.nil?
+          raise TypeError.new("packet_data must be an array-like object that implements each, length, and []") if (not packet_data.respond_to?(:each)) or (not packet_data.respond_to?(:[])) or (not packet_data.respond_to?(:length))
+          raise RangeError.new("packet_data must have a length of 1 or more") if packet_data.length <= 0
+
+          write_generic_command(DATA_FRAME, port, packet_data, *args, **kwargs)
         end
 
         public
-        def connect(mode_init=nil, *args, **kwargs)
+        def write_tx_delay(tx_delay, port = 0, *args, **kwargs)
+          raise TypeError.new("tx_delay can not be nil") if tx_delay.nil?
+          raise RangeError.new("tx_delay must be an integer value greater than or equal to 0 and less than 256") if tx_delay < 0 and tx_delay&0xff==tx_delay
+
+          write_generic_command(TX_DELAY, port, tx_delay, *args, **kwargs)
         end
 
         public
-        def close(*args, **kwargs)
+        def write_persistence(persistence, port = 0, *args, **kwargs)
+          raise TypeError.new("persistence can not be nil") if persistence.nil?
+          raise RangeError.new("persistence must be an integer value greater than or equal to 0 and less than 256") if persistence < 0 and persistence&0xff==persistence
+
+          write_generic_command(PERSISTENCE, port, persistence, *args, **kwargs)
         end
 
         public
-        def read(*args, **kwargs)
-          @lock.synchronize do
-              frame = self.read_bytes(*args, **kwargs)
-              if frame and frame.length > 0
-                  return KissAbstract.decode_frame(frame)
-              else
-                  return nil
-              end
+        def write_slot_time(slot_time, port = 0, *args, **kwargs)
+          raise TypeError.new("slot_time can not be nil") if slot_time.nil?
+          raise RangeError.new("slot_time must be an integer value greater than or equal to 0 and less than 256") if slot_time < 0 and slot_time&0xff==slot_time
+
+          write_generic_command(SLOT_TIME, port, slot_time, *args, **kwargs)
+        end
+
+        public
+        def write_tx_tail(tx_tail, port = 0, *args, **kwargs)
+          raise TypeError.new("tx_tail can not be nil") if tx_tail.nil?
+          raise RangeError.new("tx_tail must be an integer value greater than or equal to 0 and less than 256") if tx_tail < 0 and tx_tail&0xff==tx_tail
+
+          write_generic_command(TX_TAIL, port, tx_tail, *args, **kwargs)
+        end
+
+        public
+        def write_full_duplex(full_duplex, port = 0, *args, **kwargs)
+          raise TypeError.new("full_duplex can not be nil") if full_duplex.nil?
+          raise TypeError.new("full_duplex must be either truthy or falsy") if full_duplex != (!!full_duplex)
+
+          if full_duplex
+            write_generic_command(FULL_DUPLEX, port, 1, *args, **kwargs)
+          else
+            write_generic_command(FULL_DUPLEX, port, 0, *args, **kwargs)
           end
         end
 
         public
-        def write(frame, port=0, *args, **kwargs)
+        def write_set_hardware(value, port = 0, *args, **kwargs)
+          raise TypeError.new("value can not be nil") if value.nil?
+
+          write_generic_command(SET_HARDWARE, port, value, *args, **kwargs)
+        end
+
+        public
+        def write_exit_kiss_mode(*args, **kwargs)
+          write_generic_command(RETURN, 0, nil*args, **kwargs)
+        end
+
+        public
+        def connect(mode_init=nil, *args, **kwargs)
+        end
+
+        public
+        def close(*args, **kwargs)
+        end
+
+        public
+        def read_datagram(*args, **kwargs)
           @lock.synchronize do
-              encoded_frame = KissAbstract.encode_frame(frame)
-              if KissAbstract.valid_frame(encoded_frame)
-                self.write_bytes(encoded_frame, *args, **kwargs)
-              else
-                raise IOError.new("frame was able to be encoded but was determined not to be valid")
-              end
+              return self.read_bytes(*args, **kwargs)
           end
         end
     end

data/lib/kiss/kiss_serial.rb

@@ -28,8 +28,8 @@ module Kiss
         end
 
         protected
-        def read_interface
-            read_data = @serial.read(@read_bytes)
+        def read_interface(*args, **kwargs)
+            read_data = @serial.read(@read_bytes, *args, **kwargs)
             if read_data
                 return read_data.chars.map { |c| c.ord }
             else
@@ -38,18 +38,18 @@ module Kiss
         end
 
         protected
-        def write_interface(data)
+        def write_interface(data, *args, **kwargs)
             unless data.is_a? String
                 data = data.map { |b| b.chr }.join
             end
-            @serial.write(data)
+            @serial.write(data, *args, **kwargs)
         end
 
         public
         def connect(mode_init=nil, *args, **kwargs)
             super
 
-            @serial = SerialPort.new(@com_port, @baud, @byte_size, @stop_bits, @parity)
+            @serial = SerialPort.new(@com_port, @baud, @byte_size, @stop_bits, @parity, *args, **kwargs)
             @serial.read_timeout = SERIAL_READ_TIMEOUT
 
             if mode_init
@@ -58,14 +58,6 @@ module Kiss
             else
                 @exit_kiss = false
             end
-
-            # Previous verious defaulted to Xastir-friendly configs. Unfortunately
-            # those don't work with Bluetooth TNCs, so we're reverting to None.
-            if kwargs
-                kwargs.each do |name, value|
-                    write_setting(name, value)
-                end
-            end
         end
 
         public
@@ -79,7 +71,7 @@ module Kiss
             if @serial == nil or @serial.closed?
                 raise IOError.new('Attempting to close before the class has been started.')
             else
-                @serial.close
+                @serial.close(*args, **kwargs)
             end
         end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kiss-tnc
 version: !ruby/object:Gem::Version
-  version: 2.1.3
+  version: 3.0.0
 platform: ruby
 authors:
 - Jeffrey Phillips Freeman
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2023-08-16 00:00:00.000000000 Z
+date: 2023-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abstractify
@@ -110,7 +110,7 @@ dependencies:
         version: '0.9'
 description: Ruby library for KISS communication with Terminal Node Controllers.
 email:
-- jeffrey.freeman@syncleus.com
+- the@jeffreyfreeman.me
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -122,7 +122,6 @@ files:
 - Gemfile
 - LICENSE
 - README.md
-- README.rdoc
 - Rakefile
 - kiss-tnc.gemspec
 - lib/kiss.rb
@@ -151,7 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Library for KISS communication with TNCs.

data/README.rdoc

@@ -1,19 +0,0 @@
-= apex - DESCRIBE YOUR GEM
-
-Author::  Jeffrey Phillips Freeman (freemo@gmail.com)
-Copyright:: Copyright (c) 2016 Syncleus
-
-
-DESCRIBE YOUR GEM HERE
-
-== Links
-
-* {Source on Github}[https://github.com/Syncleus/kiss-tnc]
-* RDoc[LINK TO RDOC.INFO]
-
-== Install
-
-== Examples
-
-== Contributing
-