ruxbee 0.1.0

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/listen_api.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruxbee"
+require 'pp'
+require 'getoptlong'
+
+
+opts = GetoptLong.new(
+  [ '--device', '-d', GetoptLong::REQUIRED_ARGUMENT ],
+  [ '--speed', '-s', GetoptLong::REQUIRED_ARGUMENT ]
+)
+
+@dev = nil
+@speed = nil
+
+opts.each do |opt, arg|
+ case opt
+ when '--device'
+   @dev = arg
+ when '--speed'
+   @speed = arg.to_i
+ end 
+end
+
+@xbee = XBee.new @dev, @speed, :API_S1
+
+loop do
+  res = @xbee.getresponse
+  if not res.nil? and res.api_identifier == '81'
+    res = {rssi: res.rssi, address: res.address_16_bits, api_frame_id: res.api_identifier, data: res.cmd_data}
+    pp res
+  end
+end
+

data/lib/ruxbee/at_commands.rb

@@ -0,0 +1,28 @@
+module XBee
+  module ATCommands
+    class ParameterDescriptor
+      def initialize
+        yield self if block_given?
+      end
+    end
+
+    class CommandDescriptor
+      attr_reader :command, :command_name, :command_description, :parameter
+
+      def initialize (command, command_name, command_description = nil, parameter = nil)
+        @command = command
+        @command_name = command_name
+        @command_description = command_description
+        @parameter = parameter
+        yield self if block_given?
+      end
+
+      def has_parameter?
+        parameter.nil?
+      end
+    end
+
+    AP_PARAM_DESCRIPTOR = ParameterDescriptor.new
+    AP = CommandDescriptor.new("AP","API Mode","0 = off; 1 = on, unescaped; 2 = on, escaped", AP_PARAM_DESCRIPTOR)
+  end
+end

data/lib/ruxbee/config.rb

@@ -0,0 +1,96 @@
+
+module XBee
+  module Config
+    ##
+    # A class for encapsulating UART communication parameters
+
+    class XBeeUARTConfig
+      attr_accessor :baud, :data_bits, :parity, :stop_bits
+
+      ##
+      # Defaults to standard 9600 baud 8N1 communications
+      def initialize(baud = 9600, data_bits = 8, parity = 0, stop_bits = 1)
+        self.baud = Integer(baud)
+        self.data_bits = Integer(data_bits)
+        self.parity = Integer(parity)
+        self.stop_bits = Integer(stop_bits)
+      end
+
+    end
+
+    ##
+    # A class for encapsulating XBee programmable parameters
+    class RFModuleParameter
+      attr_accessor :at_name, :value, :default_value, :retrieved, :operation_mode
+
+      def initialize(at_name, default_value)
+        self.at_name= at_name
+        self.default_value = default_value
+        self.value = default_value
+        self.retrieved = false
+      end
+
+    end
+
+    class GuardTime < RFModuleParameter
+      def initialize(default = 0x3E8)
+        super("GT", default)
+      end
+
+      def in_seconds
+        self.value / 1000.0
+      end
+    end
+
+    class CommandModeTimeout < RFModuleParameter
+      def initialize(default = 0x64)
+        super("CT", default)
+      end
+
+      def in_seconds
+        self.value / 1000.0
+      end
+    end
+
+    class CommandCharacter < RFModuleParameter
+      def initialize(default = '+')
+        super("CC", default)
+      end
+    end
+
+
+    class NodeDiscoverTimeout < RFModuleParameter
+      def initialize(default = 0x82)
+        super("NT", default)
+      end
+
+      def in_seconds
+        self.value / 10.0
+      end
+    end
+
+    class NodeIdentifier < RFModuleParameter
+      def initialize(default = " ")
+        super("NI", default)
+      end
+    end
+
+    class ApiEnableMode < RFModuleParameter
+      def initialize(default = 0x01)
+        unless default == 0x01 or default == 0x02
+          raise "XBee AP parameter range can be 1-2; 1 = API-enabled; 2 = API-enabled (with escaped control characters)"
+        end
+        super("AP", default)
+      end
+
+      def in_symbol
+        unless self.value == 0x01 or self.value == 0x02
+          raise "XBee AP parameter invalid range! Valid range 1-2; Set to: #{self.value}"
+        end
+        return :API1 if self.value == 0x01
+        return :API2 if self.value == 0x02
+      end
+    end
+  end
+
+end

