ruby-xbee 1.1.0 → 1.2.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    M2YwMDViM2UwZDVhODRmOTY5NTk0MTk5ZjlmYzlhMGQ1ZGEyZGFmZg==
-  data.tar.gz: !binary |-
-    MTRhMGYwODc0MTVjN2ZiZTI3MjI0ODJmYTg0MjUwYWQwNjEwODdhNQ==
+SHA1:
+  metadata.gz: 69899610a08432193f6c6aa024e12d7d1d1f1307
+  data.tar.gz: 4ad1f0cf2f2f80632767e79b28317d076032071c
 SHA512:
-  metadata.gz: !binary |-
-    YWRiNmE4NjFhNDQzNGJmNmY0ZGNhODJmY2ViYWE4ZjMxNTBmZjgxNmU0ODA1
-    YWEwOGMyMjE1MTk4MDhmMWE3Mjc5ZGVmZGQ3OTNjNzNhNTkyZmFkNjMzYTYw
-    NzYxZWY1MDlhZmQ1N2MzNGJjMWZiZDg4ZGFiZWUzMDQzYmJkYmE=
-  data.tar.gz: !binary |-
-    MTVmODU0MzllZjM4ZmNhYWI5ZGM5MDMyMGE1ZjJmYzJiNDJlMTc3YTYxYjhk
-    ZmQ1MmU5Y2QyYjJiN2YxNzdlMzJlM2JjMGQ0NmRmNGVhNmE2MWJjYThiMWNl
-    YmJkZTc3ZmNiYjRmOWMwYjEwYmUzOTY3MTQzZjBmNmFmM2M5Njc=
+  metadata.gz: be955c5442b964912f43af8aa2fa15a3a3ac123adc48d98095b8b929570fe1c78f85f4141b0e2f949ae5cda6ee8ae4bfadf402e64d05e48eca90efca4d969782
+  data.tar.gz: 8347bdc735975f245bcbc5feb0e80efa24a01a3b7e488eebe0ae063ea521846754d09d5878ed47030e768ac95d3b2926b15cc5c2f6dcefa3cede73f20f34ffc5

data/README.rdoc

@@ -47,10 +47,11 @@ Example use of the core XBee ruby class can be found in the utilities themselves
 xbeeinfo.rb, xbeeconfigure.rb, xbeedio.rb, xbeelisten.rb, xbeesend.rb
 
 == Quick Start
