simms 1.0.0

data/.rspec

@@ -0,0 +1 @@
+--require <%= File.join(File.expand_path(File.dirname(__FILE__)), 'spec', 'spec_helper.rb') %>

data/History.txt

@@ -0,0 +1,7 @@
+== 1.0.0 / 2012-03-02
+
+* Initial revision
+* Support for stream bytes parsing
+* Support for packet parsing
+* Support for global config, electricity config and electricity data beacons
+* Full rspec coverage

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Irongaze Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,60 @@
+= GEM: simms
+
+Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
+
+Based on sample PHP code and documentation provided by Simms Energy (http://simmsenergy.com)
+
+Funding for development provided by Sustainable Industrial Solutions LLC (http://sustainableis.com)
+
+== DESCRIPTION
+
+A set of classes to enable reading posted data from Simms Energy monitoring products (http://simmsenergy.com)
+
+== SYNOPSIS
+
+This gem facilitates interpreting incoming monitoring data and converting it into Ruby objects for easier
+manipulation.  It handles parsing the byte-stream of mesh data Simms devices provide, including
+conversion of hex byte-codes into Ruby native data types such as integers, bools and floats.
+
+To use:
+
+    # Require the library (not needed if using Rails/bundler)
+    >> require 'simms'
+    
+    # Parse a packet to extract the contained beacon, passing in
+    # the timestamp and data posted to your server from the Simms device
+    >> beacon = Simms::Packet.parse(params['DateTime'], params['MeshData'])
+
+    # Which device sent this beacon?
+    >> beacon.uuid
+    => '0A-28-00-48-27-88'
+
+    # See what kind of beacon we have
+    >> beacon.group
+    => :electric
+    >> beacon.type
+    => :data
+    >> beacon.data?
+    => true
+    
+    # Extract some data from the beacon
+    >> beacon.phase
+    => 0
+    >> beacon.accumulated_real_energy
+    => 15290
+    >> beacon.present_real_power
+    => 472.08821
+    
+== REQUIREMENTS
+
+None, though you'll need rspec to build and test the gem
+
+== INSTALL
+
+To install, simply run:
+
+    sudo gem install simms
+    
+RVM users can skip the sudo:
+  
+    gem install simms

data/Version.txt

@@ -0,0 +1 @@
+1.0.0

data/lib/simms.rb

@@ -0,0 +1,8 @@
+# Load our dependencies
+#require 'iron/extensions'
+
+# Requires all classes
+search_path = File.join(File.expand_path(File.dirname(__FILE__)), '*', '*.rb')
+Dir.glob(search_path) do |path|
+  require path
+end

data/lib/simms/beacon.rb

@@ -0,0 +1,81 @@
+# Represents the data or configuration information broadcast by a single Simms monitoring
+# device.  
+module Simms
+  class Beacon
+    
+    # Attributes
+    attr_accessor :uuid, :timestamp, :command_group_id, :device_command_id
+    
+    # Command group codes
+    CG_GLOBAL =     0xFFFF
+    CG_SENSOR =     0x0001
+    CG_ELECTRIC =   0x0002
+    CG_HVAC =       0x0004
+    CG_PULSER =     0x0005
+    CG_IRRIGATION = 0x0007
+
+    # Device commands
+    DC_DATA =           0x0001
+    DC_GLOBAL_CONFIG =  0x000B
+    DC_CONFIG =         0x0022
+    
+    # Find the appropriate beacon class for a given group + command tuple
+    def self.class_for(group, command)
+      case group
+        
+      when CG_GLOBAL then
+        case command
+        when DC_GLOBAL_CONFIG then
+          return Simms::GlobalConfigBeacon
+        end
+        
+      when CG_ELECTRIC then
+        case command
+        when DC_DATA then
+          return Simms::ElectricityDataBeacon
+        when DC_CONFIG then
+          return Simms::ElectricityConfigBeacon
+        end
+        
+      end
+      
+      # None found!
+      nil
+    end
+    
+    def initialize(bytes)
+      @bytes = bytes
+    end
+
+    def group
+      case @command_group_id
+      when CG_GLOBAL then :global
+      when CG_SENSOR then :sensor
+      when CG_ELECTRIC then :electric
+      when CG_HVAC then :hvac
+      when CG_PULSER then :pulser
+      when CG_IRRIGATION then :irrigation
+      else
+        :unknown
+      end
+    end
+    
+    def type
+      case @device_command_id
+      when DC_DATA then :data
+      when DC_CONFIG, DC_GLOBAL_CONFIG then :config
+      else
+        :unknown
+      end
+    end
+    
+    def data?
+      type == :data
+    end
+    
+    def config?
+      type == :config
+    end
+
+  end
+end

data/lib/simms/bytes.rb

@@ -0,0 +1,73 @@
+# Manages a set of byte codes in hex string format (eg 'AF', '0C', etc) and
+# provides methods for extracting floats, ints, etc from that stream by
+# position.
+#
+# Responsible for low-level translation of incoming data into types usable
+# in Ruby.
+module Simms
+  class Bytes
+
+    attr_accessor :data
+   
+    def initialize(byte_array)
+      @data = byte_array
+      @data = @data.to_s.scan(/../) unless @data.is_a?(Array)
+    end
+    
+    def count
+      @data.count
+    end
+    
+    def empty?
+      count == 0
+    end
+    
+    def uint8(pos)
+      @data[pos].hex
+    end
+    
+    def uint16(pos)
+      @data[pos...pos+2].reverse.join('').hex
+    end
+    
+    def sint16(pos)
+      [@data[pos...pos+2].join].pack('H*').unpack('s').first
+    end
+    
+    def uint32(pos)
+      @data[pos...pos+4].reverse.join('').hex
+    end
+    
+    def sint32(pos)
+      [@data[pos...pos+4].join].pack('H*').unpack('l').first
+    end
+    
+    def bool(pos)
+      @data[pos].hex == 1
+    end
+    
+    def float(pos)
+      v = uint32(pos)
+      x = (v & ((1 << 23) - 1)) + (1 << 23) * (v >> 31 | 1)
+	    exp = (v >> 23 & 0xFF) - 127
+	    return x.to_f * (2 ** (exp - 23))
+    end
+    
+    def slice(*args)
+      Bytes.new(@data.slice(*args))
+    end
+    
+    def [](*args)
+      Bytes.new(@data[*args])
+    end
+    
+    def calc_checksum
+      @data.inject(0) {|sum, byte| sum + byte.hex} % 0xFF
+    end
+    
+    def to_s
+      @data.join('')
+    end
+    
+  end
+end

data/lib/simms/electricity_config_beacon.rb

@@ -0,0 +1,34 @@
+require 'simms/beacon'
+
+module Simms
+  class ElectricityConfigBeacon < Simms::Beacon
+
+    def ct_amps
+      @bytes.uint16(6)
+    end
+    
+    def nominal_voltage
+      @bytes.uint16(8)
+    end
+    
+    def phase_type
+      @bytes.uint8(10)
+    end
+    
+    # Human-readable description of the phase type
+    def phase_type_description
+      case phase_type
+      when 0 then
+        '3 Phase With Neutral, Display L-N'
+      when 1 then
+        '3 Phase With Neutral, Display L-L'
+      when 2 then
+        'Single Split Phase A+B with Neutral, Display L-N'
+      when 3 then 
+        'Single Phase A to Neutral, Display L-N'
+      else
+        'Unknown phase type!'
+      end
+    end
+  end
+end

data/lib/simms/electricity_data_beacon.rb

@@ -0,0 +1,70 @@
+require 'simms/beacon'
+
+# Electricity data beacons are sent at the time interval configured in the device, and will be
+# have one packet sent per phase being monitored, ie for a 3-phase system, you will receive
+# 3 data beacons per reporting interval per device, with the phase field set to 0, 1, or 2.
+module Simms
+  class ElectricityDataBeacon < Simms::Beacon
+
+    # Which phase this beacon represents
+    def phase
+      @bytes.uint8(6)
+    end
+    
+    # TODO What does this mean?  What are the valid values?
+    def error_state
+      @bytes.uint8(7)
+    end
+    
+    # May be negative, as in the case of a solar power installation.  Is a counter, ie to get
+    # the real energy (Wh) for a given interval, you need to diff against past values
+    def accumulated_real_energy
+      @bytes.sint32(8)
+    end
+    
+    # In Wh - see #accumulated_real_energy for counter info
+    def accumulated_apparent_energy
+      @bytes.sint32(12)
+    end
+    
+    # In W
+    def present_real_power
+      @bytes.float(16)
+    end
+    
+    # In W
+    def present_apparent_power
+      @bytes.float(20)
+    end
+    
+    def volts_rms
+      @bytes.float(24)
+    end
+    
+    def current_rms
+      @bytes.float(28)
+    end
+    
+    # In VA
+    def power_factor
+      @bytes.float(32)
+    end
+
+    def max_demand
+      @bytes.float(36)
+    end
+    
+    def volts_sag
+      @bytes.uint16(40)
+    end
+    
+    def volts_peak
+      @bytes.uint16(42)
+    end
+    
+    def current_peak
+      @bytes.uint16(44)
+    end
+
+  end
+end

data/lib/simms/global_config_beacon.rb

@@ -0,0 +1,29 @@
+require 'simms/beacon'
+
+module Simms
+  class GlobalConfigBeacon < Simms::Beacon
+    
+    def version_high
+      @bytes.uint16(6)
+    end
+    
+    def version_low
+      @bytes.uint16(8)
+    end
+    
+    def firmware_version
+      "#{version_high}.#{version_low}"
+    end
+    
+    def local_devices
+      @bytes.uint16(10)
+    end
+    
+    def device_name
+      name = ''
+      @bytes.slice(24,16).data.collect {|b| b.hex}.each {|c| name << c if c > 0}
+      name
+    end
+    
+  end
+end

data/lib/simms/packet.rb

@@ -0,0 +1,53 @@
+module Simms
+  class Packet
+    
+    # Action type constants
+    ACTION_BEACON = 0x35
+    
+    # Parses an incoming packet, extracts its enclosed beacon data, instantiates
+    # the correct beacon class, and returns it.  Raises exceptions on malformed data.
+    # If beacon type is unknown, raises an exception if raise_on_unknown is set to true.  Otherwise,
+    # unknown beacons are returned as nil.
+    def self.parse(timestamp, data_packet, raise_on_unknown = false)
+      # Parse the string into hex pair bytes for the mesh packet
+      mesh_data = Bytes.new(data_packet)
+      
+      # Extract the bytes for the embedded beacon data
+      beacon_data = mesh_data[34..-1]
+      
+      # Verify data
+      if mesh_data.empty? || beacon_data.empty?
+        raise "Malformed packet - missing segments"
+      end
+      unless mesh_data.uint16(32) == beacon_data.count
+        raise "Malformed packet - length field (#{mesh_data.uint16(32)}) does not match data length (#{beacon_data.count})"
+      end
+      
+      # Parse timestamp - always UTC time
+      timestamp = Time.utc(*(timestamp.split(/[\- \:]/)))
+      
+      # Get key variables from packet
+      uuid = mesh_data.slice(6,6).data.join('-')
+      group = beacon_data.uint16(0)
+      command = beacon_data.uint8(2)
+      action = beacon_data.uint8(3)
+      
+      # Instantiate beacon instance (assuming it's a beacon action!)
+      klass = Simms::Beacon.class_for(group, command) if action == ACTION_BEACON
+      if klass
+        # Create the beacon, then set all the meta-info we have about it
+        beacon = klass.new(beacon_data)
+        beacon.command_group_id = group
+        beacon.device_command_id = command
+        beacon.timestamp = timestamp
+        beacon.uuid = uuid
+        beacon
+        
+      else        
+        raise "Unable to find beacon class for group #{group} and command #{command}" if raise_on_unknown
+        nil
+      end
+    end
+    
+  end
+end

data/spec/simms/beacon_spec.rb

@@ -0,0 +1,136 @@
+
+describe Simms::Beacon do
+
+  SAMPLE_TIMESTAMP = '2012-06-27 16:16:08'
+  SAMPLE_GC_BEACON = 'FB10040002000015ABA0B0220100FF00FF00FFFFFFFFFFFF0100790E937900022A00FFFF0B351A820000C8000100040002000015ABA0B022010053696D6D734F666669636550616E656C0000'
+  SAMPLE_EC_BEACON = 'FB10040002000015ABA0B0250100FF00FF00FFFFFFFFFFFF0100AA72704C00020D00020022359FCA960078000300D3'
+  SAMPLE_ED_BEACON = 'FB10040002000015ABA0B0220100FF00FF00FFFFFFFFFFFF01008E51CB1C00022E0002000135E58900014EF722004308280041E91144132620442D5EF542D417A740B43D693F8C8820447A007A000500'
+  
+  it 'should return the correct class for a given group + command combo' do
+    {
+      [0xFFFF, 0x0B] => Simms::GlobalConfigBeacon,
+      [0x0002, 0x01] => Simms::ElectricityDataBeacon,
+      [0x0002, 0x22] => Simms::ElectricityConfigBeacon
+    }.each do |info, klass|
+      Simms::Beacon.class_for(*info).should == klass
+    end
+  end
+  
+  context 'when a global configuration beacon' do
+    before do
+      @beacon = Simms::Packet.parse(SAMPLE_TIMESTAMP, SAMPLE_GC_BEACON)
+    end
+    
+    it 'should know what kind of beacon it is' do
+      @beacon.group.should == :global
+      @beacon.type.should == :config
+      @beacon.config?.should be_true
+    end
+    
+    it 'should extract firmware version' do
+      @beacon.firmware_version.should == '0.200'
+    end
+    
+    it 'should extract local device count' do
+      @beacon.local_devices.should == 1
+    end
+    
+    it 'should extract device name' do
+      @beacon.device_name.should == 'SimmsOfficePanel'
+    end
+  end
+
+  context 'when an electricity configuration beacon' do
+    before do
+      @beacon = Simms::Packet.parse(SAMPLE_TIMESTAMP, SAMPLE_EC_BEACON)
+    end
+    
+    it 'should know what kind of beacon it is' do
+      @beacon.group.should == :electric
+      @beacon.type.should == :config
+      @beacon.config?.should be_true
+    end
+    
+    it 'should extract CT clamp amps' do
+      @beacon.ct_amps.should == 150
+    end
+    
+    it 'should extract nominal voltage' do
+      @beacon.nominal_voltage.should == 120
+    end
+    
+    it 'should extract phase type' do
+      @beacon.phase_type.should == 3
+    end
+    
+    it 'should provide a user-readable phase type' do
+      @beacon.phase_type_description.should == 'Single Phase A to Neutral, Display L-N'
+    end
+  end
+  
+  context 'when an electricity data beacon' do
+    before do
+      @beacon = Simms::Packet.parse(SAMPLE_TIMESTAMP, SAMPLE_ED_BEACON)
+    end
+
+    it 'should know what kind of beacon it is' do
+      @beacon.group.should == :electric
+      @beacon.type.should == :data
+      @beacon.data?.should be_true
+    end
+    
+    it 'should extract the phase' do
+      @beacon.phase.should == 0
+    end
+    
+    it 'should extract the error state' do
+      @beacon.error_state.should == 1
+    end
+    
+    it 'should extract the accumulated real energy (Wh)' do
+      @beacon.accumulated_real_energy.should == 2291534
+    end
+    
+    it 'should extract the accumulated apparent energy' do
+      @beacon.accumulated_apparent_energy.should == 2623555
+    end
+    
+    it 'should extract the present real power' do
+      @beacon.present_real_power.round(4).should == 583.6446
+    end
+    
+    it 'should extract the present apparent power' do
+      @beacon.present_apparent_power.round(4).should == 640.5949
+    end
+    
+    it 'should extract the volts rms' do
+      @beacon.volts_rms.round(4).should == 122.6839
+    end
+    
+    it 'should extract the current rms' do
+      @beacon.current_rms.round(4).should == 5.2217
+    end
+    
+    it 'should extract the power factor' do
+      @beacon.power_factor.round(4).should == 0.9111
+    end
+    
+    it 'should extract the max demand' do
+      @beacon.max_demand.round(4).should == 642.1335
+    end
+    
+    it 'should extract the volts sag' do
+      @beacon.volts_sag.should == 122
+    end
+
+    it 'should extract the volts peak' do
+      @beacon.volts_peak.should == 122
+    end
+
+    it 'should extract the current peak' do
+      @beacon.current_peak.should == 5
+    end
+
+  end
+
+end

data/spec/simms/bytes_spec.rb

@@ -0,0 +1,47 @@
+describe Simms::Bytes do
+  
+  it 'should manage a set of byte strings' do
+    bytes = bytes('010200ABCD')
+    bytes.count.should == 5
+    bytes.data.last.should == 'CD'
+  end
+  
+  it 'should extract unsigned 8 bit ints' do
+    bytes('01').uint8(0).should == 1
+    bytes('AC').uint8(0).should == 172
+    bytes('FF').uint8(0).should == 255
+  end
+  
+  it 'should extract unsigned 16 bit ints' do
+    bytes('0400').uint16(0).should == 4
+    bytes('0000').uint16(0).should == 0
+    bytes('FFFF').uint16(0).should == 65535
+  end
+  
+  it 'should extract unsigned 32 bit ints' do
+    bytes('4EF72200').uint32(0).should == 2291534
+    bytes('FFFFFFFF').uint32(0).should == 4294967295
+  end
+  
+  it 'should extract signed 32 bit ints' do
+    bytes('4EF72200').sint32(0).should == 2291534
+    bytes('FFFFFFFF').sint32(0).should == -1
+  end
+  
+  it 'should extract floats' do
+    bytes('8C882044').float(0).round(4).should == 642.1335
+    bytes('B43D693F').float(0).round(4).should == 0.9111
+  end
+  
+  it 'should enable subset extraction' do
+    @bytes = bytes('1234567890')
+    @bytes[0].data.should == ['12']
+    @bytes[1,2].to_s.should == '3456'
+  end
+  
+  # Helper to construct a new Bytes object from a given string
+  def bytes(str)
+    Simms::Bytes.new(str)
+  end
+  
+end

data/spec/simms/packet_spec.rb

@@ -0,0 +1,30 @@
+describe Simms::Packet do
+  
+  SAMPLE_TIMESTAMP = '2012-06-27 16:16:08'
+  SAMPLE_PACKET = 'FB10040002000015ABA0B0220100FF00FF00FFFFFFFFFFFF0100790E937900022A00FFFF0B351A820000C8000100040002000015ABA0B022010053696D6D734F666669636550616E656C0000'
+
+  before(:all) do
+    @beacon = Simms::Packet.parse(SAMPLE_TIMESTAMP, SAMPLE_PACKET)
+  end
+
+  it 'should parse valid packets' do
+    Simms::Packet.parse(SAMPLE_TIMESTAMP, SAMPLE_PACKET).should_not be_nil
+  end
+
+  it 'should return the correct beacon type' do
+    @beacon.should be_a(Simms::GlobalConfigBeacon)
+  end
+
+  it 'should correctly set the beacon\'s device UUID' do
+    @beacon.uuid.should == '00-15-AB-A0-B0-22'
+  end
+
+  it 'should correctly set the beacon\'s timestamp' do
+    @beacon.timestamp.should == Time.utc(2012,6,27,16,16,8)
+  end
+  
+  it 'should return raise on invalid packet data' do
+    lambda{Simms::Packet.parse(SAMPLE_TIMESTAMP, '1234')}.should raise_error
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+# Require our library
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'simms'))
+
+RSpec.configure do |config|
+  #config.add_formatter 'documentation'
+  config.color = true
+  config.backtrace_clean_patterns = [/rspec/]
+end
+

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: simms
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Rob Morris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Allows accepting and parsing Simms Energy monitor data streams.
+email:
+- rob@irongaze.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/simms/beacon.rb
+- lib/simms/bytes.rb
+- lib/simms/electricity_config_beacon.rb
+- lib/simms/electricity_data_beacon.rb
+- lib/simms/global_config_beacon.rb
+- lib/simms/packet.rb
+- lib/simms.rb
+- spec/simms/beacon_spec.rb
+- spec/simms/bytes_spec.rb
+- spec/simms/packet_spec.rb
+- spec/spec_helper.rb
+- LICENSE
+- History.txt
+- Version.txt
+- README.rdoc
+- .rspec
+homepage: http://irongaze.com
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Data stream parser for Simms Energy monitors
+test_files: []