ruby-xbee 1.1.0

data/bin/xbeesend.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# == Synposis
+# xbeesend.rb - A Ruby utility for sending raw data to and through an XBee
+#
+# :title: xbeesend.rb - A Ruby utility for sending raw data to and through an XBee
+#
+# == Copyright
+# Copyright (C) 2008-2009 360VL, Inc. and Landon Cox
+#
+# == License
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License version 3 for more details.
+#
+# You should have received a copy of the GNU Affero General Public License along with this program.
+# If not, see http://www.gnu.org/licenses/
+#
+# You can learn more about ruby for XBee and other projects at http://sawdust.see-do.org
+#
+# == Usage
+#    xbeesend.rb [message]
+#
+# example:
+#      ./xbeesend.rb 'this is some data to send' 'some more data' 'last bits'
+#
+# each of the 3 parameters above is sent in succession.  You can put as many messages on the command
+# line as will be accomodated by the shell.
+#
+# example
+#      ./xbeesend.rb
+#
+# this form of the command will wait for you to input data from the keyboard...it reads stdin input
+# and every line you type will be sent to/through the XBee when you hit enter
+#
+# this utility can be used also for just setting up an XBee with raw AT commands.
+# it doesn't interpret anything in or out of the XBee.  You can put the XBee into attention by:
+#      ./xbeesend.rb '+++'
+# if you monitor it with the xbeelisten.rb utility, you'd see an 'OK' in response
+#
+# See conf/xbeeconfig.rb for configuration defaults
+#
+# this code is for the following XBee modules:
+# IEEE® 802.15.4 OEM RF Modules by Digi International
+#
+# == See Also
+# xbeeinfo.rb, xbeeconfigure.rb, xbeedio.rb, xbeelisten.rb, xbeesend.rb
+#
+# == Learn more
+# You can learn more about Ruby::XBee and other projects at http://sawdust.see-do.org
+#
+# see Digi product manual: "Product Manual v1.xCx - 802.15.4 Protocol"
+# for details on the operation of XBee series 1 modules.
+#
+
+$: << File.dirname(__FILE__)
+
+require 'date'
+require 'getoptlong'
+
+require 'ruby-xbee'
+
+# start a connection to the XBee
+@xbee = XBee.new( @xbee_usbdev_str, @xbee_baud, @data_bits, @stop_bits, @parity )
+
+if ( ARGV.size > 0 )
+  ARGV.each do | message |
+    puts "Sending: #{message}"
+    @xbee.send! message
+  end
+else  # take input from STDIN to make it interactive
+  while true
+    message = gets
+    @xbee.send! message
+  end
+end
+

data/lib/apimode/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/apimode/frame/at_command.rb

@@ -0,0 +1,34 @@
+module XBee
+  module Frame
+    class ATCommand < 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/apimode/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/apimode/frame/explicit_addressing_command.rb

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

data/lib/apimode/frame/explicit_rx_indicator.rb

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

data/lib/apimode/frame/frame.rb

@@ -0,0 +1,123 @@
+$: << File.dirname(__FILE__)
+
+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)
+      stray_bytes = []
+      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
+      puts "Got some stray bytes for ya: #{stray_bytes.map {|b| "0x%x" % b} .join(", ")}" unless stray_bytes.empty?
+      header = source_io.read(3).xb_unescape
+      print "Reading ... header after start byte: #{header.unpack("C*").join(", ")} | " if $DEBUG
+      frame_remaining = frame_length = api_identifier = cmd_data = ""
+      if header.length == 3
+        frame_length, api_identifier = header.unpack("nC")
+      else
+        frame_length, api_identifier = header.unpack("n").first, source_io.readchar
+      end
+      #### DEBUG ####
+      if $DEBUG then
+      print "Frame length: #{frame_length} | "
+      print "Api Identifier: #{api_identifier} | "
+      end
+      #### DEBUG ####
+      cmd_data_intended_length = frame_length - 1
+      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
+      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 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
+
+    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
+        raise "Too much data (#{self.length} bytes) to fit into one frame!" if (self.length > 0xFFFF)
+        "~" + [length].pack("n").xb_escape + data.xb_escape + [Frame.checksum(data)].pack("C")
+      end
+    end
+
+    class ReceivedFrame < Base
+      def initialize(frame_data)
+        # raise "Frame data must be an enumerable type" unless frame_data.kind_of?(Enumerable)
+        self.api_identifier = frame_data[0]
+        if $DEBUG then
+          print "Initializing a ReceivedFrame of type 0x%x | " % self.api_identifier.unpack('H*').join.to_i(16)
+        else
+          puts "Initializing a ReceivedFrame of type 0x%x" % self.api_identifier.unpack('H*').join.to_i(16)
+        end
+        self.cmd_data = frame_data[1..-1]
+      end
+    end
+  end
+end
+
+require 'at_command'
+require 'at_command_response'
+require 'explicit_addressing_command'
+require 'explicit_rx_indicator'
+require 'io_data_sample_rx_indicator'
+require 'modem_status'
+require 'receive_packet'
+require 'remote_command_request'
+require 'remote_command_response'
+require 'transmit_request'
+require 'transmit_status'
+

data/lib/apimode/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: #{data_string}"
+        end
+        #actually assign and move along
+        @cmd_data = data_string
+      end
+    end
+  end
+end

data/lib/apimode/frame/receive_packet.rb

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

data/lib/apimode/frame/remote_command_request.rb

@@ -0,0 +1,34 @@
+require 'at_command'
+
+module XBee
+  module Frame
+    class RemoteCommandRequest < 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/apimode/frame/remote_command_response.rb

@@ -0,0 +1,22 @@
+require 'at_command_response'
+
+module XBee
+  module Frame
+    class RemoteCommandResponse < 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%x" % status_byte
+        end
+        #actually assign and move along
+        @cmd_data = data_string
+      end
+    end
+  end
+end

data/lib/apimode/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/apimode/frame/transmit_status.rb

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