-0. install ruby 1.9.3 or 2.0.0 for your platform (see http://www.ruby-lang.org)
-1. download the ruby-xbee ( git clone https://github.com/exsilium/ruby-xbee )
-2. determine your /dev string and configure that in bin/ruby-xbee.rb
-3. try ./bin/xbeeinfo.rb
+1. install ruby 1.9.3 or 2.0.0 for your platform (see http://www.ruby-lang.org)
+2. download the ruby-xbee ( git clone https://github.com/exsilium/ruby-xbee )
+3. install the dependencies `bundle install`
+4. determine your /dev string and configure that in bin/ruby-xbee.rb
+5. try ./bin/xbeeinfo.rb
 
 == Detailed Quick Start
 === clone the ruby-xbee repository.  

data/bin/apilisten.rb

@@ -6,9 +6,9 @@ require 'ruby-xbee'
 require 'pp'
 
 @uart_config = XBee::Config::XBeeUARTConfig.new()
-@xbee = XBee::BaseAPIModeInterface.new(@xbee_usbdev_str, @uart_config, 'API')
+@xbee = XBee::BaseAPIModeInterface.new(@xbee_usbdev_str, @uart_config)
 
 # read XBee output forever
 while 1
   @xbee.getresponse true
-end
+end

data/bin/ota_upgrade.rb

@@ -0,0 +1,213 @@
+#!/usr/bin/env ruby
+#
+# Programmable XBee module Over the Air (OTA) Upgrade
+# A sample using ruby-xbee and xmodem.
+#
+# Please note, this only works for PROGRAMMABLE XBee modules and for uploading
+# the *application* firmware, not to be confused with the radio firmware.
+#
+# The coordinator must be running in API 1 mode because the programmable XBEE
+# does not properly in the API mode 2 (with escaped control characters).
+#
+# This is specific to Series 2 radios and ZigBee
+#
+# This script is not interactive, please define the below CONSTANTS before use
+#
+# If you are using broadcast addresses, make sure only one device is there to
+# answer, concurrent upgrades have not been implemented
+#
+# Prerequisites: Install the xmodem gem by: gem install xmodem it's purposely
+# left out from runtime dependencies.
+#
+# Usage: 1) set the constants
+#        2) make sure the ruby-xbee.rb has the correct device configured
+#        3) ./ota_upgrade.rb
+#
+$: << File.dirname(__FILE__)
+
+require 'date'
+require 'ruby-xbee'
+require 'pp'
+require 'socket'
+
+require 'rubygems'
+gem 'xmodem'
+require 'xmodem'
+
+### CONSTANTS - SET BEFORE USE
+
+# Target Address of the device being upgraded 0x000000000000FFFF for broadcast
+TARGET_ADDRESS = 0x000000000000FFFF
+# Target network, 0xFFFE for broadcast
+TARGET_NETWORK = 0xFFFE
+# OTA password, nil, if no password used
+PASSWORD = nil
+# Firmware file being uploaded, can be full path
+TRANSFER_FILE = "blink_led_0_0_1_OTA_blank_pass.bin"
+# If not on unix, this is the port used for XMODEM IO
+LOCAL_PORT = 2000
+
+### END OF CONSTANTS
+
+@uart_config = XBee::Config::XBeeUARTConfig.new()
+@xbee = XBee::Series2APIModeInterface.new(@xbee_usbdev_str, @uart_config)
+
+# Create server/socket for XModem transfer
+@server=nil
+@unix_socket = "/tmp/xmodem-transfer.sock"
+
+# State variables
+@transfer_started = false
+@transfer_eot = 0
+
+if !FileTest.exists?(TRANSFER_FILE)
+  puts "Firmware file not found: #{TRANSFER_FILE}"
+  exit
+end
+
+if ENV['OS'] != "Windows_NT"
+  File.delete( @unix_socket ) if FileTest.exists?( @unix_socket )
+  @server = UNIXServer.new(@unix_socket)
+else
+  @server = TCPServer.new(LOCAL_PORT)
+end
+
+puts "---------------------------------------------------"
+puts "             Over The Air Upgrade                  "
+puts "---------------------------------------------------"
+puts "Target address: 0x%x" % TARGET_ADDRESS
+puts "Target network: 0x%x" % TARGET_NETWORK
+puts "---------------------------------------------------"
+
+#XMODEM::logger.outputters = Outputter.stdout
+XMODEM::timeout_seconds = 10.0 # Let's prolong the timeout
+XMODEM::block_size      = 64   # XBEE uses non-standard block size
+
+puts "XMODEM: Transfer blocksize: #{XMODEM::block_size}"
+puts "XMODEM: Timeout in seconds: #{XMODEM::timeout_seconds}"
+
+transfer_thread = Thread.new {
+  session = @server.accept
+  session.sync = true
+  file = File.new(TRANSFER_FILE, "rb")
+  puts "Starting file transfer of: #{TRANSFER_FILE}"
+  XMODEM::send(session, file)
+  session.close
+  puts "<CLOSED>"
+  file.close
+}
+
+##
+# If the target board does not have proper OTA enabled application running
+# or if the previous upgrades have been unsuccessful to the point where the
+# module is unable to run and goes to bootloader, the following method
+# can be used instead of the init_ota_upgrade. If the application is running
+# the following request does not get any response
+#
+# Please note that the following works only if the target is in bootloader and
+# when explicit addressing is used (broadcast address doesn't work, altough
+# the target network can be broadcast)!
+frame_id = @xbee.next_frame_id
+frame_to_send = XBee::Frame::ExplicitAddressingCommand.new(frame_id, TARGET_ADDRESS, TARGET_NETWORK, 0xE8, 0xE8, 0x0011, 0xC105, 0x00, 0x00, "F")
+@xbee.xbee_serialport.write(frame_to_send._dump)
+
+##
+# The following call is meant for Applications that have the OTA upgrade
+# enabled. In case of wrong password a "bad password" message is sent in reply
+#
+# Let's send a initialization package for starting OTA upgrade
+@xbee.init_ota_upgrade(PASSWORD, TARGET_ADDRESS, TARGET_NETWORK)
+
+# main loop
+while 1
+  begin
+
+    r = @xbee.getresponse true
+
+    if r.kind_of?(XBee::Frame::ExplicitRxIndicator) and r.cluster_id == 0x0011 and r.profile_id == 0xC105
+      if !@transfer_started and r.received_data == "C"
+        puts "XBEE: Got response with frame type: 0x%02x" % r.api_identifier
+        puts "XBEE: Source address of the one waiting for new firmware: %x" % r.source_address
+        # Connect to socket
+        if ENV['OS'] != "Windows_NT"
+          socket = UNIXSocket.open(@unix_socket)
+        else
+          socket = TCPSocket.new('localhost', LOCAL_PORT)
+        end
+        socket.sync=true
+        @transfer_started = true
+        puts "Connected to socket"
+        sleep(0.1)
+      end
+
+      if r.received_data == "C"
+        print "C"
+      elsif r.received_data.ord == XMODEM::ACK
+        print "O"
+      elsif r.received_data.ord == XMODEM::NAK
+        print "X"
+      elsif r.received_data == "F" and !@transfer_started
+        puts "F - Upgrade started from bootloader"
+        next
+      else
+        print "?"
+      end
+
+      unless socket.closed?
+        # As we have the socket open, we can presume the tranmission is ok to
+        # start.
+        if transfer_thread.alive? and @transfer_eot < 1
+          # Send the received payload to local XMODEM socket
+          socket.write(r.received_data)
+
+          # Try to get the block that the XMODEM wants to send
+          # 3 header bytes, data block, 2 bytes checksum
+          # We read the first byte separately in case it's the end of file
+          data_to_send = ""
+          b = XMODEM::receive_getbyte(socket)
+          data_to_send << b
+
+          if data_to_send.ord == XMODEM::SOH
+            (XMODEM::block_size+4).times do
+              b = XMODEM::receive_getbyte(socket)
+              data_to_send << b
+            end
+          elsif data_to_send.ord == XMODEM::EOT
+            print "<END-OF-TRANSMISSION>"
+            @transfer_eot += 1
+          end
+
+          #puts "Inspecting packet to encapsulate: #{data_to_send.inspect}"
+
+          # We have the XMODEM block, we should encapsulate and send it to the radio
+          frame_id = @xbee.next_frame_id
+          frame_to_send = XBee::Frame::ExplicitAddressingCommand.new(frame_id, r.source_address, r.source_network, 0xE8, 0xE8, 0x0011, 0xC105, 0x00, 0x00, data_to_send)
+          @xbee.xbee_serialport.write(frame_to_send._dump)
+          print "."
+        else
+          # Transfer completed
+          socket.close
+          puts "XBEE: Transfer completed!"
+          break
+        end
+      end
+    elsif r.kind_of?(XBee::Frame::ExplicitRxIndicator) and r.cluster_id == 0x1000 and r.profile_id == 0xC105 and r.received_data == "bad password"
+      puts "XBEE: Bad password sent for device: 0x%x. Giving up." % r.source_address
+      break
+    end
+
+    if r.kind_of?(XBee::Frame::TransmitStatus)
+      #puts "XBEE: Got response with frame type: 0x%02x" % r.api_identifier
+      #puts "XBEE: cmd_data: #{r.cmd_data.inspect}"
+    end
+
+  rescue RuntimeError => e
+    puts e
+  end
+end
+
+unless ENV['OS'] == "Windows_NT"
+  File.delete( @unix_socket ) if FileTest.exists?( @unix_socket )
+end
+
+puts "Exiting!"

data/lib/apimode/frame/explicit_addressing_command.rb

@@ -1,7 +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
+      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/apimode/frame/explicit_rx_indicator.rb

@@ -1,6 +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/apimode/frame/frame.rb

@@ -15,21 +15,48 @@ module XBee
       0xFF - (data.unpack("C*").inject(0) { |sum, byte| (sum + byte) & 0xFF })
     end
 
-    def Frame.new(source_io)
+    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
-      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
+      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 header.length == 3
-        frame_length, api_identifier = header.unpack("nC")
+      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("n").first, source_io.readchar
+        frame_length, api_identifier = header.unpack("nC")
       end
       #### DEBUG ####
       if $DEBUG then
@@ -38,10 +65,17 @@ module XBee
       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)
+      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
-      data = api_identifier.chr + cmd_data.xb_unescape
       sent_checksum = source_io.getc.unpack('H*').join.to_i(16)
       #### DEBUG ####
       if $DEBUG then
@@ -56,15 +90,15 @@ module XBee
       case data[0].unpack('H*')[0].to_i(16)
         when 0x8A
           ModemStatus.new(data)
-        when 0x88 
+        when 0x88
           ATCommandResponse.new(data)
-        when 0x97 
+        when 0x97
           RemoteCommandResponse.new(data)
-        when 0x8B 
+        when 0x8B
           TransmitStatus.new(data)
-        when 0x90 
+        when 0x90
           ReceivePacket.new(data)
-        when 0x91 
+        when 0x91
           ExplicitRxIndicator.new(data)
         when 0x92
           IODataSampleRxIndicator.new(data)
@@ -88,22 +122,29 @@ module XBee
         Array(api_identifier).pack("C") + cmd_data
       end
 
-      def _dump
+      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)
-        "~" + [length].pack("n").xb_escape + data.xb_escape + [Frame.checksum(data)].pack("C")
+
+        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
 
     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]
+        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%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)
+          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]
+        self.cmd_data = frame_data[1..-1] unless frame_data.nil?
       end
     end
   end