data/lib/ruxbee/frame/at_command.rb

@@ -0,0 +1,35 @@
+
+module XBee
+  module Frame
+    class ATCommand < XBee::Frame::Base
+      def api_identifier ; 0x08 ; end
+
+      attr_accessor :at_command, :parameter_value, :parameter_pack_string
+
+      def initialize(at_command, frame_id = nil, parameter_value = nil, parameter_pack_string = "a*")
+        self.frame_id = frame_id
+        self.at_command = at_command # TODO: Check for valid AT command codes here
+        self.parameter_value = parameter_value
+        self.parameter_pack_string = parameter_pack_string
+        yield self if block_given?
+      end
+
+      def cmd_data=(data_string)
+        self.frame_id, self.at_command, self.parameter_value = data_string.unpack("ca2#{parameter_pack_string}")
+      end
+
+      def cmd_data
+        if parameter_value.nil?
+          [frame_id, at_command].pack("ca2")
+        else
+          [frame_id, at_command, parameter_value].pack("ca2#{parameter_pack_string}")
+        end
+      end
+    end
+
+    class ATCommandQueueParameterValue < ATCommand
+      def api_identifier ; 0x09 ; end
+    end
+
+  end
+end

data/lib/ruxbee/frame/at_command_response.rb

@@ -0,0 +1,33 @@
+module XBee
+  module Frame
+    class ATCommandResponse < ReceivedFrame
+      attr_accessor :frame_id, :at_command, :status, :retrieved_value
+
+      def initialize(data = nil)
+        super(data) && (yield self if block_given?)
+      end
+
+      def command_statuses
+        [:OK, :ERROR, :Invalid_Command, :Invalid_Parameter]
+      end
+
+      def cmd_data=(data_string)
+        self.frame_id, self.at_command, status_byte, self.retrieved_value = data_string.unpack("Ca2Ca*")
+        self.status = case status_byte
+        when 0..3 
+          command_statuses[status_byte]
+        else
+          raise "AT Command Response frame appears to include an invalid status: 0x%x" % status_byte
+        end
+        #actually assign and move along
+        @cmd_data = data_string
+        #### DEBUG ####
+        if $DEBUG then
+          print "Retrieved Value: #{self.retrieved_value.unpack('C*').join(', ')} | "
+          print "Retrieved Value: #{self.retrieved_value.unpack('a*')} | "
+        end
+        #### DEBUG ####
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/base_frame.rb

@@ -0,0 +1,32 @@
+module XBee
+  module Frame
+    
+    class Base
+      attr_accessor :api_identifier, :cmd_data, :frame_id
+
+      def api_identifier ; @api_identifier ||= 0x00 ; end
+
+      def cmd_data ; @cmd_data ||= "" ; end
+
+      def length ; data.length ; end
+
+      def data
+        Array(api_identifier).pack("C") + cmd_data
+      end
+
+      def _dump(api_mode = :API1)
+        unless api_mode == :API1 or api_mode == :API2
+          raise "XBee api_mode must be either :API1 (non-escaped) or :API2 (escaped, default)"
+        end
+        raise "Too much data (#{self.length} bytes) to fit into one frame!" if (self.length > 0xFFFF)
+
+        if (api_mode == :API1)
+          "~" + [length].pack("n") + data + [Frame.checksum(data)].pack("C")
+        elsif (api_mode == :API2)
+          "~" + [length].pack("n").xb_escape + data.xb_escape + [Frame.checksum(data)].pack("C")
+        end
+      end
+    end
+
+  end
+end

