xap_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d218f4cd8c25a7216bbf37f0be337a1c6146f8d
+  data.tar.gz: 1a30d854e84114a1cae501a8148702b28418c01a
+SHA512:
+  metadata.gz: 6d1374d05a86b88265bfba24ed697e76a495c6afae3702421c8e7b366ffbdf94aff3bf3024ff6c3ee5bb9a132f2520ed13174ddf8917b83e47dd798abccf2cf3
+  data.tar.gz: 523b3a5c72fd055f868aa4333862c92986baedf01f4420bef5180e9d650e674d3e3a4b631878ccc831799937d45f20e4d86d3119ebc713dc54046a0bc1aaaec4

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.ruby-version
+.ruby-gemset

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in xap_ruby.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012-2016, Mike Bourgeous (and any Git contributors)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,59 @@
+xap\_ruby
+=========
+This gem provides basic xAP Automation protocol support for EventMachine
+applications.  It was developed for use in Nitrogen Logic controller software.
+There are no automated tests and the code could be improved in many ways, but it
+may still be useful to someone.
+
+This is a Ruby library written from scratch for communicating with a home
+automation network using the xAP protocol.  Supports sending and receiving
+arbitrary xAP messages, triggering callbacks on certain received messages,
+etc.  Also includes an implementation of an xAP Basic Status and Control
+device.  Incoming xAP messages are parsed using an ad-hoc parser based on
+Ruby's String#split() and Array#map() (a validating Treetop parser is also
+available).  Network events are handled using EventMachine.
+
+This library strives to support all address wildcard modes and data types
+specified by the xAP specification as correctly as possible.
+
+Read the examples under `test/` to understand how to create your own applications
+using xap\_ruby.  All user-facing classes should have documenting comments.
+
+xAP
+---
+xAP is a broadcast UDP protocol for interfacing disparate home automation
+systems and devices.  Despite its weaknesses, xAP support is available for many
+DIY and enthusiast automation systems.  For more information on xAP, visit
+http://www.xapautomation.org/.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'xap_ruby'
+```
+
+Testing and Examples
+--------------------
+There are no automated tests.  You can test the code by running
+test/bscdev\_test.rb to simulate an xAP BSC device, then running
+test/xap\_receive.sh and test/xap\_query.sh on another machine.
+
+* test/bsdev\_test.rb creates a dummy xAP Basic Status and Control device.
+* test/parser\_test.rb tests the Treetop parser with a variety of xAP data types.
+* test/xap\_query.sh uses netcat to send a network-wide xAP query message.
+* test/xap\_receive.rb prints all xAP messages received from the network.
+
+Users of xap\_ruby
+------------------
+Submit a pull request if you use this library somewhere and would like a
+mention here.
+
+* [Nitrogen Logic](http://www.nitrogenlogic.com/) - [Depth Camera Controller](http://www.nitrogenlogic.com/products/depth_controller.html)
+
+Copyright
+---------
+(C)2012-2017 Mike Bourgeous (and any Git contributors), licensed under
+two-clause BSD (see LICENSE)

data/Rakefile

@@ -0,0 +1,3 @@
+namespace :gem do
+  require "bundler/gem_tasks"
+end

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "xap_ruby"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start

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/lib/xap.rb

@@ -0,0 +1,30 @@
+# Basic class and function definitions for the xAP protocol
+# (C)2012-2016 Mike Bourgeous
+
+require 'eventmachine'
+require_relative 'xap_ruby'
+
+# Basic functions for working with the xAP protocol.
+module Xap
+	# Generates a random xAP UID of the form 'FF(01..FE)(01..FE)00'.
+	def self.random_uid
+		a = Random.rand(253) + 1
+		b = Random.rand(253) + 1
+		sprintf "FF%02X%02X00", a, b
+	end
+
+	# Prints a message using the global puts, prefixed with 'xAP: [time]'
+        # TODO: Use Logger
+	def self.log msg
+		puts "#{Time.now.strftime('%Y-%m-%d %H:%M:%S.%6N %z')} - xAP - #{msg}"
+	end
+end
+
+require_relative 'xap/parser'
+
+require_relative 'xap/xap_address'
+require_relative 'xap/xap_msg'
+require_relative 'xap/xap_dev'
+require_relative 'xap/xap_handler'
+
+require_relative 'xap/schema'

data/lib/xap/parser.rb

@@ -0,0 +1,6 @@
+module Xap
+	module Parser
+	end
+end
+
+require_relative 'parser/parse_xap'

data/lib/xap/parser/parse_xap.rb

@@ -0,0 +1,47 @@
+# Treetop parser for xAP messages
+# (C)2012 Mike Bourgeous
+#
+# References:
+# http://thingsaaronmade.com/blog/a-quick-intro-to-writing-a-parser-using-treetop.html
+# http://treetop.rubyforge.org/syntactic_recognition.html
+# http://treetop.rubyforge.org/using_in_ruby.html
+# http://www.xapautomation.org/index.php?title=Protocol_definition
+
+require 'treetop'
+require_relative 'xap_nodes'
+
+module Xap
+	module Parser
+		module ParseXap
+			path = File.expand_path(File.dirname(__FILE__))
+			Treetop.load(File.join(path, 'xap.treetop'))
+			@@parser = XapTreetopParser.new
+
+			# Returns a Treetop node tree for the given xAP message
+			def self.parse(data)
+				tree = @@parser.parse(data, :root => :message)
+
+				if !tree
+					raise Exception, "Parse error: #{@@parser.failure_reason.inspect} (index #{@@parser.index})"
+				end
+
+				tree
+			end
+
+			# Returns a hash that is equivalent to calling parse(data).to_hash(),
+			# but much faster.  However, this method does not do any explicit
+			# checking for invalid messages or values.
+			def self.simple_parse(data)
+				Hash[*data.split(/}\n?/).map {|v|
+					bl = v.split("\n{\n")
+					bl[1] = Hash[*bl[1].to_s.split("\n").map {|v2|
+						pair = v2.split(/[=!]/, 2)
+						pair[1] = [pair[1]].pack 'H*' if v2 =~ /^[^=!]+!/
+						pair
+					}.flatten!]
+					bl
+				}.flatten!(1)]
+			end
+		end
+	end
+end

data/lib/xap/parser/xap.treetop

@@ -0,0 +1,47 @@
+# Treetop grammar file for parsing xAP
+# (C)2012 Mike Bourgeous
+
+grammar XapTreetop
+	rule keyword
+		# The xAP message grammar in the spec doesn't say that periods
+		# can be included in keywords, but the example messages include
+		# periods in keywords.  TODO: handle odd number of hex digits
+		[-A-Za-z0-9_ ]+ ( '.' [-A-Za-z0-9_ ]+ )* <Keyword>
+	end
+
+	rule ascii
+		[^\n]* <AsciiValue>
+	end
+
+	rule hex
+		[A-Z0-9]* <HexValue>
+	end
+
+	rule space
+		[\s]+
+	end
+
+	rule eol
+		"\n"
+	end
+
+	rule value
+		delim:'=' val:ascii / delim:'!' val:hex <Value>
+	end
+
+	rule kvp
+		keyword value eol <KeyValuePair>
+	end
+
+	rule pairs
+		kvp* <Pairs>
+	end
+
+	rule block
+		keyword eol '{' eol pairs '}' eol <MessageBlock>
+	end
+
+	rule message
+		block* <Message>
+	end
+end

data/lib/xap/parser/xap_nodes.rb

@@ -0,0 +1,120 @@
+# Treetop node extensions for parsing xAP
+# (C)2012 Mike Bourgeous
+
+module XapTreetop
+	class Keyword < Treetop::Runtime::SyntaxNode
+	end
+
+	# When value in KVP is prefixed by =
+	class AsciiValue < Treetop::Runtime::SyntaxNode
+		def raw_value
+			self.text_value
+		end
+	end
+
+	# When value in KVP is prefixed by !
+	class HexValue < Treetop::Runtime::SyntaxNode
+		def raw_value
+			[self.text_value].pack 'H*'
+		end
+	end
+
+	class Value < Treetop::Runtime::SyntaxNode
+	end
+
+	class KeyValuePair < Treetop::Runtime::SyntaxNode
+		def key
+			keyword.text_value
+		end
+
+		def val
+			value.val.raw_value
+		end
+
+		def to_s
+			s = "#{key}"
+			if is_hex?
+				s << '!'
+			else
+				s << '='
+			end
+			s << value.val.text_value
+			s
+		end
+
+		def is_hex?
+			value.val.is_a? HexValue
+		end
+	end
+
+	class Pairs < Treetop::Runtime::SyntaxNode
+		def to_hash
+			h = {}
+			elements.each do |el|
+				if el.is_a? KeyValuePair
+					h[el.key] = el.val
+				end
+			end
+			h
+		end
+
+		def to_s
+			s = ''
+			elements.each do |el|
+				if el.is_a? KeyValuePair
+					s << "#{el.to_s}\n"
+				end
+			end
+			s
+		end
+	end
+
+	class MessageBlock < Treetop::Runtime::SyntaxNode
+		def name
+			keyword.text_value
+		end
+
+		def values
+			pairs.to_hash
+		end
+
+		def to_s
+			s = "#{keyword.text_value}\n{\n"
+			s << pairs.to_s
+			s << "}\n"
+			s
+		end
+	end
+
+	class Message < Treetop::Runtime::SyntaxNode
+		# Returns the name of the first message block
+		def first_block
+			elements.each do |el|
+				if el.is_a? MessageBlock
+					return el.keyword.text_value
+				end
+			end
+			nil
+		end
+
+		def to_hash
+			h = {}
+			elements.each do |el|
+				if el.is_a? MessageBlock
+					h[el.keyword.text_value] = el.values
+				end
+			end
+			h
+		end
+
+		def to_s
+			s = ""
+			elements.each do |el|
+				if el.is_a? MessageBlock
+					s << el.to_s
+				end
+			end
+			s
+		end
+	end
+end

data/lib/xap/schema.rb

@@ -0,0 +1,7 @@
+module Xap
+	module Schema
+	end
+end
+
+require_relative 'schema/xap_bsc'
+require_relative 'schema/xap_bsc_device'

data/lib/xap/schema/xap_bsc.rb

@@ -0,0 +1,416 @@
+# Support for the xAP Basic Status and Control schema.
+# (C)2012 Mike Bourgeous
+#
+# References:
+# http://www.xapautomation.org/index.php?title=Basic_Status_and_Control_Schema
+
+module Xap
+	module Schema
+		class XapBscBlock
+			attr_accessor :state, :level, :text, :display_text, :id
+
+			# is_input - Whether this is an input block or an output block
+			# index - If not nil, the block's index (0-based)
+			# hash - The block's hash of key-value pairs from @blocks -- this will
+			# be modified to
+			def initialize is_input, index, hash
+				@is_input = is_input
+				@index = index
+				@hash = hash
+
+				@hash.clone.each do |k, v|
+					case k.downcase
+					when 'state'
+						@hash.delete k
+						set_state v
+					when 'level'
+						@hash.delete k
+						set_level v
+					when 'text'
+						@hash.delete k
+						self.text = v
+					when 'displaytext'
+						@hash.delete k
+						self.display_text = v
+					when 'id'
+						@hash.delete k
+						self.id = v.upcase
+					end
+				end
+			end
+
+			# Sets this block's State field.  Once the state is set, it cannot be
+			# unset, only changed.  Pass true for 'ON', false for 'OFF', 'toggle'
+			# for 'toggle', or nil or any other value for '?'.
+			def state= s
+				@state = s
+				@hash['State'] = case s
+						 when true
+							 'ON'
+						 when false
+							 'OFF'
+						 else
+							 if s.is_a?(String) && s.downcase == 'toggle'
+								 @state = 'toggle'
+								 'toggle'
+							 else
+								 @state = '?'
+								 '?'
+							 end
+						 end
+			end
+
+			# Sets this block's Level field.  Once the level is set, it cannot be
+			# unset, only changed.  Examples: pass [ 1, 5 ] to specify '1/5'.  Pass
+			# [ 35, '%' ] to specify '35%'.  Pass [ 25 ] to specify 25 in an
+			# endpoint's native range.
+			def level= num_denom_array
+				raise 'num_denom_array must be an Array.' unless num_denom_array.is_a? Array
+				numerator, denominator = num_denom_array
+				@level = [ numerator, denominator ]
+				if denominator == '%'
+					@hash['Level'] = "#{numerator.to_i}%"
+				else
+					@hash['Level'] = "#{numerator.to_i}/#{denominator.to_i}"
+				end
+			end
+
+			# Sets this block's Text field.  Once the text is set, it cannot be
+			# unset, only changed.
+			def text= t
+				raise 'Text must not include newlines.' if t.include? "\n"
+				@text = t
+				@hash['Text'] = t
+			end
+
+			# Sets this block's DisplayText field.  Once the display text is set,
+			# it cannot be unset, only changed.
+			def display_text= t
+				raise 'Display text must not include newlines.' if t.include? "\n"
+				@display_text = t
+				@hash['DisplayText'] = t
+			end
+
+			# Sets this block's ID field.  The given ID must be a String containing
+			# either two uppercase hex digits or a single asterisk.  Once the ID is
+			# set, it cannot be unset, only changed.
+			def id= i
+				raise 'ID must be two uppercase hex digits or *.' unless i =~ /^([0-9A-Z][0-9A-Z]|\*)$/
+				@id = i
+				@hash['ID'] = i
+			end
+
+			# Returns 'input.state(.nn)' for input messages, 'output.state(.nn)' for output messages
+			def blockname
+				s = @is_input ? 'input.state' : 'output.state'
+				s << ".#{@index + 1}" if @index
+				s
+			end
+
+			# Returns a human-readable string description of this block.
+			def inspect
+				"Name: #{blockname} ID: #{id} State: #{state} Level: #{level} Text: #{text} DisplayText: #{display_text}"
+			end
+
+			protected
+			# Sets state based on the state text: "ON", "OFF", or "?"
+			def set_state s
+				case s.upcase
+				when 'ON'
+					self.state = true
+				when 'OFF'
+					self.state = false
+				when 'TOGGLE'
+					self.state = 'toggle'
+				when '?'
+					self.state = '?'
+				else
+					# Don't set state for anything else
+				end
+			end
+
+			# Sets level based on the level text: "x%", "y/z"
+			def set_level l
+				if l.include? '/'
+					self.level = l.split('/').map { |v| v.to_i }
+				elsif l.end_with? '%'
+					self.level = [ l.to_i, '%' ]
+				else
+					self.level = [ l.to_i ]
+				end
+			end
+		end
+
+		class XapBscMessage < XapUnsupportedMessage
+			def self.parse hash
+				self.new hash, nil, nil, nil, nil
+			end
+
+			def initialize msgclass, src_addr, src_uid, target_addr, is_input
+				super msgclass, src_addr, src_uid, target_addr
+
+				if msgclass.is_a?(Hash)
+					raise 'xAP BSC messages must have at least one block' if @blocks.length == 0
+					@is_input = @blocks.keys[0].downcase.start_with? 'input'
+				else
+					@is_input = is_input
+				end
+
+				@bsc_blocks = []
+				idx = 0
+				@blocks.each do |k, v|
+					kdown = k.downcase
+					if kdown.start_with?('input') || kdown.start_with?('output')
+						@bsc_blocks << XapBscBlock.new(@is_input, idx, v)
+					end
+					idx += 1 if idx
+				end
+			end
+
+			# Returns a human-readable string description of this message.
+			def inspect
+				s = "#{self.class.name}: #{@bsc_blocks.length} blocks recognized, #{@blocks.length} total\n"
+				s << "Blocks: \n"
+				@bsc_blocks.each do |blk|
+					s << "\t#{blk.inspect}\n"
+				end
+				s << "Regenerated message:\n\t"
+				s << super.lines.to_a.join("\t")
+			end
+
+			# Yields each XapBscBlock in sequence.
+			def each_block &block
+				@bsc_blocks.each do |b|
+					yield b
+				end
+			end
+		end
+
+		class XapBscCommand < XapBscMessage
+			register_class self, 'xAPBSC.cmd'
+
+			# Initializes an xAP BSC command message with the given source address
+			# and UID and target address.  Any subsequent arguments are ignored.
+			def initialize src_addr, src_uid, target_addr, *args
+				if src_addr.is_a?(Hash)
+					super src_addr, src_uid, nil, nil, nil
+				else
+					super 'xAPBSC.cmd', src_addr, src_uid, target_addr, false
+				end
+				raise 'All xAP BSC command messages must have a target address.' if @target_addr.nil?
+				check_block 0
+			end
+
+			# Gets the State value of the index-th block (0-based).  Returns true
+			# for 'ON', false for 'OFF', 'toggle' for 'toggle', '?' for '?' or any
+			# other value, and nil for undefined.  Throws an error if index is out
+			# of range.
+			def get_state index
+				@bsc_blocks[index].state
+			end
+
+			# Sets the State value of the index-th block (0-based).  Pass true for
+			# 'ON', false for 'OFF', 'toggle' for 'toggle', or any other value for
+			# '?'.  The block will be created if it is not present.  It is up to
+			# the caller to avoid creating gaps in the block indexes.
+			def set_state index, value
+				check_block index
+				@bsc_blocks[index].state = value
+			end
+
+			# Gets the Level value of the index-th block (0-based).  Returns an
+			# array with the numerator and '%' if the message contains a percentage
+			# level, the numerator and denominator if the message contains a ranged
+			# level, or just the numerator if the message contains a non-ranged
+			# level.  Throws an error if index is out of range.
+			def get_level index
+				@bsc_blocks[index].level
+			end
+
+			# Sets the Level value of the index-th block (0-based).  The value
+			# parameter must be an array containing the numerator and '%' for a
+			# percentage level, the numerator and the denominator for a ranged
+			# level, or the numerator alone for command messages that will set an
+			# endpoint's level using its native range.  The block will be created
+			# if it is not present.  It is up to the caller to avoid creating gaps
+			# in the block indexes.
+			def set_level index, value
+				check_block index
+				@bsc_blocks[index].level = value
+			end
+
+			# Gets the Text value of the index-th block (0-based).  Throws an error
+			# if index is out of range.
+			def get_text index
+				@bsc_blocks[index].text
+			end
+
+			# Sets the Text value of the index-th block (0-based).  The block will
+			# be created if it is not present.  It is up to the caller to avoid
+			# creating gaps in the block indexes.
+			def set_text index, value
+				check_block index
+				@bsc_blocks[index].text = value
+			end
+
+			# Gets the DisplayText value of the index-th block (0-based).  Throws an error
+			# if index is out of range.
+			def get_display_text index
+				@bsc_blocks[index].display_text
+			end
+
+			# Sets the DisplayText value of the index-th block (0-based).  The block will
+			# be created if it is not present.  It is up to the caller to avoid
+			# creating gaps in the block indexes.
+			def set_display_text index, value
+				check_block index
+				@bsc_blocks[index].display_text = value
+			end
+
+			# Gets the ID value of the index-th block (0-based).  Throws an error
+			# if index is out of range.
+			def get_id index
+				@bsc_blocks[index].id
+			end
+
+			# Sets the ID value of the index-th block (0-based).  The ID given must
+			# be either two uppercase hex digits or a single asterisk.  The block
+			# will be created if it is not present.  It is up to the caller to
+			# avoid creating gaps in the block indexes.
+			def set_id index, value
+				check_block index
+				@bsc_blocks[index].id = value
+			end
+
+			private
+			def check_block index
+				unless @bsc_blocks[index]
+					h = {}
+					blk = XapBscBlock.new @is_input, index, h
+					@bsc_blocks[index] = blk
+					@blocks[blk.blockname] = h
+				end
+			end
+		end
+
+		class XapBscQuery < XapBscMessage
+			register_class self, 'xAPBSC.query'
+
+			# Initializes an xAP BSC query message with the given source address
+			# and UID and target address.  Any subsequent arguments are ignored.
+			def initialize src_addr, src_uid, target_addr, *args
+				if src_addr.is_a?(Hash)
+					super src_addr, src_uid, nil, nil, nil
+				else
+					super 'xAPBSC.query', src_addr, src_uid, target_addr
+					@blocks['request'] = {}
+				end
+				raise 'All xAP BSC query messages must have a target address.' if @target_addr.nil?
+			end
+		end
+
+		# Shared functionality between info and event messages.
+		class XapBscResponse < XapBscMessage
+			attr_accessor :state, :level, :text, :display_text
+
+			# Initializes an xAP BSC event or info message with the given source
+			# address and UID.  If is_input is truthy, this will be an input.state
+			# message; if is_input is falsy, this will be an output.state message.
+			# Any subsequent arguments are ignored.
+			def initialize src_addr, src_uid, is_input, *args
+				if src_addr.is_a?(Hash)
+					super src_addr, src_uid, nil, nil, nil
+				else
+					super self.class.classname, src_addr, src_uid, nil, is_input
+					@is_input = !!is_input
+
+					h = {}
+					blk = XapBscBlock.new @is_input, nil, h
+					@bsc_blocks[0] = blk
+					@blocks[blk.blockname] = h
+				end
+			end
+
+			# Sets the State field in the message's (input|output).status block.
+			# Once the state is set, it cannot be unset, only changed.  Pass true
+			# for 'ON', false for 'OFF', 'toggle' for 'toggle', or nil for '?'.
+			def state= s
+				raise 'Do not use State=toggle for response messages.' if s.is_a?(String) && s.casecmp('toggle') == 0
+				@bsc_blocks[0].state = s
+			end
+
+			# Sets the Level field in the message's (input|output).status block.
+			# Once the level is set, it cannot be unset, only changed.  xAPBSC.info
+			# and xAPBSC.event messages should not use percentage or non-ranged
+			# responses.  Example: pass [ 1, 5 ] to specify '1/5'.
+			def level= num_denom_array
+				if num_denom_array[1] == nil || num_denom_array[1] == '%'
+					raise "Do not use percentages or non-ranged levels for response messages (#{num_denom_array})."
+				end
+				@bsc_blocks[0].level = num_denom_array
+			end
+
+			# Sets the Text field in the message's (input|output).status block.
+			# Once the text is set, it cannot be unset, only changed.
+			def text= t
+				@bsc_blocks[0].text = t
+			end
+
+			# Sets the DisplayText field in the message's (input|output).status
+			# block.  Once the display text is set, it cannot be unset, only
+			# changed.
+			def display_text= t
+				@bsc_blocks[0].display_text = t
+			end
+
+			# Gets the message's State value.  Returns true for 'ON', false for
+			# 'OFF', 'toggle' for 'toggle', '?' for '?' or any other value, and nil
+			# for undefined.
+			def state
+				@bsc_blocks[0].state
+			end
+
+			# Gets the Level value, if any.  Returns a two-element array with the
+			# numerator and '%' if the message contains a percentage level, or the
+			# numerator and denominator if the message contains a ranged level.
+			def level
+				@bsc_blocks[0].level
+			end
+
+			# Gets the message's Text value, if any.
+			def text
+				@bsc_blocks[0].text
+			end
+
+			# Gets the message's DisplayText value, if any.
+			def display_text
+				@bsc_blocks[0].display_text
+			end
+		end
+
+		class XapBscEvent < XapBscResponse
+			@@classname = 'xAPBSC.event'
+			register_class self, @@classname
+
+			def self.classname
+				@@classname
+			end
+		end
+
+		# The xAP standard seems kind of silly for having separate info and event
+		# messages, especially since info messages may be sent at device startup, and
+		# the result of a command message must be an info message if the command
+		# message didn't change anything, or an event message otherwise.  Overall, the
+		# xAP protocol is excessively chatty.  But, it seems a lot of DIY home
+		# automation systems support it, so it's best to use the weak protocol you have
+		# rather than the perfect one you don't.
+		class XapBscInfo < XapBscResponse
+			@@classname = 'xAPBSC.info'
+			register_class self, @@classname
+
+			def self.classname
+				@@classname
+			end
+		end
+	end
+end