@@ -120,4 +161,3 @@ require 'remote_command_request'
 require 'remote_command_response'
 require 'transmit_request'
 require 'transmit_status'
-

data/lib/apimode/frame/modem_status.rb

@@ -22,7 +22,7 @@ module XBee
         when 0..2
           modem_statuses.assoc(status_byte)
         else
-          raise "ModemStatus frame appears to include an invalid status value: #{data_string}"
+          raise "ModemStatus frame appears to include an invalid status value: 0x%02x" % status_byte
         end
         #actually assign and move along
         @cmd_data = data_string

data/lib/apimode/frame/remote_command_response.rb

@@ -12,7 +12,7 @@ module XBee
         when 0..4
           command_statuses[status_byte]
         else
-          raise "AT Command Response frame appears to include an invalid status: 0x%x" % status_byte
+          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

data/lib/apimode/xbee_api.rb

@@ -3,11 +3,42 @@ require 'frame/frame'
 require File.dirname(File.dirname(__FILE__)) + '/ruby_xbee'
 
 module XBee
+  ##
+  # This is the main class for API mode for XBee radios.
   class BaseAPIModeInterface < RFModule
-  
-    VERSION = "1.1.0" # Version of this class
-  
-    def initialize(xbee_usbdev_str, uart_config = XBeeUARTConfig.new, operation_mode = :AT, transmission_mode = :SYNC)
+
+    VERSION = "1.2.0" # Version of this class
+
+    ##
+    # ==== Attributes
+    # * +xbee_usbdev_str+ - USB Device as a string
+    #
+    # ==== Options
+    # * +uart_config+ - XBeeUARTConfig
+    # * +operation_mode+ - Either :AT or :API for XBee operation mode
+    # * +transmission_mode+ - :SYNC for Synchronous communication or :ASYNC for Asynchonrous communication.
+    #
+    # A note on the asynchronous vs synchronous communication modes - A
+    # simplistic network of a few XBee nodes can pretty much work according to
+    # expected flows where requests and responses are always handled in
+    # synchronous ways. However, if bigger radio networks are being deployed
+    # (real scenarios) you cannot guarantee the synchronous nature of the network.
+    # You will have nodes joining/removing themselves, sleeping, sending data
+    # samples etc. Although the default behaviour is set as :SYNC, if you have a
+    # real network, then by design the network is Asynchronous, use :ASYNC instead.
+    # Otherwise you will most definitely run into "Invalid responses" issues.
+    #
+    # For handling the Asynchronous communication logic, use an external Queue
+    # and database to effectively handle the command/response and other frames
+    # that are concurrently being conversed on the PAN.
+    #
+    # ==== Example
+    #   require 'ruby_xbee'
+    #   @uart_config = XBee::Config::XBeeUARTConfig.new()
+    #   @xbee_usbdev_str = '/dev/tty.usbserial-A101KYF6'
+    #   @xbee = XBee::BaseAPIModeInterface.new(@xbee_usbdev_str, @uart_config, :API, :ASYNC)
+    #
+    def initialize(xbee_usbdev_str, uart_config = XBeeUARTConfig.new, operation_mode = :API, transmission_mode = :SYNC)
       super(xbee_usbdev_str, uart_config, operation_mode, transmission_mode)
       @frame_id = 1
       if self.operation_mode == :AT