data/lib/ruxbee/frame/explicit_addressing_command.rb

@@ -0,0 +1,52 @@
+module XBee
+  module Frame
+    ##
+    # Explicit Addressing ZigBee Command Frame (0x11)
+    #
+    # This frame allows ZigBee Application Layer fields to be specified for
+    # a data transmission. This frame is similar to Zigbee Transmit Request (0x10)
+    # but requires the ZigBee application layer addressing fields to be set.
+    #
+    # This frame is also used for triggering Programmable XBee (S2B) module
+    # Over-the-Air firmware upgrade process.
+    #
+    class ExplicitAddressingCommand < Base
+      def  api_identifier ; 0x11 ; end
+
+      attr_accessor :destination_address, :destination_network, :source_endpoint, :destination_endpoint, :cluster_id, :profile_id, :broadcast_radius, :transmit_options, :payload, :payload_pack_string
+
+      def initialize(frame_id = nil, destination_address = 0x000000000000ffff, destination_network = 0x0000fffe, source_endpoint = nil, destination_endpoint = nil, cluster_id = nil, profile_id = nil, broadcast_radius = 0x00, transmit_options = 0x00, payload = nil, payload_pack_string = "a*")
+        self.frame_id = frame_id
+        self.destination_address = destination_address
+        self.destination_network = destination_network
+        self.source_endpoint = source_endpoint
+        self.destination_endpoint = destination_endpoint
+        self.cluster_id = cluster_id
+        self.profile_id = profile_id
+        self.broadcast_radius = broadcast_radius
+        self.transmit_options = transmit_options
+        self.payload = payload
+        self.payload_pack_string = payload_pack_string
+      end
+
+      def cmd_data=(data_string)
+        # We need to read in the 64-bit destination_address in two 32-bit parts.
+        dest_high = dest_low = 0
+        self.frame_id, dest_high, dest_low, self.destination_network, self.source_endpoint, self.destination_endpoint, self.cluster_id, self.profile_id, self.broadcast_radius, self.transmit_options, self.payload = data_string.unpack("CNNnCCnnCC#{payload_pack_string}")
+        self.destination_address = dest_high << 32 | dest_low
+      end
+
+      def cmd_data
+        # We need to pack the 64-bit destination_address in two 32-bit parts.
+        dest_high = (self.destination_address >> 32) & 0xFFFFFFFF
+        dest_low = self.destination_address & 0xFFFFFFFF
+        if payload.nil?
+          # By default we send a null-byte payload \0
+          [self.frame_id, dest_high, dest_low, self.destination_network, self.source_endpoint, self.destination_endpoint, self.cluster_id, self.profile_id, self.broadcast_radius, self.transmit_options, self.payload].pack("CNNnCCnnCCx")
+        else
+          [self.frame_id, dest_high, dest_low, self.destination_network, self.source_endpoint, self.destination_endpoint, self.cluster_id, self.profile_id, self.broadcast_radius, self.transmit_options, self.payload].pack("CNNnCCnnCC#{payload_pack_string}")
+        end
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/explicit_rx_indicator.rb

@@ -0,0 +1,23 @@
+module XBee
+  module Frame
+    ##
+    # ZigBee Explicit Rx Indicator (0x91) (AO=1)
+    class ExplicitRxIndicator < ReceivedFrame
+      def api_identifier ; 0x91 ; end
+      attr_accessor :source_address, :source_network, :source_endpoint, :destination_endpoint, :cluster_id, :profile_id, :receive_options, :received_data
+
+      def initialize(data = nil)
+        super(data) && (yield self if block_given?)
+      end
+
+      def cmd_data=(data_string)
+        # We need to read in the 64-bit source_address in two 32-bit parts.
+        src_high = src_low = 0
+        src_high, src_low, self.source_network, self.source_endpoint, self.destination_endpoint, self.cluster_id, self.profile_id, self.receive_options, self.received_data = data_string.unpack("NNnCCnnCa*")
+        self.source_address = src_high << 32 | src_low
+        @cmd_data = data_string
+      end
+
+    end
+  end
+end

