emu_power 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 749cd7c9a9756e9154e204fd1f0429ec3bd847716edbaadd873e08a9d5c8d2f8
+  data.tar.gz: 21ac87685aa627635cd7e6e8fa9b2f18d12a5a570f50ca32f0da1ddd6c10236e
+SHA512:
+  metadata.gz: 1cfd81a5436476c76d45d163cf027958bb5550be01d69a0d3b71863d712d59a56d1e62059db70dc06d744257746887d7a9b49a0fd58ccfd8ae65f56e8f6df0a5
+  data.tar.gz: 0aec10ac51e7a084d968e60760aff1c693c0ee5d4b9677ae894ae07b41c2a493acb20460d8e0bef0b9a9a13588d61913a6bc7e263ed0ee35777b0532f74ba98f

data/lib/emu_power.rb

@@ -0,0 +1,7 @@
+class EmuPower
+end
+
+require 'emu_power/api'
+require 'emu_power/stream_parser'
+require 'emu_power/types'
+require 'emu_power/commands'

data/lib/emu_power/api.rb

@@ -0,0 +1,135 @@
+# API for communicating with the Rainforest EMU-2 monitoring
+# unit. This API is asynchronous, and allows event handlers
+# to be registered for the various message types.
+
+require 'emu_power/stream_parser'
+require 'emu_power/types'
+
+require 'serialport'
+require 'nokogiri'
+
+class EmuPower::Api
+
+	LINE_TERMINATOR = "\r\n"
+
+	# Initialize the serial connection and build notification histories
+	def initialize(tty, history_length = 10)
+
+		@port = SerialPort.new(tty, baud: 115200)
+
+		@histories = {}
+		@callbacks = {}
+		EmuPower::Types::Notification.subclasses.each do |n|
+			@histories[n] = Array.new(history_length)
+			@callbacks[n] = nil
+		end
+
+	end
+
+	# Register the callback for specific notification events. Expects
+	# a subclass of Types::Notification. If :global is passed for klass,
+	# the callback will be triggered for every event in addition to the
+	# normal callback. Note that only one callback may be registered
+	# per event - setting another will replace the existing one.
+	def callback(klass, &block)
+		@callbacks[klass] = block
+		return true
+	end
+
+	# Send a command to the device. Expects an instance of one of the
+	# command classes defined in commands.rb. The serial connection
+	# must be started before this can be used.
+	def issue_command(obj)
+		return false if @thread.nil?
+		return false unless obj.respond_to?(:to_command)
+		xml = obj.to_command
+		@port.write(xml)
+		return true
+	end
+
+	# Begin polling for serial data. We spawn a new thread to
+	# handle this so we don't block input. If blocking is set
+	# to true, this method blocks indefinitely. If false, it
+	# returns true and expects the caller to handle things.
+	def start_serial(interval: 1, blocking: true)
+
+		return false unless @thread.nil?
+
+		parser = construct_parser
+
+		@thread = Thread.new do
+			loop do
+				begin
+					parser.parse
+					sleep(interval)
+				rescue Nokogiri::XML::SyntaxError
+					# This means that we probably connected in the middle
+					# of a message, so just reset the parser.
+					parser = construct_parser
+				end
+			end
+		end
+
+		if blocking
+			@thread.join
+		else
+			return true
+		end
+
+	end
+
+	# Stop polling for data. Already-received objects will
+	# remain available.
+	def stop_serial
+		return false if @thread.nil?
+		@thread.terminate
+		@thread = nil
+		return true
+	end
+
+	# Get the full history buffer for a given notify type
+	def history_for(klass)
+		return @histories[klass].compact
+	end
+
+	# Get the most recent object for the given type
+	def current(klass)
+		return history_for(klass)[0]
+	end
+
+	private
+
+	# Handle the completed hash objects when notified by the parser
+	def handle_response(obj)
+
+		container = EmuPower::Types.construct(obj)
+
+		if container == nil
+			puts "BAD OBJECT #{obj}"
+		else
+			push_history(container)
+			@callbacks[container.class]&.call(container)
+			@callbacks[:global]&.call(container)
+		end
+
+	end
+
+	# Helper for initializing underlying parser
+	def construct_parser
+		return EmuPower::StreamParser.new(@port, LINE_TERMINATOR, EmuPower::Types.notify_roots) do |obj|
+			handle_response(obj)
+		end
+	end
+
+	# Helper for inserting object into appropriate history queue
+	def push_history(obj)
+		
+		type = obj.class
+
+		old = @histories[type].pop
+		@histories[type].prepend(obj)
+		return old
+
+	end
+
+end

data/lib/emu_power/commands.rb

