lxp-packet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a06975e75dcaa0908d9f1e795d6a9106cf4cabe951b5907ce9b73802d1322999
+  data.tar.gz: 32919a40bd5f34819be74a7b5eeb51d5c6cdd322882d75b2f533f2cbc73c68a6
+SHA512:
+  metadata.gz: 52d0753334fb109f1caddbf00ced45d9e2d372b8de76cc8358154d95a79931357d71cfad525a0f8ee578e89f15a95648d599948501f17f8ca3a7c137bca926b0
+  data.tar.gz: 75e3b687650069eb24fd0d875b27a0a831ef20157d885b5c12450cee60e7c6e1f038606109e2dd0338f9cd9d710ce1a6a6dd240a228364c0fee65dd81975d7e4

data/.gitignore

@@ -0,0 +1,4 @@
+*.swp
+vendor/*
+.bundle
+Gemfile.lock

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+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).
+
+## [Unreleased]
+
+- Nothing yet
+
+## [0.1.0] - 2020-01-05
+
+### Added
+
+- Initial release

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Chris Elsworth
+
+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.md

@@ -0,0 +1,161 @@
+# LXP Communications Library
+
+This is a Ruby gem to parse and generate data packets from/to a LuxPower inverter. This is tested with my ACS3600 model but may work with others.
+
+Unfortunately LuxPower refuse to release API documentation for this inverter, so this is all reverse engineered. Use with care.
+
+That said, I've managed to work out quite a bit of it. You can parse "input" packets (via `ReadInput`) from the inverter (which are the data sent in 3 packets at 2 minute intervals, concerning energy flows and states), request settings (via `ReadHold`) for a specific register, and then modify and write those settings back (via `WriteSingle`).
+
+There's a `WriteMulti` too but I've not used that yet. It may be used for setting the time, but I'm not interested in that so didn't bother working it out.
+
+When you send the inverter a read/write packet, it sends a reply with the same register you sent it, and in the case of write packets, the updated value. This can be used to check the write has taken effect.
+
+Note that the replies appear to be sent to all connected clients. If you updating a setting then the reply containing the new updated value is sent to all connected clients (including Lux in China, as per the default inverter configuration). They probably just ignore it as being unexpected; but this is partly the reason there's a `read_reply` method below which ignores packets until we get the one we expect.
+
+See the docs in doc/ for a list of registers and my notes on how the packets are constructed. Please remember there may be errors so test carefully before letting any of this loose on your own kit. To repeat, this is all detective work by myself without the assistance of any official docs.
+
+Also note that `lib/lxp/packet/registers.rb` only contains registers I've used, not all of them. I'll happily accept PRs adding new ones.
+
+This library uses semantic versioning, and accordingly I currently make no guarantees about preserving backwards compatibility. Lock your gem version if this might affect you!
+
+## Install
+
+Standard Ruby fare in your Gemfile:
+
+```ruby
+gem 'lxp-packet'
+```
+
+Then require the base library when you want it:
+
+```ruby
+require 'lxp/packet'
+```
+
+## Setup
+
+You obviously need the WiFi datalogger module in your inverter to use this. Mine came with it as standard.
+
+The datalogger by default sends information about itself to LuxPower (see Connection 1 below) every 2 minutes. It connects to Lux at the IP shown below. This is how their portal gets information about you, and how they can send your inverter commands over the open channel.
+
+It can optionally be configured with a second network endpoint; I set this to TCP Server with a port of 4346, which means you can connect to the inverter on that port and get the same information sent to you. You can also send it commands. So the "Network Setting" page of my inverter looks like this:
+
+![LXP ACS Network Settings](https://i.imgur.com/teygH6h.png)
+
+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.
+
+## Examples
+
+The inverter requires that your datalog serial and inverter serial are in the packets you send to it for it to respond.
+
+These are set like so; this will not be repeated in all subsequent examples.
+
+```ruby
+pkt = LXP::Packet::ReadHold.new
+pkt.datalog_serial = 'AB12345678'
+pkt.inverter_serial = '1234567890'
+```
+
+There's also a commonly-used loop that I'll refer to. This reads input from the socket until it gets a decoded packet which matches the packet register we've previously sent to the inverter, ignoring heartbeats and other data.
+
+This is extremely rudimentary but you get the idea. It should really have a timeout so it doesn't block forever.
+
+```ruby
+def read_reply(sock, pkt)
+  loop do
+    input = sock.recvfrom(2000)[0]
+    # puts "IN: #{input.unpack('C*')}"
+    r = LXP::Packet::Parser.parse(input)
+    return r if r.is_a?(pkt.class) && r.register == pkt.register
+  end
+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
+
+This is the simplest use-case; read the value of something from the inverter.
+
+```ruby
+pkt = LXP::Packet::ReadHold.new
+pkt.datalog_serial = 'AB12345678'
+pkt.inverter_serial = '1234567890'
+pkt.register = LXP::Packet::Registers::DISCHG_CUT_OFF_SOC_EOD
+
+# pkt.bytes returns an array of integers if you want to inspect what we'll send
+
+# pack the integers into a binary packet to send to a socket
+out = pkt.to_bin
+
+# 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)
+puts "Received: #{r.value}" # should be discharge cut-off value
+```
+
+### Writing
+
+Updating a value on the inverter.
+
+```ruby
+pkt = LXP::Packet::WriteSingle.new
+# set serials like above..
+
+# set discharge cutoff to 20%
+pkt.register = LXP::Packet::Registers::DISCHG_CUT_OFF_SOC_EOD
+pkt.value = 20
+
+# pack the integers into a binary packet to send to a socket
+out = pkt.to_bin
+
+# 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)
+puts "Received: #{r.value}" # should be new discharge cut-off value, 20
+```
+
+### Updating a multi-byte register
+
+The Lux has two registers that contain multiple settings. In `doc/LXP_REGISTERS.txt` you can see them at 21 and 110. They have two bytes.
+
+This library combines them into a 16bit word, so that the constants in `LXP::Packet::RegisterBits` can be applied directly to those values.
+
+First you need to read the previous value, update it with a new bit, then write it back. This is really just a combination of the two above examples.
+
+This enables AC charge. You need to OR the bit with the previous value so as not to change other settings tored in register 21.
+
+It could be improved not to bother doing the write if it was already enabled.
+
+```ruby
+sock = TCPSocket.new('192.168.0.30', 4346)
+
+pkt = LXP::Packet::ReadHold.new
+# serials..
+
+pkt.register = 21
+sock.write(pkt.to_bin)
+
+r = read_reply(sock, pkt)
+# r.value is a 16bit integer
+
+pkt = LXP::Packet::WriteSingle.new
+# serials..
+
+pkt.register = 21
+
+# enable AC charge by ORing it with the previous value
+pkt.value = r.value | LXP::Packet::RegisterBits::AC_CHARGE_ENABLE
+
+# or maybe you want to disable AC charge
+# pkt.value = r.value & ~LXP::Packet::RegisterBits::AC_CHARGE_ENABLE
+
+sock.write(pkt.to_bin)
+
+r = read_reply(sock, pkt)
+# now r.value should be the updated 16bit integer
+```

data/doc/LXP_PACKET.txt

@@ -0,0 +1,64 @@
+Reverse-engineered packet analysis when talking to my LXP ACS inverter.
+
+E&OE - this may not be complete or correct, please exercise care!
+
+All numbers appear to be transmitted least significant byte first. Numbers
+in this document are presented in decimal.
+
+Most packets appear to be 38 bytes (though this can vary). There appears
+to be a prefix of 6 bytes:
+
+ BYTE BYTES VALUE MEANING
+    0     1   161 Prefix
+    1     1    26 Prefix
+    2     2       protocol number
+    4     2       frame length
+
+Protocol number normally seems to be 1, though I've seen 2 returned from the
+inverter.
+
+Frame length is a count of all bytes after those 6, so for a usual 38 byte
+packet, this will be 32.
+
+Then there's a header:
+
+ BYTE BYTES VALUE MEANING
+    6     1     1 always seems to be 1
+    7     1       TCP_FUNCTION; 193=heartbeat
+                                194=data to translate
+                                195=read param 196=write param
+    8    10       datalog serial number
+   18     2       data frame length or heartbeat number?
+
+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:
+
+ BYTE BYTES VALUE MEANING
+ 0/20     1       address? 0 when writing to inverter, 1 when reading?
+ 1/21     1       DEVICE_FUNCTION; 3=R_HOLD 4=R_INPUT 6=W_SINGLE 16=W_MULTI
+ 2/22    10       inverter serial number
+12/32     2       register (also start address - 0/40/80)
+14/34     2?      value (also point number)
+16/36     2       modbus_CRC16 (of bytes 0-15 of this dataframe)
+
+Data frames are usually 18 bytes, but I have seen 17 and 19. Sometimes there's
+a byte integer between the register and the value, I think this says how many
+value bytes there are. Not entirely clear when this will be such an int, or
+when it will be the first byte of the value though. Maybe just when len != 18?
+
+DEVICE_FUNCTION is basically the type of command. Not sure of the difference
+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.

data/doc/LXP_REGISTERS.txt

@@ -0,0 +1,126 @@
+This is a list of registers in the LXP inverter. The numbers here are
+decimal.
+
+This is all reverse engineered and worked out manually so there may be
+omissions. Please take care before changing critical values without proper
+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
+2 SERIAL_NUM
+7 FW_CODE
+12 TIME
+15 COM_ADDR
+16 LANGUAGE
+20 PV_INPUT_MODE
+21 FUNC_AC_CHARGE / FUNC_FORCED_DISCHG_EN / FUNC_FORCED_CHG_EN /
+   FUNC_EPS_EN / FUNC_FEED_IN_GRID_EN / FUNC_SET_TO_STANDBY ?
+   ## LEAST SIGNIFICANT BYTE
+   bit 7 = ac charge
+   bit 6 = grid on power ss
+   bit 5 = neutral detect
+   bit 4 = anti island
+   bit 3 = ? can't see any effect. normally off..
+   bit 2 = drms
+   bit 1 = ovf load derate
+   bit 0 = eps
+         fails with error code 3? (134 in dataframe second byte)
+   ## MOST SIGNIFICANT BYTE
+   bit 7 = feed in grid
+   bit 6 = DCI
+   bit 5 = GFCI
+   bit 4 = ? can't see any effect. normally on.
+   bit 3 = charge priority (charge before supplying load)
+   bit 2 = forced discharge
+   bit 1 = normal/standby (does not appear to save any power anyway)
+   bit 0 = seamless eps switching
+22 START_PV_VOLT
+23 CONNECT_TIME
+24 RECONNECT_TIME
+25 GRID_VOLT_CONN_LOW
+26 GRID_VOLT_CONN_HIGH
+27 GRID_FREQ_CONN_LOW
+28 GRID_FREQ_CONN_HIGH
+29 GRID_VOLT_LIMIT1_LOW
+30 GRID_VOLT_LIMIT1_HIGH
+31 GRID_VOLT_LIMIT1_LOW_TIME
+32 GRID_VOLT_LIMIT1_HIGH_TIME
+33 GRID_VOLT_LIMIT2_LOW
+34 GRID_VOLT_LIMIT2_HIGH
+35 GRID_VOLT_LIMIT2_LOW_TIME
+36 GRID_VOLT_LIMIT2_HIGH_TIME
+37 GRID_VOLT_LIMIT3_LOW
+38 GRID_VOLT_LIMIT3_HIGH
+39 GRID_VOLT_LIMIT3_LOW_TIME
+40 GRID_VOLT_LIMIT3_HIGH_TIME
+41 GRID_VOLT_MOV_AVG_HIGH
+42 GRID_FREQ_LIMIT1_LOW
+43 GRID_FREQ_LIMIT1_HIGH
+44 GRID_FREQ_LIMIT1_LOW_TIME
+45 GRID_FREQ_LIMIT1_HIGH_TIME
+46 GRID_FREQ_LIMIT2_LOW
+47 GRID_FREQ_LIMIT2_HIGH
+48 GRID_FREQ_LIMIT2_LOW_TIME
+49 GRID_FREQ_LIMIT2_HIGH_TIME
+50 GRID_FREQ_LIMIT3_LOW
+51 GRID_FREQ_LIMIT3_HIGH
+52 GRID_FREQ_LIMIT3_LOW_TIME
+53 GRID_FREQ_LIMIT3_HIGH_TIME
+54 MAX_Q_PERCENT_FOR_QV
+55 V1L
+56 V2L
+57 V1H
+58 V2H
+59 REACTIVE_POWER_CMD_TYPE
+60 ACTIVE_POWER_PERCENT_CMD
+61 REACTIVE_POWER_PERCENT_CMD
+62 PF_CMD
+63 POWER_SOFT_START_SLOPE
+64 CHARGE_POWER_PERCENT_CMD
+65 DISCHG_POWER_PERCENT_CMD
+66 AC_CHARGE_POWER_CMD
+67 AC_CHARGE_SOC_LIMIT
+68 AC_CHARGE_START_HOUR / AC_CHARGE_START_MINUTE
+69 AC_CHARGE_END_HOUR / AC_CHARGE_END_MINUTE
+70 AC_CHARGE_START_HOUR_1 / AC_CHARGE_START_MINUTE_1
+71 AC_CHARGE_END_HOUR_1 / AC_CHARGE_END_MINUTE_1
+72 AC_CHARGE_START_HOUR_2 / AC_CHARGE_START_MINUTE_2
+73 AC_CHARGE_END_HOUR_2 / AC_CHARGE_END_MINUTE_2
+74 FORCED_CHG_POWER_CMD
+75 FORCED_CHG_SOC_LIMIT
+76 FORCED_CHARGE_START_HOUR / FORCED_CHARGE_START_MINUTE
+77 FORCED_CHARGE_END_HOUR/ FORCED_CHARGE_END_MINUTE
+78 FORCED_CHARGE_START_HOUR_1 / FORCED_CHARGE_START_MINUTE_1
+79 FORCED_CHARGE_END_HOUR_1 / FORCED_CHARGE_END_MINUTE_1
+80 FORCED_CHARGE_START_HOUR_2 / FORCED_CHARGE_START_MINUTE_2
+81 FORCED_CHARGE_END_HOUR_2 / FORCED_CHARGE_END_MINUTE_2
+82 FORCED_DISCHG_POWER_CMD
+83 FORCED_DISCHG_SOC_LIMIT
+84 FORCED_DISCHARGE_START_HOUR / FORCED_DISCHARGE_START_MINUTE
+85 FORCED_DISCHARGE_END_HOUR / FORCED_DISCHARGE_END_MINUTE
+86 FORCED_DISCHARGE_START_HOUR_1 / FORCED_DISCHARGE_START_MINUTE_1
+87 FORCED_DISCHARGE_END_HOUR_1 / FORCED_DISCHARGE_END_MINUTE_1
+88 FORCED_DISCHARGE_START_HOUR_2 / FORCED_DISCHARGE_START_MINUTE_2
+89 FORCED_DISCHARGE_END_HOUR_2 / FORCED_DISCHARGE_END_MINUTE_2
+90 EPS_VOLT_SET
+91 EPS_FREQ_SET
+99 LEAD_ACID_CHARGE_VOLT_REF
+100 LEAD_ACID_DISCHARGE_CUT_OFF_VOLT
+101 LEAD_ACID_CHARGE_RATE
+102 LEAD_ACID_DISCHARGE_RATE
+103 FEED_IN_GRID_POWER_PERCENT
+105 DISCHG_CUT_OFF_SOC_EOD
+106 LEAD_ACID_TEMPR_LOWER_LIMIT_DISCHG
+107 LEAD_ACID_TEMPR_UPPER_LIMIT_DISCHG
+108 LEAD_ACID_TEMPR_LOWER_LIMIT_CHG
+109 LEAD_ACID_TEMPR_UPPER_LIMIT_CHG
+110 FUNC_PV_GRID_OFF_EN / FUNC_RUN_WITHOUT_GRID / FUNC_MICRO_GRID_EN?
+    ## LEAST SIGNIFICANT BYTE
+    bit 2 = micro grid enable
+    bit 1 = fast zero export
+    bit 0 = ? fails with error 3 (134 in dataframe second byte)
+    ## MOST SIGNIFICANT BYTE
+112 SET_MASTER_OR_SLAVE
+113 SET_COMPOSED_PHASE

data/lib/lxp/packet/base.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative 'device_functions'
+
+class LXP
+  class Packet
+    class Base
+      # 20 bytes
+      attr_accessor :header
+
+      # usually 16 bytes?
+      attr_accessor :data
+
+      # 2 bytes
+      attr_accessor :chksum
+
+      def initialize
+        @header = [0] * 20
+        @data = [0] * 16
+        @chksum = [0, 0]
+
+        # prefix
+        @header[0] = 161
+        @header[1] = 26
+
+        self.protocol = 1
+
+        # length after first 6 bytes maybe?
+        self.packet_length = 32
+
+        @header[6] = 1 # unsure
+
+        @header[7] = 194 # translated data, TBD
+      end
+
+      def bytes
+        update_checksum
+        header + data + chksum
+      end
+
+      def to_bin
+        bytes.pack('C*')
+      end
+
+      def self.parse(ascii)
+        # array of integers
+        bdata = ascii.unpack('C*')
+
+        raise 'invalid packet' if bdata[0] != 161 || bdata[1] != 26
+
+        i = new
+
+        # header is always 20 bytes
+        i.header[0, 20] = bdata[0, 20]
+
+        # data can vary from 17 bytes upwards
+        i.data = bdata[20, i.data_length - 2] # -2, don't copy checksum
+        raise 'bad data length' unless i.data.length != i.data_length
+
+        # calculate checksum and compare to input
+        i.update_checksum
+        raise 'invalid checksum' if i.chksum != bdata[-2..-1]
+
+        i
+      end
+
+      def protocol
+        @header[2] | @header[3] >> 8
+      end
+
+      def protocol=(protocol)
+        @header[2] = protocol & 0xff
+        @header[3] = (protocol >> 8) & 0xff
+      end
+
+      def packet_length
+        @header[4] | @header[5] >> 8
+      end
+
+      def packet_length=(packet_length)
+        @header[4] = packet_length & 0xff
+        @header[5] = (packet_length >> 8) & 0xff
+      end
+
+      # Passed as a string
+      def datalog_serial=(datalog_serial)
+        @header[8, 10] = datalog_serial.bytes
+      end
+
+      def data_length
+        @header[18] | @header[19] >> 8
+      end
+
+      def data_length=(data_length)
+        @header[18] = data_length & 0xff
+        @header[19] = (data_length >> 8) & 0xff
+      end
+
+      def device_function
+        @data[1]
+      end
+
+      def device_function=(device_function)
+        @data[1] = device_function
+      end
+
+      # Passed as a string
+      def inverter_serial=(inverter_serial)
+        @data[2, 10] = inverter_serial.bytes
+      end
+
+      def register
+        @data[12] | @data[13] >> 8
+      end
+
+      def register=(register)
+        @data[12] = register & 0xff
+        @data[13] = (register >> 8) & 0xff
+      end
+
+      def value_length_byte?
+        @value_length_byte ||=
+          protocol == 2 &&
+          device_function != DeviceFunctions::WRITE_SINGLE
+      end
+
+      def value_length
+        if value_length_byte?
+          @data[14]
+        else
+          2
+        end
+      end
+
+      # protocol 1 has value at 14 and 15
+      # protocol 2 has length at 14, then that many bytes of values
+      #
+      # So this can return an int or an array.
+      #
+      def value
+        if value_length_byte?
+          @data[15, value_length]
+        else
+          @data[14] | @data[15] >> 8
+        end
+      end
+
+      # this only makes sense for protocol 1 at the moment.
+      # for 2 we'd need to append to an array, and not sure that
+      # is even used (sending an array of values to inverter)
+      # (maybe with W_MULTI?)
+      def value=(value)
+        raise 'cannot set value with protocol 2 yet' if protocol == 2
+
+        @data[14] = value & 0xff
+        @data[15] = (value >> 8) & 0xff
+      end
+
+      def update_checksum
+        chksum = crc16_modbus(data)
+        @chksum[0] = chksum & 0xff
+        @chksum[1] = (chksum >> 8) & 0xff
+      end
+
+      private
+
+      def crc16_modbus(arr)
+        arr.length.times.inject(0xffff) do |r, n|
+          r ^= arr[n]
+          8.times do
+            t = r >> 1
+            r = (r & 1).positive? ? 40_961 ^ t : t
+          end
+          r
+        end
+      end
+    end
+  end
+end

data/lib/lxp/packet/device_functions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class LXP
+  class Packet
+    module DeviceFunctions
+      READ_HOLD    = 3
+      READ_INPUT   = 4
+      WRITE_SINGLE = 6
+      WRITE_MULTI  = 16
+    end
+  end
+end

data/lib/lxp/packet/parser.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'utils'
+
+require_relative 'device_functions'
+require_relative 'tcp_functions'
+
+class LXP
+  class Packet
+    # Given an input string, work out which type of LXP::Packet it should be,
+    # and call .parse on the appropriate class.
+    class Parser
+      attr_reader :ascii, :bdata
+
+      def self.parse(ascii)
+        new(ascii).parse
+      end
+
+      def initialize(ascii)
+        @ascii = ascii
+        @bdata = ascii.unpack('C*')
+      end
+
+      def parse
+        case bdata[7] # tcp_function
+        when TcpFunctions::HEARTBEAT then nil # ignored
+        when TcpFunctions::TRANSLATED_DATA then parse_translated_data
+        else
+          raise "unhandled tcp_function #{bdata[7]}"
+        end
+      end
+
+      def parse_translated_data
+        kls = case bdata[21] # device_function
+              when DeviceFunctions::READ_HOLD then ReadHold
+              when DeviceFunctions::WRITE_SINGLE then WriteSingle
+              when DeviceFunctions::READ_INPUT then parse_input
+              else
+                raise "unhandled device_function #{bdata[21]}"
+              end
+
+        kls.parse(ascii)
+      end
+
+      # Input packets are 1-of-3; work out which it is from the register
+      def parse_input
+        case Utils.int(bdata[32, 2]) # register
+        when 0  then ReadInput1
+        when 40 then ReadInput2
+        when 80 then ReadInput3
+        end
+      end
+    end
+  end
+end

data/lib/lxp/packet/read_hold.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'device_functions'
+
+class LXP
+  class Packet
+    class ReadHold < Base
+      def initialize
+        super
+
+        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.
+        self.value = 1
+      end
+
+      # ReadHold packets should always (I think) have two byte values.
+      #
+      # Raise if not, as that is not expected?
+      #
+      # Base#value will return an int for protocol 1, or an Array
+      # for protocol 2. If we can, convert that Array to an int.
+      #
+      def value
+        raise 'value_length not 2?' unless value_length == 2
+
+        r = super
+        r.is_a?(Array) ? Utils.int(r, 2) : r
+      end
+    end
+  end
+end

data/lib/lxp/packet/read_input.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+class LXP
+  class Packet
+    # Input packets are a stream of values related to energy flows (inputs?)
+    class ReadInput < Base
+      def self.parse(ascii)
+        i = super
+
+        if i.packet_length != 111 || i.data_length != 97
+          raise 'unexpected packet length'
+        end
+
+        i
+      end
+    end
+  end
+end

data/lib/lxp/packet/read_input1.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'utils'
+require_relative 'read_input'
+
+class LXP
+  class Packet
+    class ReadInput1 < ReadInput
+      # Decode the data and return a hash of values in this input packet
+      def to_h
+        {
+          status: @data[15],
+
+          v_bat: Utils.int(@data[23, 2], :lsb) / 10.0, # V
+          soc: @data[25], # %
+
+          p_pv: Utils.int(@data[29, 2], :lsb), # W
+          p_charge: Utils.int(@data[35, 2], :lsb), # W
+          p_discharge: Utils.int(@data[37, 2], :lsb), # W
+          v_acr: Utils.int(@data[39, 2], :lsb) / 10.0, # V
+          f_ac: Utils.int(@data[45, 2], :lsb) / 100.0, # Hz
+
+          p_inv: Utils.int(@data[47, 2], :lsb), # W
+          p_rec: Utils.int(@data[49, 2], :lsb), # W
+
+          v_eps: Utils.int(@data[55, 2], :lsb) / 10.0, # V
+          f_eps: Utils.int(@data[61, 2], :lsb) / 100.0, # Hz
+
+          # peps and seps in 62..65?
+
+          p_to_grid: Utils.int(@data[66, 2], :msb), # W
+          p_to_user: Utils.int(@data[68, 2], :msb), # W
+
+          e_pv_day: Utils.int(@data[70, 2], :msb) / 10.0, # kWh
+          # not sure what 72..75 are
+          e_inv_day: Utils.int(@data[76, 2], :msb) / 10.0, # kWh
+          e_rec_day: Utils.int(@data[78, 2], :msb) / 10.0, # kWh
+          e_chg_day: Utils.int(@data[80, 2], :msb) / 10.0, # kWh
+          e_dischg_day: Utils.int(@data[82, 2], :msb) / 10.0, # kWh
+          e_eps_day: Utils.int(@data[84, 2], :msb) / 10.0, # kWh
+          e_to_grid_day: Utils.int(@data[86, 2], :msb) / 10.0, # kWh
+          e_to_user_day: Utils.int(@data[88, 2], :msb) / 10.0, # kWh
+
+          v_bus_1: Utils.int(@data[91, 2], :lsb) / 10.0, # V
+          v_bus_2: Utils.int(@data[93, 2], :lsb) / 10.0 # V
+        }
+      end
+    end
+  end
+end

data/lib/lxp/packet/read_input2.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'utils'
+require_relative 'read_input'
+
+class LXP
+  class Packet
+    class ReadInput2 < ReadInput
+      # Decode the data and return a hash of values in this input packet
+      def to_h
+        {
+          e_pv_all: Utils.int(@data[15, 4], :lsb) / 10.0, # kWh
+          e_inv_all: Utils.int(@data[27, 4], :lsb) / 10.0, # kWh
+          e_rec_all: Utils.int(@data[31, 4], :lsb) / 10.0, # kWh
+          e_chg_all: Utils.int(@data[35, 4], :lsb) / 10.0, # kWh
+          e_dischg_all: Utils.int(@data[39, 4], :lsb) / 10.0, # kWh
+          e_eps_all: Utils.int(@data[43, 4], :lsb) / 10.0, # kWh
+          e_to_grid_all: Utils.int(@data[47, 4], :lsb) / 10.0, # kWh
+          e_to_user_all: Utils.int(@data[51, 4], :lsb) / 10.0, # kWh
+
+          t_inner: Utils.int(@data[62, 2], :msb),
+          t_rad_1: Utils.int(@data[64, 2], :msb),
+          t_rad_2: Utils.int(@data[66, 2], :msb)
+        }
+      end
+    end
+  end
+end

data/lib/lxp/packet/read_input3.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'utils'
+require_relative 'read_input'
+
+class LXP
+  class Packet
+    class ReadInput3 < ReadInput
+      # Decode the data and return a hash of values in this input packet
+      def to_h
+        {
+          max_chg_curr: Utils.int(@data[17, 2], :lsb) / 100.0, # A
+          max_dischg_curr: Utils.int(@data[19, 2], :lsb) / 100.0, # A
+          charge_volt_ref: Utils.int(@data[21, 2], :lsb) / 10.0, # V
+          dischg_cut_volt: Utils.int(@data[23, 2], :lsb) / 10.0, # V
+
+          bat_status_0: @data[25],
+          bat_status_1: @data[27],
+          bat_status_2: @data[29],
+          bat_status_3: @data[31],
+          bat_status_4: @data[33],
+          bat_status_5: @data[35],
+          bat_status_6: @data[37],
+          bat_status_7: @data[39],
+          bat_status_8: @data[41],
+          bat_status_9: @data[43],
+          bat_status_inv: @data[45]
+        }
+      end
+    end
+  end
+end

data/lib/lxp/packet/register_bits.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class LXP
+  class Packet
+    module RegisterBits
+      ###
+      ### Register 21, Most Significant Byte
+      ###
+      FEED_IN_GRID            = 1 << 15
+      DCI_ENABLE              = 1 << 14
+      GFCI_ENABLE             = 1 << 13
+      R21_UNKNOWN_BIT_12      = 1 << 12
+      CHARGE_PRIORITY         = 1 << 11
+      FORCED_DISCHARGE_ENABLE = 1 << 10
+      NORMAL_OR_STANDBY       = 1 << 9
+      SEAMLESS_EPS_SWITCHING  = 1 << 8
+
+      ### Register 21, Least Significant Byte
+      AC_CHARGE_ENABLE       = 1 << 7
+      GRID_ON_POWER_SS       = 1 << 6
+      NEUTRAL_DETECT_ENABLE  = 1 << 5
+      ANTI_ISLAND_ENABLE     = 1 << 4
+      R21_UNKNOWN_BIT_3      = 1 << 3
+      DRMS_ENABLE            = 1 << 2
+      OVF_LOAD_DERATE_ENABLE = 1 << 1
+      POWER_BACKUP_ENABLE    = 1 << 0
+
+      # Not a recommendation, just what my defaults appeared to be when
+      # setting up the unit for the first time, so probably sane..?
+      R21_DEFAULTS = FEED_IN_GRID |
+                     DCI_ENABLE | GFCI_ENABLE |
+                     R21_UNKNOWN_BIT_12 |
+                     NORMAL_OR_STANDBY | SEAMLESS_EPS_SWITCHING |
+                     GRID_ON_POWER_SS | ANTI_ISLAND_ENABLE |
+                     DRMS_ENABLE
+
+      ###
+      ### Register 105, Least Significant Byte
+      ###
+      MICRO_GRID_ENABLE       = 1 << 2
+      FAST_ZERO_EXPORT_ENABLE = 1 << 1
+    end
+  end
+end

data/lib/lxp/packet/registers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class LXP
+  class Packet
+    module Registers
+      # System Charge Rate (%)
+      CHARGE_POWER_PERCENT_CMD = 64
+
+      # System Discharge Rate (%)
+      DISCHG_POWER_PERCENT_CMD = 65
+
+      # Grid Charge Power Rate (%)
+      AC_CHARGE_POWER_CMD = 66
+
+      # Discharge cut-off SOC (%)
+      DISCHG_CUT_OFF_SOC_EOD = 105
+    end
+  end
+end

data/lib/lxp/packet/tcp_functions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class LXP
+  class Packet
+    module TcpFunctions
+      HEARTBEAT       = 193
+      TRANSLATED_DATA = 194
+      READ_PARAM      = 195
+      WRITE_PARAM     = 196
+    end
+  end
+end

data/lib/lxp/packet/write_single.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+class LXP
+  class Packet
+    class WriteSingle < Base
+      def initialize
+        super
+
+        self.device_function = DeviceFunctions::WRITE_SINGLE
+        self.data_length = 18
+      end
+
+      def discharge_rate=(value)
+        self.register = Registers::DISCHG_POWER_PERCENT_CMD
+        self.value = value
+      end
+
+      def discharge_cut_off=(value)
+        self.register = Registers::DISCHG_CUT_OFF_SOC_EOD
+        self.value = value
+      end
+
+      # WriteSingle packets should always (I think) have two byte values.
+      #
+      # Raise if not, as that is not expected?
+      #
+      # Base#value will return an int for protocol 1, or an Array
+      # for protocol 2. If we can, convert that Array to an int.
+      #
+      def value
+        raise 'value_length not 2?' unless value_length == 2
+
+        r = super
+        r.is_a?(Array) ? Utils.int(r, 2) : r
+      end
+    end
+  end
+end

data/lib/lxp/packet.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'packet/registers'
+require_relative 'packet/register_bits'
+
+require_relative 'packet/parser'
+
+require_relative 'packet/read_input1'
+require_relative 'packet/read_input2'
+require_relative 'packet/read_input3'
+require_relative 'packet/read_hold'
+require_relative 'packet/write_single'

data/lib/lxp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LXP
+  VERSION = '0.1.0'
+end

data/lib/utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Utils
+  module_function
+
+  def int(bytes, order = :lsb)
+    bytes = bytes.reverse if order == :msb
+
+    bytes.each_with_index.map do |b, idx|
+      b << (idx * 8)
+    end.inject(:|)
+  end
+
+  def int_complement(bytes, order = :lsb)
+    r = int(bytes, order)
+    r -= 0x10000 if r & 0x8000 == 0x8000
+    r
+  end
+end

data/lxp-packet.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lxp/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'lxp-packet'
+  s.version       = LXP::VERSION
+  s.authors       = ['Chris Elsworth']
+  s.email         = ['chris@cae.me.uk']
+
+  s.summary       = 'Library to generate and parse LuxPower inverter packets'
+  s.homepage      = 'https://github.com/celsworth/lxp-packet'
+  s.license       = 'MIT'
+
+  s.metadata['homepage_uri'] = s.homepage
+  s.metadata['source_code_uri'] = 'https://github.com/celsworth/lxp-packet'
+
+  s.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|s|features)/}) }
+  end
+  s.bindir        = 'exe'
+  s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'bundler', '~> 2.0'
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: lxp-packet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Elsworth
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-01-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 
+email:
+- chris@cae.me.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- doc/LXP_PACKET.txt
+- doc/LXP_REGISTERS.txt
+- lib/lxp/packet.rb
+- lib/lxp/packet/base.rb
+- lib/lxp/packet/device_functions.rb
+- lib/lxp/packet/parser.rb
+- lib/lxp/packet/read_hold.rb
+- lib/lxp/packet/read_input.rb
+- lib/lxp/packet/read_input1.rb
+- lib/lxp/packet/read_input2.rb
+- lib/lxp/packet/read_input3.rb
+- lib/lxp/packet/register_bits.rb
+- lib/lxp/packet/registers.rb
+- lib/lxp/packet/tcp_functions.rb
+- lib/lxp/packet/write_single.rb
+- lib/lxp/version.rb
+- lib/utils.rb
+- lxp-packet.gemspec
+homepage: https://github.com/celsworth/lxp-packet
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/celsworth/lxp-packet
+  source_code_uri: https://github.com/celsworth/lxp-packet
+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: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Library to generate and parse LuxPower inverter packets
+test_files: []