@@ -23,11 +54,14 @@ module XBee
     # Switch to API mode - note that in Series 2 the Operation Mode is defined
     # by the firmware flashed to the device. Only Series 1 can switch from
     # AT (Transparent) to API Opearation and back seamlessly.
+    #
+    # API Mode 1 - API Enabled
+    # API Mode 2 - API Enabled, with escaped control characters
     def start_apimode_communication
       in_command_mode do
         puts "Entering api mode"
         # Set API Mode 2 (include escaped characters)
-        self.xbee_serialport.write("ATAP2\r")
+        self.xbee_serialport.write("ATAP1\r")
         self.xbee_serialport.read(3)
       end
     end
@@ -35,10 +69,10 @@ module XBee
     def get_param(at_param_name, at_param_unpack_string = nil)
       frame_id = self.next_frame_id
       at_command_frame = XBee::Frame::ATCommand.new(at_param_name,frame_id,nil,at_param_unpack_string)
-      puts "Sending ... [#{at_command_frame._dump.unpack("C*").join(", ")}]"
-      self.xbee_serialport.write(at_command_frame._dump)
+      puts "Sending ... [#{at_command_frame._dump(self.api_mode.in_symbol).unpack("C*").join(", ")}]" if $VERBOSE
+      self.xbee_serialport.write(at_command_frame._dump(self.api_mode.in_symbol))
       if self.transmission_mode == :SYNC