@@ -0,0 +1,111 @@
+# Collection of command types for controlling various
+# functions on the EMU device.
+
+class EmuPower::Commands
+
+	# Base class that all commands inherit from
+	class Command
+
+		def initialize(name)
+			@data = { name: name }
+		end
+
+		def to_command
+
+			tags = @data.map do |k, v|
+				tag = k.to_s.capitalize
+				next "<#{tag}>#{v}</#{tag}>"
+			end
+
+			return "<Command>#{tags.join}</Command>"
+		end
+
+		# Convert bool to Y or N
+		def to_yn(bool)
+			return bool ? 'Y' : 'N'
+		end
+
+		# Convert int to 0xABCD hex
+		def to_hex(i, width = 8)
+			return "0x%0#{width}x" % i
+		end
+
+	end
+
+	class GetNetworkInfo < Command
+		def initialize
+			super('get_network_info')
+		end
+	end
+
+	class GetNetworkStatus < Command
+		def initialize
+			super('get_network_status')
+		end
+	end
+
+	class GetInstantaneousDemand < Command
+		def initialize
+			super('get_instantaneous_demand')
+		end
+	end
+
+	class GetPrice < Command
+		def initialize
+			super('get_price')
+		end
+	end
+
+	class GetMessage < Command
+		def initialize
+			super('get_message')
+		end
+	end
+
+	# TODO: Confirm Message
+
+	class GetCurrentSummation < Command
+		def initialize
+			super('get_current_summation')
+		end
+	end
+
+	# TODO: Get History Data
+
+	# Note: This doesn't seem to work. The command is issued successfully, but
+	# the EMU does not update any schedule info. This may be disallowed by the
+	# meter or something.
+	class SetSchedule < Command
+
+		EVENTS = %w[time message price summation demand scheduled_prices profile_data billing_period block_period]
+
+		def initialize(event, frequency, enabled)
+			super('set_schedule')
+			raise ArgumentError.new("Event must be one of #{EVENTS.join(', ')}") unless EVENTS.include?(event)
+			@data[:event] = event
+			@data[:frequency] = to_hex(frequency, 4)
+			@data[:enabled] = to_yn(enabled)
+		end
+
+	end
+
+	# TODO: Add event field
+	class GetSchedule < Command
+
+		EVENTS = %w[time message price summation demand scheduled_prices profile_data billing_period block_period]
+
+		def initialize(event = nil)
+
+			super('get_schedule')
+
+			unless event.nil?
+				raise ArgumentError.new("Event must be one of #{EVENTS.join(', ')}") unless EVENTS.include?(event)
+				@data[:event] = event
+			end
+
+		end
+	end
+
+	# TODO: Reboot
+
+end

data/lib/emu_power/stream_parser.rb

@@ -0,0 +1,118 @@
+# SAX parser implementation for processing a stream of
+# XML fragments.
+
+require 'nokogiri'
+
+class EmuPower::StreamParser < Nokogiri::XML::SAX::Document
+
+	FAKEROOT = 'FAKEROOT'
+
+	def initialize(io, line_terminator, roots, &block)
+
+		@line_terminator = line_terminator
+		@io = io
+
+		# Use a push parser so we can fake a single root element
+		@parser = Nokogiri::XML::SAX::PushParser.new(Parser.new(FAKEROOT, roots, &block))
+
+		# This is the "root" of the document. We intentionally never close this
+		# so that the parser doesn't get mad when it encounters multiple real
+		# root elements.
+		@parser << "<#{FAKEROOT}>"
+
+	end
+
+	# Push all new lines from the io into the parser. The parser
+	# will fire the callback given on construction once a whole
+	# object has been processed.
+	def parse
+		lines = @io.readlines(@line_terminator)
+		lines.each { |l| @parser << l }
+	end
+
+	# Nokogiri parser definition. Processes a flat XML
+	# stream with multiple roots.
+	class Parser < Nokogiri::XML::SAX::Document
+
+		# Initialize the set of root tags to consider
+		def initialize(fakeroot, roots, &block)
+
+			@roots = roots
+
+			@current_object = nil
+			@current_property = nil
+			@current_root = nil
+
+			@callback = block
+
+			# All element parsers ignore this tag. This is only
+			# used to persuade Nokogiri to parse multiple roots
+			# in a single stream without getting mad.
+			@fakeroot = fakeroot
+
+		end
+
+		# For each tag, initialize a root element if we don't already have
+		# one. Otherwise, consider it a property of the current element.
+		def start_element(name, attrs = [])
+
+			return if name == @fakeroot
+			return if @current_object == nil && !@roots.include?(name)
+
+			if @current_object == nil
+				@current_root = name
+				@current_object = { "MessageType" => name }
+			else
+				@current_property = name
+			end
+
+		end
+
+		# Populate the content of the current element
+		def characters(str)
+			if @current_object != nil && @current_property != nil
+
+				#cur = @current_object[@current_property]
+				#return if cur == str
+
+				# Wrap into array if we already have a value (XML permits duplicates)
+				#cur = [cur] unless cur == nil
+				
+				#if cur.kind_of?(Array)
+				#	cur << str
+				#else
+				#	cur = str
+				#end
+
+				#@current_object[@current_property] = cur
+
+				@current_object[@current_property] = str
+
+			end
+		end
+
+		# Close out the current tag and clear context
+		def end_element(name, attrs = [])
+
+			return if name == @fakeroot
+			
+			if @current_root == name
+
+				if @callback != nil
+					@callback.call(@current_object)
+				else
+					puts "DEBUG: #{@current_object}"
+				end
+				
+				@current_object = nil
+				@current_root = nil
+
+			elsif @current_object != nil
+				@current_property = nil
+			end
+
+		end
+
+	end
+
+end

