pzem016 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '030915a891a9651cde14fcecdca0c8aec9683b3a58fbe36d20913ac5e4603935'
+  data.tar.gz: b1d4db0b9982a05e173420f63056272ef298eee1bbf3b01a120800589785c50a
+SHA512:
+  metadata.gz: 72d7704b3335514d3c011c2211022b676c4dd5f5764a4a5a581835fdf714c175b0c5bdc7cbe09b9fc11a2410528f77e09487b18d669304f36654df6a279c96a2
+  data.tar.gz: 26eeb29d6d1893b83145d791d1c0241af11cacf9679d2878d207732be418713935bbcc15e8489fb9fc0a54f00141b2dbc26d96051a5911bcc26ed6c27cfa995d

data/README.md

@@ -0,0 +1,102 @@
+# Pzem016
+
+Pzem016 is some Ruby support for some very cheap but decent power monitors you can get from AliExpress
+
+These things: https://www.aliexpress.com/w/wholesale-pzem%2525252d016.html?spm=a2g0o.best.search.0
+
+This gem provides a library to wrap some of the modbus details, and a cli so you can interact
+with them right away without having to write code.
+
+You'll need an RS-485 adapter of some sort - I have had good luck with https://www.amazon.com/dp/B076WVFXN8?ref=ppx_yo2ov_dt_b_product_details&th=1
+
+Wiring is very simple.  For a single point to point it's just A<->A, B<->B, GND<->GND.  You can have more than one node on the bus. If you intend
+to do that you'll need to look at doing some impedance matching with terminating resistors at both ends.
+
+![RS-485 wiring](PZEM016-bench.jpg)
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+Library documentation is here: [TODO]
+
+Example of output:
+![sample usage](sampleoutput.png)
+
+The command line tool's cli syntax uses subcommands:
+
+```
+pzem016.rb --help
+PZEM-016 power measurement module utility.
+
+Syntax: pzem016.rb [global options] <command> [options]
+
+Commands: ["read", "readconfig", "setconfig", "resetenergy", "scanbus"]
+
+Global options:
+  -p, --port=<s>       Serial port (default: /dev/ttyUSB0)
+  -s, --speed=<i>      Port speed (default: 9600)
+  -t, --timeout=<i>    Retry timeout (default: 1)
+  -r, --retries=<i>    Number of times to retry ModBus command (default: 1)
+  -n, --name=<s>       Device name (default: PZEM-016 Device)
+  -d, --debug          Extra noise
+  -h, --help           Show this message
+```
+
+```
+pzem016.rb read --help
+Read power values from specified device
+  -s, --sladdr=<i>    Slave address (default: 1)
+  -j, --json          Output JSON
+  -h, --help          Show this message
+```
+
+```
+pzem016.rb readconfig --help
+Read config values from specified device
+  -s, --sladdr=<i>    Slave address (default: 1)
+  -j, --json          Output JSON
+  -h, --help          Show this message
+```
+
+```
+pzem016.rb setconfig --help
+Set device address and/or alarm threshold: pzem016.rb setconfig <addr|alarm> <value>
+  -s, --sladdr=<i>    Slave address (default: 1)
+  -h, --help          Show this message
+```
+
+```
+pzem016.rb resetenergy  --help
+Reset (clear) the energy counter (KWH) on the specified device
+  -s, --sladdr=<i>    Slave address (default: 1)
+  -h, --help          Show this message
+```
+
+```
+pzem016.rb scanbus  --help
+Scan ModBus for nodes/addrs
+  -r, --read    Try to read values when node is found
+  -h, --help    Show this message
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at https://gitlab.com/svdasein/pzem016

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+task default: %i[]

data/exe/pzem016.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/pzem016'
+require 'optimist'
+require 'ruby-progressbar'
+
+progname = File.basename($PROGRAM_NAME)
+commands = %w[read readconfig setconfig resetenergy scanbus]
+
+global_opts = Optimist.options do
+  banner "PZEM-016 power measurement module utility.\n\nSyntax: #{progname} [global options] <command> [options]\n\nCommands: #{commands}\n\nGlobal options:"
+  opt :port, 'Serial port', type: :string, default: '/dev/ttyUSB0'
+  opt :speed, 'Port speed', type: :integer, default: 9600
+  opt :timeout, 'Retry timeout', type: :integer, default: 1
+  opt :retries, 'Number of times to retry ModBus command', default: 1
+  opt :name, 'Device name', type: :string, default: 'PZEM-016 Device'
+  opt :debug, 'Extra noise', type: :boolean
+  stop_on commands
+end
+
+cmd = ARGV.empty? ? '(not given)' : ARGV.shift.downcase.to_sym
+
+cmd_opts = case cmd
+   when :read, :readconfig # parse delete options
+     Optimist.options do
+       banner "Read #{cmd == :read ? "power" : "config"} values from specified device"
+       opt :sladdr, 'Slave address', type: :integer, default: 1
+       opt :json, 'Output JSON', type: :boolean, default: false
+     end
+   when :setconfig
+     opts = Optimist.options do
+       banner "Set device address and/or alarm threshold: #{progname} setconfig <addr|alarm> <value>"
+       opt :sladdr, 'Slave address', type: :integer, default: 1
+     end
+     if ARGV.size == 2
+       setting = ARGV.shift.downcase.to_sym
+       Optimist.die "Specify one of 'addr' or 'alarm'; you gave '#{setting}'" unless %i[addr alarm].include?(setting)
+       value = ARGV.shift.to_i
+     else
+       Optimist.die "syntax #{progname} setconfig <addr|alarm> <value>"
+     end
+     opts
+   when :resetenergy
+     Optimist.options do
+       banner 'Reset (clear) the energy counter (KWH) on the specified device'
+       opt :sladdr, 'Slave address', type: :integer, default: 1
+     end
+   when :scanbus
+     Optimist.options do
+       banner 'Scan ModBus for nodes/addrs'
+       opt :read, 'Try to read values when node is found', type: :boolean
+     end
+   else
+     puts "Valid commands: #{commands}"
+     Optimist.die "unknown command: #{cmd}"
+end
+
+if global_opts[:debug]
+  puts "Global options: #{global_opts.inspect}"
+  puts "Subcommand: #{cmd.inspect}"
+  puts "Subcommand options: #{cmd_opts.inspect}"
+  puts "Remaining arguments: #{ARGV.inspect}"
+end
+
+bus = ModBus::RTUClient.connect(global_opts[:port], global_opts[:speed])
+
+begin
+  case cmd
+  when :read
+    bus.with_slave(cmd_opts[:sladdr]).tap do |slave|
+      slave.read_retry_timeout = global_opts[:timeout]
+      slave.read_retries = global_opts[:retries]
+      input = Pzem016::InputRegisters.new(global_opts[:name], slave)
+      input.read
+      if cmd_opts[:json]
+        puts input.to_json
+      else
+        input.report
+      end
+    end
+  when :readconfig
+    bus.with_slave(cmd_opts[:sladdr]).tap do |slave|
+      slave.read_retry_timeout = global_opts[:timeout]
+      slave.read_retries = global_opts[:retries]
+      holding = Pzem016::HoldingRegisters.new(global_opts[:name], slave)
+      holding.read
+      if cmd_opts[:json]
+        puts holding.to_json
+      else
+        holding.report
+      end
+    end
+  when :setconfig
+    slave = bus.with_slave(cmd_opts[:sladdr])
+    slave.read_retry_timeout = global_opts[:timeout]
+    slave.read_retries = global_opts[:retries]
+    device = Pzem016::HoldingRegisters.new(global_opts[:name], slave)
+    case setting
+    when :addr
+      device.set_address(value)
+      puts "Address of slave at '#{cmd_opts[:sladdr]}' has been changed to '#{value}'"
+    when :alarm
+      device.set_alarm(value)
+      puts "Alarm threshold value for slave at #{cmd_opts[:sladdr]} has been set to #{value} watts"
+    end
+  when :resetenergy
+    puts "Slave at addr #{cmd_opts[:sladdr]} energy counter reset: #{Pzem016::HoldingRegisters.new(global_opts[:name],
+                                                                                                   bus.with_slave(cmd_opts[:sladdr])).reset_energy}"
+  when :scanbus
+    begin
+      (1..247).each do |address|
+        bus.with_slave(address) do |slave|
+          slave.read_retry_timeout = global_opts[:timeout]
+          slave.read_retries = global_opts[:retries]
+          begin
+            value = slave.read_holding_registers(0, 3)
+            puts "\nDevice found at address #{value[2]}\n"
+            if cmd_opts[:read]
+              input = Pzem016::InputRegisters.new(global_opts[:name], slave)
+              input.read
+              input.report
+              puts
+            end
+          rescue StandardError
+            print '.'
+          end
+        end
+      end
+      puts "\n"
+    rescue Interrupt
+      puts "\nscan interrupted\n"
+    end
+  else
+    puts "Command required, one of #{commands}"
+  end
+rescue ModBus::Errors::ModBusTimeout
+  puts 'ModBus timed out - are you sure you specified the correct --sladdr?'
+end

data/lib/pzem016/pzem016.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+##
+# This module is a container for a few classes that wrap a bunch
+# of ModBus related stuff
+#
+module Pzem016
+  require 'json'
+  require 'awesome_print'
+
+  ##
+  # Some abstract behavior for the register parser classes
+  #
+  class ModbusRegisters
+    attr_reader :raw, :slave
+
+    ##
+    # This takes two params: name and slave.  Name is a descriptive string
+    # for the slave.  Slave is an instance of a ModBus::RTUClient slave
+    # that you've previously set up.
+    #
+    def initialize(name, slave)
+      @slave = slave
+      @name = name
+      @raw = nil
+    end
+
+    ##
+    # Stub for read logic
+    #
+    def read
+      @raw = []
+    end
+
+    ##
+    # Simple basic behavior for turning the data read into a hash
+    #
+    def to_hash
+      { raw: @raw }
+    end
+
+    ##
+    # Returns the sample data as a json string
+    #
+    def to_json(*_args)
+      to_hash.to_json
+    end
+
+    ##
+    # Outputs a pretty dump of the readings to STDOUT
+    #
+    def report
+      ap to_hash
+    end
+  end
+
+  ##
+  # Parsing logic for the "holding registers", also
+  # known as read/write. PZEM-016 is configured via these
+  #
+  class HoldingRegisters < ModbusRegisters
+    ##
+    # Specific holding register read logic for PZEM-016
+    #
+    def read
+      @raw = @slave.holding_registers[0..6]
+    end
+
+    ##
+    # Sets the address of the slave to the new address addr
+    #
+    def set_address(addr)
+      @slave.write_single_register(2, addr)
+    end
+
+    ##
+    # Sets the alarm threshold to the given number of watts
+    def set_alarm(watts)
+      @slave.write_single_register(1, watts)
+    end
+
+    ##
+    # Clears / resets the KWH (energy) counter on the PZEM-016
+    #
+    def reset_energy
+      @slave.query("\x42")
+    rescue ModBus::Errors::IllegalFunction
+      # the units respond with an error but in fact do reset the counter
+      true
+    end
+
+    ##
+    # Specific logic for generating a hash of the holding registers in a PZEM-016
+    #
+    def to_hash
+      {
+        "DeviceName": @name,
+        "Address": @raw[2],
+        "AlarmWatts": @raw[1]
+      }
+    end
+  end
+
+  ##
+  # Parsing logic for the "input registers", also
+  # known as readonly.  This is where the sample data
+  # shows up
+  #
+  class InputRegisters < ModbusRegisters
+    ##
+    # Specific input register read logic for PZEM-016
+    #
+    def read
+      @raw = @slave.input_registers[0..9]
+    end
+
+    ##
+    # Extracts measured volts from the sample data
+    #
+    def volts
+      (@raw[0] * 0.1).round(3)
+    end
+
+    ##
+    # Extracts measured amps from the sample data
+    #
+    def amps
+      (((@raw[2] << 16) | @raw[1]) * 0.001).round(3)
+    end
+
+    ##
+    # Extracts measured watts from the sample data
+    #
+    def watts
+      (((@raw[4] << 16) | @raw[3]) * 0.1).round(3)
+    end
+
+    ##
+    # Extracts cumulative watt-hours from the sample data
+    #
+    def wattHours
+      (((@raw[6] << 16) | @raw[5]) * 0.1).round(3)
+    end
+
+    ##
+    # Extracts measured frequency from the sample data
+    #
+    def hz
+      (@raw[7] * 0.1).round(3)
+    end
+
+    ##
+    # Extracts measured power factor from the sample data
+    #
+    def powerFactor
+      (@raw[8] * 0.01).round(3)
+    end
+
+    ##
+    # Returns true of power consumption has reached the alarm number of watts
+    #
+    def alarm?
+      @raw[9] == 0xFFFF
+    end
+
+    ##
+    # Specific logic for generating a hash of the input registers in a PZEM-016
+    #
+    def to_hash
+      {
+        "DeviceName": @name,
+        "Volts": volts,
+        "Amps": amps,
+        "Watts": watts,
+        "WH": wattHours,
+        "HZ": hz,
+        "PF": powerFactor,
+        "Alarm": alarm?
+      }
+    end
+  end
+end

data/lib/pzem016/version.rb

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

data/lib/pzem016.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rmodbus'
+require 'pry' if ENV['RUBY_ENV'] == 'development'
+require_relative 'pzem016/version'
+require_relative 'pzem016/pzem016'
+
+module Pzem016
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/pzem016.rbs

@@ -0,0 +1,4 @@
+module Pzem016
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: pzem016
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Parker
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: optimist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rmodbus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: PZEM-016 is a cheap power monitoring thing you can get from aliexpress
+  for usually very little money https://www.aliexpress.com/w/wholesale-pzem%2525252d016.html?spm=a2g0o.best.search.0.  This
+  gem provides a library to talk to them with and some cli utils
+email:
+- dparker@svdasein.org
+executables:
+- pzem016.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- PZEM016-bench.jpg
+- README.md
+- Rakefile
+- exe/pzem016.rb
+- lib/pzem016.rb
+- lib/pzem016/pzem016.rb
+- lib/pzem016/version.rb
+- sampleoutput.png
+- sig/pzem016.rbs
+homepage: https://gitlab.com/svdasein/pzem016
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://gitlab.com/svdasein/pzem016
+  changelog_uri: https://gitlab.com/svdasein/pzem016/-/blob/master/CHANGELOG
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.7
+signing_key: 
+specification_version: 4
+summary: Library and cli utils to interact with PZEM-016 power monitoring units
+test_files: []