data/lib/ruxbee/frame/frame.rb

@@ -0,0 +1,128 @@
+require 'ruxbee/frame/base_frame'
+require 'ruxbee/frame/received_frame'
+require 'ruxbee/frame/at_command'
+require 'ruxbee/frame/at_command_response'
+require 'ruxbee/frame/explicit_addressing_command'
+require 'ruxbee/frame/explicit_rx_indicator'
+require 'ruxbee/frame/io_data_sample_rx_indicator'
+require 'ruxbee/frame/modem_status'
+require 'ruxbee/frame/receive_packet'
+require 'ruxbee/frame/remote_command_request'
+require 'ruxbee/frame/remote_command_response'
+require 'ruxbee/frame/transmit_request'
+require 'ruxbee/frame/transmit_status'
+require 'ruxbee/frame/receive_packet_16'
+
+class String
+  def xb_escape
+    self.gsub(/[\176\175\021\023]/) { |c| [0x7D, c[0].ord ^ 0x20].pack("CC")}
+  end
+  def xb_unescape
+    self.gsub(/\175./) { |ec| [ec.unpack("CC").last ^ 0x20].pack("C")}
+  end
+end
+
+module XBee
+  module Frame
+    def Frame.checksum(data)
+      0xFF - (data.unpack("C*").inject(0) { |sum, byte| (sum + byte) & 0xFF })
+    end
+
+    def Frame.new(source_io, api_mode = :API1)
+      stray_bytes = []
+      unless api_mode == :API1 or api_mode == :API2
+        raise "XBee api_mode must be either :API1 (non-escaped) or :API2 (escaped, default)"
+      end
+      until (start_delimiter = source_io.readchar.unpack('H*').join.to_i(16)) == 0x7e
+        #puts "Stray byte 0x%x" % start_delimiter
+        print "DEBUG: #{start_delimiter} | " if $DEBUG
+        stray_bytes << start_delimiter
+      end
+      if $VERBOSE
+        puts "Got some stray bytes for ya: #{stray_bytes.map {|b| "0x%x" % b} .join(", ")}" unless stray_bytes.empty?
+      end
+      if(api_mode == :API1)
+        header = source_io.read(3)
+      elsif(api_mode == :API2)
+        header = source_io.read(2).xb_unescape
+      end
+      print "Reading ... header after start byte: #{header.unpack("C*").join(", ")} | " if $DEBUG
+      frame_remaining = frame_length = api_identifier = cmd_data = ""
+      if api_mode == :API2
+        if header.length == 2
+          frame_length = header.unpack("n").first
+        else
+          read_extra_byte = source_io.readchar
+          if(read_extra_byte == "\175")
+            # We stumbled upon another escaped character, read another byte and unescape
+            read_extra_byte += source_io.readchar
+            read_extra_byte = read_extra_byte.xb_unescape
+          else
+            header += read_extra_byte
+          end
+          frame_length = header.unpack("n")
+        end
+        api_identifier = source_io.readchar
+        if(api_identifier == "\175")
+          api_identifier += source_io.readchar
+          api_identifier = api_identifier.xb_unescape
+        end
+        api_identifier = api_identifier.unpack("C").first
+      else
+        frame_length, api_identifier = header.unpack("nC")
+      end
+      #### DEBUG ####
+      if $DEBUG then
+      print "Frame length: #{frame_length} | "
+      print "Api Identifier: #{api_identifier} | "
+      end
+      #### DEBUG ####
+      cmd_data_intended_length = frame_length - 1
+      if api_mode == :API2
+        while ((unescaped_length = cmd_data.xb_unescape.length) < cmd_data_intended_length)
+          cmd_data += source_io.read(cmd_data_intended_length - unescaped_length)
+        end
+        data = api_identifier.chr + cmd_data.xb_unescape
+      else
+        while (cmd_data.length < cmd_data_intended_length)
+          cmd_data += source_io.read(cmd_data_intended_length)
+        end
+        data = api_identifier.chr + cmd_data
+      end
+      sent_checksum = source_io.getc.unpack('H*').join.to_i(16)
+      #### DEBUG ####
+      if $DEBUG then
+      print "Sent checksum: #{sent_checksum} | "
+      print "Received checksum: #{Frame.checksum(data)} | "
+      print "Payload: #{cmd_data.unpack("C*").join(", ")} | "
+      end
+      #### DEBUG ####
+      unless sent_checksum == Frame.checksum(data)
+        raise "Bad checksum - data discarded"
+      end
+      case data[0].unpack('H*')[0].to_i(16)
+        when 0x8A
+          ModemStatus.new(data)
+        when 0x81
+          ReceivePacket16.new(data)
+        when 0x88
+          ATCommandResponse.new(data)
+        when 0x97
+          RemoteCommandResponse.new(data)
+        when 0x8B
+          TransmitStatus.new(data)
+        when 0x90
+          ReceivePacket.new(data)
+        when 0x91
+          ExplicitRxIndicator.new(data)
+        when 0x92
+          IODataSampleRxIndicator.new(data)
+        else
+          ReceivedFrame.new(data)
+      end
+      rescue EOFError
+        # No operation as we expect eventually something
+    end
+
+  end
+end

