lxp-packet 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be850807f4bf009125b77a32fc9e6572575e9b82a40039cd9898a55e0e27b9c
-  data.tar.gz: efc7f72f2e855500f90ce223977909956c21edbe372e4c29dbe52017ee1599dc
+  metadata.gz: ddb052890f90bbf20bf9ff7fd399dcb1f2a7211612c53b7cc2e98a57cf5c69a1
+  data.tar.gz: 7234113e5decb4dad0581089b72277b138c7140af0105bd4231284342f187997
 SHA512:
-  metadata.gz: 4d06b6bd60c3fff448a629e6732b9edb7a7f1b559d1c88c61420cf4b17e1c4f48e0489d0052a72442e841085295e7ac794630d97264f55194b3546d0b1fcba7a
-  data.tar.gz: f9e98b57883625a567cf3d41162f3955b1bc9c311f816ce3fe40170155315e9f0f6bc6e7e2c2b9a2fcb36def46c4ea567f99c93f540803a7bc91a8de7b261e72
+  metadata.gz: 824355382e38cc49be2c1de0a9a7d875d8975bd4993156565d7dfa8b0cfa24c042deed6d6d4ab87d5a6c42b1e88f52ad7c61eaaa4c912a6c18f7a1ccb1eb0519
+  data.tar.gz: 11d143b9f00cce2cb821216e2f64d961e595d8b52451321cf2ce2073f8d4666f33c6e0d2c36cc21761c4e849a4ca0ff3dfd192ef0f08f15cc0beb1ce5a4c1e35

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2020-05-08
+
+### Added
+
+- support for requesting input registers on demand
+- support for sending heartbeats
+
 ## [0.6.0] - 2020-04-10
 
 ### Added

data/README.md

@@ -44,6 +44,14 @@ It can optionally be configured with a second network endpoint; I set this to TC
 
 Alternatively you can probably just change the first setting if you don't care about the official Lux portal or mobile app being updated, though I found it useful to verify I was setting the right values at first. This would also prevent LuxPower sending you firmware updates (for better or for worse), not that I've had any so far.
 
+## Inverter Fundamentals
+
+The inverter has two basic sets of information.
+
+There are 114 registers (0-113), which are also referred to as "holdings". See [doc/LXP_REGISTERS.txt](doc/LXP_REGISTERS.txt) for a list of them. Most of these you can write, and they affect inverter operation. Some pieces of information span several registers, for example the serial number is in registers 2 through 8.
+
+Additionally there are input registers. These are transient information which the inverter broadcasts to any connected client every 2 minutes. These are sent as sets of 3 packets. `ReadInput1` / `ReadInput2` / `ReadInput3` are used to parse these.
+
 ## Examples
 
 The inverter requires that your datalog serial and inverter serial are in the packets you send to it for it to respond.
