growatt 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cdc0228981843d69bfcec6a7bfac1e9ec88e4511242901c7edfb1f5a75e35ee
-  data.tar.gz: a60b162152c7090b9baa7f1427c8218c59551de541a2e4cb877a2bd263d48f98
+  metadata.gz: 77b696ab2333a1954a2e62dcacffea1cb9f1c4ba02f06e34001d90abc25ec4a2
+  data.tar.gz: ae2ce05b85d79cec90ca7beb35e820f0d2529b95c215fb2ebf88213c7c3d8b92
 SHA512:
-  metadata.gz: 58d0571cb4dce760266b931865e4fd7b0af69bd01c8ccbaaa51214ebd1bf5270acb3878f2356756413c9037842dc5084de2695a0cf640d5425252768dc0a307d
-  data.tar.gz: ea7d72d419209489861c5a109388f13160d3c32a5f02f5094c039562600c5f2a0c054a7ad8cca788753908c5b90cfe8b616e19ab235b22454fc6d6cdd3c86d12
+  metadata.gz: 433e4623b99df6514698821dbbd0ad319d736c47840b2c670f216b1bf9302f6cedede2c0f8ef9eb7bd02741f2d3ae0b8f179d72b14d69448852a7fc5eb6d219f
+  data.tar.gz: 2b6d7c7f0b69bace8f2b45ad838ff091e0af665ddc1dfae0c970a7bb0d692882428534eb706793102ce2524b00345f8eb02a9b771bb3dafc07dee2fa73c9c893

data/.env.template

@@ -1,4 +1,4 @@
-# demo token used
-GROWATT_USERNAME=username
-GROWATT_PASSWORD=password
-
+# demo token used
+GROWATT_USERNAME=username
+GROWATT_PASSWORD=password
+

data/.gitignore

@@ -1,47 +1,47 @@
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-/data/
-*.log
-*.txt
-*.json
-*.yml
-.DS_Store
-__pycache__
-*.py
-
-# Used by dotenv library to load environment variables.
-.env
-
-
-## Documentation cache and generated files:
-/.yardoc/
-/_yardoc/
-/doc/
-/rdoc/
-
-## Environment normalization:
-/.bundle/
-/vendor/bundle
-/lib/bundler/man/
-
-# for a library or gem, you might want to ignore these files since the code is
-# intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
-# .ruby-version
-# .ruby-gemset
-
-# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
-.rvmrc
-
-# Used by RuboCop. Remote config files pulled in from inherit_from directive.
-# .rubocop-https?--*
-Gemfile.lock
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/data/
+*.log
+*.txt
+*.json
+*.yml
+.DS_Store
+__pycache__
+*.py
+
+# Used by dotenv library to load environment variables.
+.env
+
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+Gemfile.lock

data/CHANGELOG.md

@@ -1,14 +1,16 @@
-## [Unreleased]
-
-## [0.1.0] - 2024-05-28
-- Initial release
-## [0.1.1] - 2024-05-28
-- remove unused require
-## [0.1.2] - 2024-05-29
-- add missing dependency
-## [0.1.3] - 2024-05-30
-- fix api issues to get inverter data
-## [0.1.4] - 2024-05-30
-- fix api issues where some api require correct Accept header
-## [0.2.0] - 2024-06-03
-- rename method to reflect export limitations
+## [Unreleased]
+
+## [0.1.0] - 2024-05-28
+- Initial release
+## [0.1.1] - 2024-05-28
+- remove unused require
+## [0.1.2] - 2024-05-29
+- add missing dependency
+## [0.1.3] - 2024-05-30
+- fix api issues to get inverter data
+## [0.1.4] - 2024-05-30
+- fix api issues where some api require correct Accept header
+## [0.2.0] - 2024-06-03
+- rename method to reflect export limitations
+## [0.2.1] - 2025-03-19
+- add dcumenttion

data/Gemfile

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in growatt.gemspec
-gemspec
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in growatt.gemspec
+gemspec

data/README.md