-        r = XBee::Frame.new(self.xbee_serialport)
+        r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
         if r.kind_of?(XBee::Frame::ATCommandResponse) && r.status == :OK && r.frame_id == frame_id
           if block_given?
             yield r
@@ -60,10 +94,10 @@ module XBee
     def set_param(at_param_name, param_value, at_param_unpack_string = nil)
       frame_id = self.next_frame_id
       at_command_frame = XBee::Frame::ATCommand.new(at_param_name,frame_id,param_value,at_param_unpack_string)
-      # puts "Sending ... [#{at_command_frame._dump.unpack("C*").join(", ")}]"
-      self.xbee_serialport.write(at_command_frame._dump)
+      # puts "Sending ... [#{at_command_frame._dump(self.api_mode.in_symbol).unpack("C*").join(", ")}]"
+      self.xbee_serialport.write(at_command_frame._dump(self.api_mode.in_symbol))
       if self.transmission_mode == :SYNC
-      r = XBee::Frame.new(self.xbee_serialport)
+      r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
         if r.kind_of?(XBee::Frame::ATCommandResponse) && r.status == :OK && r.frame_id == frame_id
           if block_given?
             yield r
@@ -79,10 +113,10 @@ module XBee
     def get_remote_param(at_param_name, remote_address = 0x000000000000ffff, remote_network_address = 0xfffe, at_param_unpack_string = nil)
       frame_id = self.next_frame_id
       at_command_frame = XBee::Frame::RemoteCommandRequest.new(at_param_name, remote_address, remote_network_address, frame_id, nil, at_param_unpack_string)
-      puts "Sending ... [#{at_command_frame._dump.unpack("C*").join(", ")}]" 
-      self.xbee_serialport.write(at_command_frame._dump)
+      puts "Sending ... [#{at_command_frame._dump(self.api_mode.in_symbol).unpack("C*").join(", ")}]"
+      self.xbee_serialport.write(at_command_frame._dump(self.api_mode.in_symbol))
       if self.transmission_mode == :SYNC