data/lib/ruxbee/frame/io_data_sample_rx_indicator.rb

@@ -0,0 +1,10 @@
+module XBee
+  module Frame
+    class IODataSampleRxIndicator < ReceivedFrame
+      def cmd_data=(data_string)
+
+        @cmd_data = data_string
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/modem_status.rb

@@ -0,0 +1,32 @@
+module XBee
+  module Frame
+    class ModemStatus < ReceivedFrame
+      attr_accessor :status
+
+      def initialize(data = nil)
+        super(data) && (yield self if block_given?)
+      end
+
+      def modem_statuses
+        [
+          [0, :Hardware_Reset],
+          [1, :Watchdog_Timer_Reset],
+          [2, :Associated],
+        ]
+      end
+
+      def cmd_data=(data_string)
+        status_byte = data_string.unpack("c")[0]
+        # update status ivar for later use
+        self.status = case status_byte
+        when 0..2
+          modem_statuses.assoc(status_byte)
+        else
+          raise "ModemStatus frame appears to include an invalid status value: 0x%02x" % status_byte
+        end
+        #actually assign and move along
+        @cmd_data = data_string
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/receive_packet.rb

@@ -0,0 +1,6 @@
+module XBee
+  module Frame
+    class ReceivePacket < ReceivedFrame
+    end
+  end
+end

data/lib/ruxbee/frame/receive_packet_16.rb

@@ -0,0 +1,29 @@
+module XBee
+  module Frame
+
+    class ReceivePacket16 < Base
+      attr_reader :rssi, :address_16_bits, :options
+      @rssi = 0x00
+      @address_16_bits = 0x0000
+      @options = 0x00
+
+      def initialize(frame_data)
+        self.api_identifier = frame_data[0].unpack('H*')[0] #.join.to_i(16) unless frame_data.nil?
+        if $DEBUG then
+          print "Initializing a ReceivedFrame of type 0x%02x | " % self.api_identifier
+        elsif $VERBOSE
+          puts "Initializing a ReceivedFrame of type 0x%02x" % self.api_identifier
+        end
+        @address_16_bits = frame_data[1..2] unless frame_data.nil?
+        @rssi = frame_data[3] unless frame_data.nil?
+        @options = frame_data[4] unless frame_data.nil?
+        self.cmd_data = frame_data[5..-1] unless frame_data.nil?
+
+        @rssi = @rssi.unpack('C')[0]
+        @address_16_bits = @address_16_bits.unpack('B8B8').join()
+        @options = @options.unpack('B8')[0]
+      end
+    end
+
+  end
+end