@@ -1,83 +1,114 @@
-# Growatt API
-[![Version](https://img.shields.io/gem/v/growatt.svg)](https://rubygems.org/gems/growatt)
-
-This is a wrapper for the Growatt rest API. Main objective is to turn inverter on/off. This has been testen with MOD-9000TL-X.
-
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'growatt'
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install growatt
-
-## Usage
-
-Before you start making the requests to API provide the endpoint and api key using the configuration wrapping.
-
-```ruby
-require 'growatt'
-require 'logger'
-
-# use do block
-Growatt.configure do |config|
-  config.username = ENV['GROWATT_USERNAME']
-  config.password = ENV['GROWATT_PASSWORD']
-  config.logger = Logger.new(TEST_LOGGER)
-end
-
-# or configure with options hash
-client = Growatt.client
-client.login
-
-```
-
-## Resources
-### Authentication
-```ruby
-# setup
-#
-begin
-  client = Growatt.client
-  client.login
-  # turn invertor off
-  client.turn_inverter('<serial_no>', false)
-rescue Growatt::AuthenticationError => e
-  puts "Error logging in growatt api"
-  puts e
-end
-```
-
-
-
-## Publishing
-
-1. Update version in [version.rb](lib/growatt/version.rb).
-2. Add release to [CHANGELOG.md](CHANGELOG.md)
-3. Commit.
-4. Test build.
-```
-> rake build
-
-```
-5. Release
-```
-> rake release
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/jancotanis/growatt.
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-"# growatt"
+# Growatt API
+[![Version](https://img.shields.io/gem/v/growatt.svg)](https://rubygems.org/gems/growatt)
+[![Maintainability](https://api.codeclimate.com/v1/badges/60e7b62db0513a99ae4a/maintainability)](https://codeclimate.com/github/jancotanis/growatt/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/60e7b62db0513a99ae4a/test_coverage)](https://codeclimate.com/github/jancotanis/growatt/test_coverage)
+
+This is a wrapper for the Growatt rest API. Main objective is to turn inverter on/off. This has been testen with MOD-9000TL-X.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'growatt'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install growatt
+
+## Usage
+
+Before you start making the requests to API provide the username and password using with Shinephone app.
+
+```ruby
+require 'growatt'
+require 'logger'
+TEST_LOGGER = './test.log'
+# use do block
+Growatt.configure do |config|
+  config.username = ENV['GROWATT_USERNAME']
+  config.password = ENV['GROWATT_PASSWORD']
+  config.logger = Logger.new(TEST_LOGGER)
+end
+
+# or configure with options hash
+client = Growatt.client
+client.login
+
+```
+
+## Resources
+### Authentication and configuration
+```ruby
+# setup
+#
+begin
+  client = Growatt.client
+  client.login
+  # turn invertor off
+  client.turn_inverter('<serial_no>', false)
+rescue Growatt::AuthenticationError => e
+  puts "Error login to growatt api"
+  puts e
+end
+```
+### Read data
+
+```ruby
+# create client (don't forget to configure authentication)
+# get data for first inverter for first defined plant
+plants = client.plant_list
+plant_id = plants.data.first.plantId
+devices = client.inverter_list(plant_id)
+inverter = devices.first
+
+yymm = Time.now.strftime("%Y%m")
+puts "- loading period #{yymm}"
+data = client.inverter_data(inverter.deviceSn,Growatt::Timespan::MONTH,current_month)
+
+```
+
+### Control
+
+```ruby
+# continu from read data example above
+inverter = devices.first
+
+# turn inverter on/of
+client.turn_inverter(inverter.deviceSn, false)
+
+# or limit energy export
+client.export_limit(inverter.deviceSn,Growatt::ExportLimit::PERCENTAGE, 100)
+# allow energy export to grid
+client.export_limit(inverter.deviceSn,Growatt::ExportLimit::DISABLE)
+```
+
+## Publishing
+
+1. Update version in [version.rb](lib/growatt/version.rb).
+2. Add release to [CHANGELOG.md](CHANGELOG.md)
+3. Commit.
+4. Test build.
+```
+> rake build
+
+```
+5. Release
+```
+> rake release
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jancotanis/growatt.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+"# growatt"

data/Rakefile

@@ -1,19 +1,22 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'dotenv'
-require 'rake/testtask'
-
-Dotenv.load
-
-#system './bin/cc-test-reporter before-build'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
-end
-
-require 'rubocop/rake_task'
-RuboCop::RakeTask.new
-task default: %i[test rubocop]
-#system './bin/cc-test-reporter after-build'
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'dotenv'
+require 'rake/testtask'
+
+Dotenv.load
+
+system './bin/cc-test-reporter before-build'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+  at_exit do
+    system './bin/cc-test-reporter after-build'
+  end
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+task default: %i[test rubocop]
+

data/growatt.gemspec

@@ -1,37 +1,37 @@
-# frozen_string_literal: true
-
-require_relative 'lib/growatt/version'
-
-Gem::Specification.new do |s|
-  s.name        = 'growatt'
-  s.version     = Growatt::VERSION
-  s.authors     = ['Janco Tanis']
-  s.email       = 'gems@jancology.com'
-  s.license     = 'MIT'
-
-  s.summary     = 'A Ruby wrapper for the Growatt APIs (readonly)'
-  s.homepage    = 'https://rubygems.org/gems/growatt'
-
-  s.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
-
-  s.metadata['homepage_uri'] = s.homepage
-  s.metadata['source_code_uri'] = 'https://github.com/jancotanis/growatt'
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  s.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
-  end
-  s.bindir        = 'exe'
-  s.executables   = s.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  s.require_paths = ['lib']
-
-  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.platform = Gem::Platform::RUBY
-  s.add_runtime_dependency 'wrapi', ">= 0.3.0"
-  s.add_runtime_dependency 'faraday-cookie_jar'
-  s.add_development_dependency 'dotenv'
-  s.add_development_dependency 'minitest'
-  s.add_development_dependency 'simplecov'
-  s.add_development_dependency 'rubocop'
-end
+# frozen_string_literal: true
+
+require_relative 'lib/growatt/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'growatt'
+  s.version     = Growatt::VERSION
+  s.authors     = ['Janco Tanis']
+  s.email       = 'gems@jancology.com'
+  s.license     = 'MIT'
+
+  s.summary     = 'A Ruby wrapper for the Growatt APIs (readonly)'
+  s.homepage    = 'https://rubygems.org/gems/growatt'
+
+  s.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
+
+  s.metadata['homepage_uri'] = s.homepage
+  s.metadata['source_code_uri'] = 'https://github.com/jancotanis/growatt'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  s.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  s.bindir        = 'exe'
+  s.executables   = s.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.platform = Gem::Platform::RUBY
+  s.add_runtime_dependency 'wrapi', ">= 0.3.0"
+  s.add_runtime_dependency 'faraday-cookie_jar'
+  s.add_development_dependency 'dotenv'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rubocop'
+end

data/lib/growatt/api.rb

@@ -1,35 +1,59 @@
-require "wrapi"
-require File.expand_path('authorization', __dir__)
-require File.expand_path('connection', __dir__)
-
-module Growatt
-  # @private
-  class API
-
-    # @private
-    attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
-
-    # Creates a new API and copies settings from singleton
-    def initialize(options = {})
-      options = Growatt.options.merge(options)
-      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
-        send("#{key}=", options[key])
-      end
-    end
-
-    def config
-      conf = {}
-      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
-        conf[key] = send key
-      end
-      conf
-    end
-
-    include WrAPI::Connection
-    include Connection
-    include WrAPI::Request
-    include WrAPI::Authentication
-    include Authentication
-
-  end
-end
+# frozen_string_literal: true
+
+require 'wrapi'
+require File.expand_path('authorization', __dir__)
+require File.expand_path('connection', __dir__)
+
+module Growatt
+  # The `API` class is an internal component of the Growatt module.
+  # It is responsible for managing API configurations, connections, and authentication.
+  #
+  # This class should not be accessed directly. Instead, use `Growatt.client` to interact with the API.
+  #
+  class API
+    # Attribute accessors for all valid configuration options.
+    #
+    # These options are defined in `WrAPI::Configuration::VALID_OPTIONS_KEYS`.
+    attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
+
+    # Initializes a new `Growatt::API` instance.
+    #
+    # This method copies configuration settings from the Growatt module singleton and allows
+    # for optional overrides through the `options` parameter.
+    #
+    # @param options [Hash] Optional configuration overrides.
+    #
+    # @example Creating an API instance with custom options:
+    #   api = Growatt::API.new(user_agent: "CustomClient/1.0")
+    #
+    def initialize(options = {})
+      options = Growatt.options.merge(options)
+      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    # Retrieves the current API configuration as a hash.
+    #
+    # @return [Hash] A hash containing the current API configuration.
+    #
+    # @example Getting the current configuration:
+    #   api.config # => { endpoint: "https://server.growatt.com/", user_agent: "Ruby Growatt API client ..." }
+    #
+    def config
+      conf = {}
+      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
+        conf[key] = send key
+      end
+      conf
+    end
+
+    # Includes required modules for making API requests, handling authentication,
+    # and establishing connections.
+    include WrAPI::Connection
+    include Connection
+    include WrAPI::Request
+    include WrAPI::Authentication
+    include Authentication
+  end
+end