-        r = XBee::Frame.new(self.xbee_serialport)
+        r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
         if r.kind_of?(XBee::Frame::RemoteCommandResponse) && r.status == :OK && r.frame_id == frame_id
           if block_given?
             yield r
@@ -98,10 +132,10 @@ module XBee
     def set_remote_param(at_param_name, param_value, remote_address = 0x000000000000ffff, remote_network_address = 0xfffe, at_param_unpack_string = nil)
       frame_id = self.next_frame_id
       at_command_frame = XBee::Frame::RemoteCommandRequest.new(at_param_name, remote_address, remote_network_address, frame_id, param_value, at_param_unpack_string)
-      puts "Sending ... [#{at_command_frame._dump.unpack("C*").join(", ")}]"
-      self.xbee_serialport.write(at_command_frame._dump)
+      puts "Sending ... [#{at_command_frame._dump(self.api_mode.in_symbol).unpack("C*").join(", ")}]"
+      self.xbee_serialport.write(at_command_frame._dump(self.api_mode.in_symbol))
       if self.transmission_mode == :SYNC
-        r = XBee::Frame.new(self.xbee_serialport)
+        r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
         if r.kind_of?(XBee::Frame::RemoteCommandResponse) && r.status == :OK && r.frame_id == frame_id
           if block_given?
             yield r
@@ -154,15 +188,15 @@ module XBee
       frame_id = self.next_frame_id
       # neighbors often takes more than 1000ms to return data
       node_discover_cmd = XBee::Frame::ATCommand.new("ND",frame_id,nil)
-      #puts "Node discover command dump: #{node_discover_cmd._dump.unpack("C*").join(", ")}"
+      #puts "Node discover command dump: #{node_discover_cmd._dump(self.api_mode.in_symbol).unpack("C*").join(", ")}"
       tmp = @xbee_serialport.read_timeout
       @xbee_serialport.read_timeout = Integer(self.node_discover_timeout.in_seconds * 1050)
-      @xbee_serialport.write(node_discover_cmd._dump)
+      @xbee_serialport.write(node_discover_cmd._dump(self.api_mode.in_symbol))
       responses = []
       #read_thread = Thread.new do
       begin
         loop do
-          r = XBee::Frame.new(self.xbee_serialport)
+          r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
           # puts "Got a response! Frame ID: #{r.frame_id}, Command: #{r.at_command}, Status: #{r.status}, Value: #{r.retrieved_value}"
           if r.kind_of?(XBee::Frame::ATCommandResponse) && r.status == :OK && r.frame_id == frame_id
             if r.retrieved_value.empty?
@@ -529,7 +563,7 @@ module XBee
     def reset!
       @xbee_serialport.write("ATFR\r")
     end
-    
+
     ##
     # Performs a network reset on one or more modules within a PAN. The module responds
     # immediately with an "OK" and then restarts the network. All network configuration
@@ -586,7 +620,7 @@ module XBee
     # echo is disabled by default
     def getresponse( echo = false )
       if echo == true
-        r = XBee::Frame.new(self.xbee_serialport)
+        r = XBee::Frame.new(self.xbee_serialport, self.api_mode.in_symbol)
       else
         getresults( @xbee_serialport, echo )
       end
@@ -603,6 +637,12 @@ module XBee
   end  # class Series1APIModeInterface
 
   class Series2APIModeInterface < BaseAPIModeInterface
-
+    ##
+    # Initiating the application firmware OTA upgrade for Programmable XBee modules
+    def init_ota_upgrade(password = nil, remote_address = 0x000000000000ffff, remote_network_address = 0xfffe)
+      frame_id = self.next_frame_id
+      command_frame = XBee::Frame::ExplicitAddressingCommand.new(frame_id, remote_address, remote_network_address, 0xE8, 0xE8, 0x1000, 0xC105, 0x00, 0x00, password)
+      self.xbee_serialport.write(command_frame._dump(self.api_mode.in_symbol))
+    end
   end # class Series2APIModeInterface
 end