data/lib/emu_power/types.rb

@@ -0,0 +1,143 @@
+# Notification types. Provides convenience calculators and
+# accessors for the notifications sent by the EMU device.
+class EmuPower::Types
+
+	# Base class for notifications
+	class Notification
+
+		UNIX_TIME_OFFSET = 946684800
+
+		attr_accessor :raw
+		attr_accessor :device_mac
+		attr_accessor :meter_mac
+		attr_accessor :timestamp
+
+		def initialize(hash)
+			@raw = hash
+			@device_mac = @raw['DeviceMacId']
+			@meter_mac = @raw['MeterMacId']
+			build(hash)
+		end
+
+		def build(hash)
+		end
+
+		# The EMU sets timestamps relative to Jan 1st 2000 UTC. We convert
+		# these into more standard Unix epoch timestamps by adding the
+		# appropriate offset.
+		def timestamp
+			ts = self.raw['TimeStamp']
+			return nil if ts == nil
+			return Integer(ts) + 946684800
+		end
+
+		def parse_hex(prop)
+			v = @raw[prop]
+			return nil if v.nil?
+			return Integer(v)
+		end
+		
+		def parse_bool(prop)
+			v = @raw[prop]
+			return nil if v.nil?
+			return (@raw[prop] == 'Y') ? true : false
+		end
+
+		# Name of the XML root object corresponding to this type
+		def self.root_name
+			return self.name.split('::').last
+		end
+
+		def self.subclasses
+			return ObjectSpace.each_object(::Class).select do |k|
+				k < self
+			end
+		end
+
+	end
+
+	class ConnectionStatus < Notification
+	end
+
+	class DeviceInfo < Notification
+	end
+
+	class ScheduleInfo < Notification
+	end
+
+	class MeterList < Notification
+	end
+
+	class MeterInfo < Notification
+	end
+
+	class NetworkInfo < Notification
+	end
+
+	class TimeCluster < Notification
+	end
+
+	class MessageCluster < Notification
+	end
+
+	class PriceCluster < Notification
+	end
+
+	class InstantaneousDemand < Notification
+
+		attr_accessor :raw_demand
+		attr_accessor :multiplier
+		attr_accessor :divisor
+		attr_accessor :digits_right
+		attr_accessor :digits_left
+		attr_accessor :suppress_leading_zeroes
+
+		def build(hash)
+			self.raw_demand = parse_hex('Demand')
+			self.multiplier = parse_hex('Multiplier')
+			self.divisor = parse_hex('Divisor')
+			self.digits_right = parse_hex('DigitsRight')
+			self.digits_left = parse_hex('DigitsLeft')
+			self.suppress_leading_zeroes = parse_bool('SuppressLeadingZero')
+		end
+
+		# Return computed demand in KW. This may return nil if data is missing.
+		def demand
+			return 0 if self.divisor == 0
+			return nil if self.multiplier.nil? || self.raw_demand.nil? || self.divisor.nil?
+			return self.multiplier * self.raw_demand / Float(self.divisor)
+		end
+
+	end
+
+	class CurrentSummationDelivered < Notification
+	end
+
+	class CurrentPeriodUsage < Notification
+	end
+
+	class LastPeriodUsage < Notification
+	end
+
+	class ProfileData < Notification
+	end
+
+	# Dispatch to the appropriate container class based
+	# on the type. Expects a data hash. Returns nil on
+	# bad message.
+	def self.construct(data)
+
+		type = data['MessageType']
+		return nil if type == nil || !notify_roots.include?(type)
+
+		klass = self.const_get(type)
+		return klass.new(data)
+
+	end
+
+	# Helper to get the element names of all types
+	def self.notify_roots
+		return Notification.subclasses.map(&:root_name)
+	end
+
+end

data/readme.md

@@ -0,0 +1 @@
+Placeholder readme

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: emu_power
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Steven Bertolucci
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: serialport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: This is an implementation of the XML API for the Rainforest EMU in ruby.
+email: srbertol@mtu.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/emu_power.rb
+- lib/emu_power/api.rb
+- lib/emu_power/commands.rb
+- lib/emu_power/stream_parser.rb
+- lib/emu_power/types.rb
+- readme.md
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6.2
+signing_key: 
+specification_version: 4
+summary: API for interfacing with the Rainforest EMU energy monitor.
+test_files: []