@@ -73,9 +81,9 @@ end
 
 This is necessary because occasionally the inverter will send us state data and heartbeats, as well as replies for other clients (see above) which we need to either process (if you're interested in them) or ignore (which is easier, and done here).
 
-### Reading
+### Reading Holding Registers
 
-This is the simplest use-case; read the value of something from the inverter.
+This is the simplest use-case; read the value of a holding register from the inverter.
 
 ```ruby
 pkt = LXP::Packet::ReadHold.new
@@ -96,9 +104,17 @@ r = read_reply(sock, pkt)
 puts "Received: #{r.value}" # should be discharge cut-off value
 ```
 
-Usually, `ReadHold` instances contain the details of just one register. However, it is possible they can contain multiple. Pressing "Read" on the LuxPower Web Portal provokes the inverter into sending out 5 packets that each contain multiple registers, for example. [TODO: work out how to request these packets ourselves]
+Usually, `ReadHold` instances contain the details of just one register. However, it is possible they can contain multiple. Pressing "Read" on the LuxPower Web Portal provokes the inverter into sending out 5 packets that each contain multiple registers, for example.
 
-To access these, you can use subscript notation to get a register directly, or call `#to_h` to get a hash of registers/values. For convenience this also works with single register packets, though obviously only one subscript will ever return data, and `to_h` will only have one key.
+To do this yourself, set `#value` in a `ReadHold` you're going to send to the inverter. This tells it how many registers you want in the reply, and they'll start from the number set in `#register`:
+
+```ruby
+# get registers 0 through 22 inclusive:
+pkt.register = 0
+pkt.value = 23
+```
+
+To access these in the reply, you can use subscript notation to get a register directly, or call `#to_h` to get a hash of registers/values. For convenience this also works with single register packets, though obviously only one subscript will ever return data, and `to_h` will only have one key.
 
 ```ruby
 # assuming pkt is a parsed packet with multiple registers/values:
@@ -111,6 +127,26 @@ pkt[22] # => nil
 pkt.to_h # { 21 => 62292 }
 ```
 
+### Reading Input Registers
+
+This is similar to reading holdings. The inverter should send these packets every 2 minutes anyway, but if you want them on demand, you can create a `ReadInput1` (or 2, or 3) and send it.
+
+The response packet contains a bunch of data, the simplest way to get at these is to call `to_h` on the packet, which returns a Hash of data:
+
+```ruby
+pkt = LXP::Packet::ReadInput1.new
+pkt.datalog_serial = 'AB12345678'
+pkt.inverter_serial = '1234567890'
+
+# assuming your inverter is at 192.168.0.30
+sock = TCPSocket.new('192.168.0.30', 4346)
+sock.write(out)
+
+r = read_reply(sock, pkt)
+# r is a populated ReadInput1, which responds to #to_h:
+r.to_h # => {:status=>16, :soc=>79, ... }
+```
+
 
 ### Writing
 

data/doc/LXP_PACKET.txt

@@ -28,15 +28,13 @@ Then there's a header:
                                 194=data to translate
                                 195=read param 196=write param
     8    10       datalog serial number
-   18     2       data frame length or heartbeat number?
+   18     2       data frame length
 
-Mostly the packets I've been dealing with have TCP_FUNCTION 194. I ignore
-heartbeats, and I've not seen 195 or 196 I don't think.
 
-For 194, bytes 18/19 are the data frame length which should match the number
-of bytes that follows. It's sometimes easier to think of the dataframe as
-its own structure so here are byte offsets in both the dataframe and the entire
-packet:
+For TCP_FUNCTION 194, bytes 18/19 are the data frame length which should match
+the number of bytes that follows. It's sometimes easier to think of the
+dataframe as its own structure so here are byte offsets in both the dataframe
+and the entire packet:
 
  BYTE BYTES VALUE MEANING
  0/20     1       address? 0 when writing to inverter, 1 when reading?
@@ -56,9 +54,6 @@ between R_HOLD and R_INPUT yet. W_SINGLE writes a single register; not used
 W_MULTI.
 
 To get the inverter to populate the response value for an R_HOLD, the value
-you send seems to need to be 1.
-
-Register and value are also referred to as start address and point number;
-this seems to be for the regular stats the inverter sends out every 2 minutes;
-seems to send 3 packets, the first one with address 0, then 40, then 80.
-Not really done much with this yet.
+you send needs to be above 0. This tells the inverter how many registers you
+want to read. Normally this is 1, if its higher than you'll get seqeuential
+registers

data/doc/LXP_REGISTERS.txt

@@ -8,7 +8,16 @@ testing in case I got anything wrong!
 Registers 21 and 110 are bitmasks; normally you fetch the previous
 settings, apply your changes, and set the new value back.
 
-0 MODEL
+0-1 MODEL
+  contains (not sure how to decode these yet):
+    lithiumType
+    powerRating
+    leadAcidType
+    ruleMask
+    batteryType
+    meterBrand
+    measurement
+    rule
 2-8 SERIAL_NUM
 7 FW_CODE ?
 9-10 ?

data/lib/lxp/packet/base.rb

@@ -16,9 +16,9 @@ class LXP
       attr_accessor :chksum
 
       def initialize
-        @header = [0] * 20
-        @data = [0] * 16
-        @chksum = [0, 0]
+        @header ||= [0] * 20
+        @data ||= [0] * 16
+        @chksum ||= [0, 0]
 
         # prefix
         @header[0] = 161

data/lib/lxp/packet/device_functions.rb

@@ -7,6 +7,12 @@ class LXP
       READ_INPUT   = 4
       WRITE_SINGLE = 6
       WRITE_MULTI  = 16
+
+      # not handled yet
+      READ_HOLD_ERROR    = 131
+      READ_INPUT_ERROR   = 132
+      WRITE_SINGLE_ERROR = 134
+      WRITE_MULTI_ERROR  = 144
     end
   end
 end

data/lib/lxp/packet/heartbeat.rb

@@ -17,10 +17,18 @@ class LXP
     #
     class Heartbeat < Base
       def initialize
+        @header = [0] * 19
+
         super
 
+        self.packet_length = 13
+        self.protocol = 2
         self.tcp_function = TcpFunctions::HEARTBEAT
       end
+
+      def bytes
+        header
+      end
     end
   end
 end

data/lib/lxp/packet/read_hold.rb

@@ -12,9 +12,9 @@ class LXP
         self.device_function = DeviceFunctions::READ_HOLD
 
         self.data_length = 18
-        # start by assuming this packet will be sent to the inverter.
-        # we need to put a 1 in the value to get the inverter to
-        # populate the reply.
+
+        # in ReadHold packets, the value is the number of registers
+        # we want to read. Default to 1.
         self.value = 1
       end
 

data/lib/lxp/packet/read_input.rb

@@ -6,6 +6,15 @@ class LXP
   class Packet
     # Input packets are a stream of values related to energy flows (inputs?)
     class ReadInput < Base
+      def initialize
+        super
+
+        self.tcp_function = TcpFunctions::TRANSLATED_DATA
+        self.device_function = DeviceFunctions::READ_INPUT
+
+        self.data_length = 18
+      end
+
       def self.parse(ascii)
         i = super
 

data/lib/lxp/packet/read_input1.rb

@@ -5,6 +5,13 @@ require_relative 'read_input'
 class LXP
   class Packet
     class ReadInput1 < ReadInput
+      def initialize
+        super
+
+        self.register = 0
+        self.value = 40
+      end
+
       # Decode the data and return a hash of values in this input packet
       def to_h
         {

data/lib/lxp/packet/read_input2.rb

@@ -5,6 +5,13 @@ require_relative 'read_input'
 class LXP
   class Packet
     class ReadInput2 < ReadInput
+      def initialize
+        super
+
+        self.register = 40
+        self.value = 40
+      end
+
       # Decode the data and return a hash of values in this input packet
       def to_h
         {
@@ -38,6 +45,8 @@ class LXP
 
           # 71..72 ?
 
+          # this actually seems to be cumulative runtime.
+          # not found an uptime since reboot yet.
           uptime: Utils.int(@data[73, 4]) # seconds
         }
       end

data/lib/lxp/packet/read_input3.rb

@@ -5,6 +5,13 @@ require_relative 'read_input'
 class LXP
   class Packet
     class ReadInput3 < ReadInput
+      def initialize
+        super
+
+        self.register = 80
+        self.value = 40
+      end
+
       # Decode the data and return a hash of values in this input packet
       def to_h
         {

data/lib/lxp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class LXP
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lxp-packet
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Chris Elsworth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-10 00:00:00.000000000 Z
+date: 2020-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,8 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Library to generate and parse LuxPower inverter packets