data/lib/ruxbee/frame/received_frame.rb

@@ -0,0 +1,16 @@
+module XBee
+  module Frame
+    class ReceivedFrame < Base
+      def initialize(frame_data)
+        self.api_identifier = frame_data[0].unpack('H*').join.to_i(16) unless frame_data.nil?
+        if $DEBUG then
+          print "Initializing a ReceivedFrame of type 0x%02x | " % self.api_identifier
+        elsif $VERBOSE
+          puts "Initializing a ReceivedFrame of type 0x%02x" % self.api_identifier
+        end
+        self.cmd_data = frame_data[1..-1] unless frame_data.nil?
+      end
+    end
+
+  end
+end

data/lib/ruxbee/frame/remote_command_request.rb

@@ -0,0 +1,34 @@
+require 'ruxbee/frame/at_command'
+
+module XBee
+  module Frame
+    class RemoteCommandRequest < XBee::Frame::ATCommand
+      def api_identifier ; 0x17 ; end
+
+      attr_accessor :destination_address, :destination_network
+
+      def initialize(at_command, destination_address = 0x000000000000ffff, destination_network = 0x0000fffe, frame_id = nil, parameter_value = nil, parameter_pack_string = "a*")
+        self.destination_address = destination_address
+        self.destination_network = destination_network
+        super(at_command, frame_id, parameter_value, parameter_pack_string)
+        yield self if block_given?
+      end
+
+      def cmd_data=(data_string)
+        dest_high = dest_low = 0
+        self.frame_id, dest_high, dest_low, self.destination_network, self.at_command, self.parameter_value = data_string.unpack("CNNnxa2#{parameter_pack_string}")
+        self.destination_address = dest_high << 32 | dest_low
+      end
+
+      def cmd_data
+        dest_high = (self.destination_address >> 32) & 0xFFFFFFFF
+        dest_low = self.destination_address & 0xFFFFFFFF
+        if parameter_value.nil?
+          [self.frame_id, dest_high, dest_low, self.destination_network, 0x00, self.at_command].pack("CNNnCa2")
+        else
+          [self.frame_id, dest_high, dest_low, self.destination_network, 0x02, self.at_command, self.parameter_value].pack("CNNnCa2#{parameter_pack_string}")
+        end
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/remote_command_response.rb

@@ -0,0 +1,22 @@
+require 'ruxbee/frame/at_command_response'
+
+module XBee
+  module Frame
+    class RemoteCommandResponse < XBee::Frame::ATCommandResponse
+      attr_accessor :destination_address, :destination_network
+      def cmd_data=(data_string)
+        dest_high = dest_low = 0
+        self.frame_id, dest_high, dest_low, self.destination_network, self.at_command, status_byte, self.retrieved_value = data_string.unpack("CNNna2Ca*")
+        self.destination_address = dest_high << 32 | dest_low
+        self.status = case status_byte
+        when 0..4
+          command_statuses[status_byte]
+        else
+          raise "AT Command Response frame appears to include an invalid status: 0x%02x" % status_byte
+        end
+        #actually assign and move along
+        @cmd_data = data_string
+      end
+    end
+  end
+end

data/lib/ruxbee/frame/transmit_request.rb

@@ -0,0 +1,7 @@
+module XBee
+  module Frame
+    class TransmitRequest < Base
+      def api_identifier ; 0x10 ; end
+    end
+  end
+end

data/lib/ruxbee/frame/transmit_status.rb

@@ -0,0 +1,6 @@
+module XBee
+  module Frame
+    class TransmitStatus < ReceivedFrame
+    end
+  end
+end