growatt 0.2.0 → 0.2.1

data/lib/growatt/authorization.rb

@@ -1,36 +1,91 @@
-require 'digest'
-require File.expand_path('error', __dir__)
-
-module Growatt
-  # Deals with authentication flow and stores it within global configuration
-  module Authentication
-
-    # Authorize to the Growatt portal
-    def login()
-      raise ConfigurationError, "Username/password not set" unless username || password
-      _password = hash_password(self.password) #unless is_password_hashed
-
-      _format = self.format
-      self.format = 'x-www-form-urlencoded'
-      response = post('newTwoLoginAPI.do', {'userName': self.username, 'password': _password})
-      self.format = _format
-      data = response.body['back']
-      if data && data['success']
-        @login_data = data
-        data
-      else
-        raise AuthenticationError.new(data['error'])
-      end
-    end
-  private
-    def hash_password(password)
-      password_md5 = Digest::MD5.hexdigest(password.encode('utf-8'))
-      (0...password_md5.length).step(2) do |i|
-        if password_md5[i] == '0'
-          password_md5[i] = 'c'
-        end
-      end
-      password_md5
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'digest'
+require File.expand_path('error', __dir__)
+
+module Growatt
+  # Handles authentication flow and stores session data in the global configuration.
+  #
+  # This module provides methods for logging into the Growatt portal, hashing passwords, 
+  # and validating credentials.
+  #
+  module Authentication
+    # Logs in to the Growatt portal using the stored credentials.
+    #
+    # This method:
+    # - Validates that the username and password are set.
+    # - Hashes the password using MD5.
+    # - Sends a login request with the credentials.
+    # - Processes the server response.
+    #
+    # @raise [ConfigurationError] If username or password is missing.
+    # @raise [AuthenticationError] If authentication fails.
+    # @return [Hash] The login response data if successful.
+    #
+    # @example Logging in to Growatt:
+    #   client.login
+    #
+    def login
+      validate_credentials
+      _password = hash_password(self.password) # Hash password before sending
+
+      _format = self.format
+      self.format = 'x-www-form-urlencoded'
+      response = post('newTwoLoginAPI.do', { 'userName' => self.username, 'password' => _password })
+      self.format = _format
+      process_response(response.body['back'])
+    end
+
+  private
+
+    # Hashes the given password using MD5.
+    #
+    # This method generates an MD5 hash of the password and modifies it by replacing
+    # every occurrence of '0' at even indices with 'c'.
+    #
+    # @param password [String] The plain-text password.
+    # @return [String] The modified MD5-hashed password.
+    #
+    # @example Hashing a password:
+    #   hash_password("mypassword") # => "5f4dcc3bcfcd204e074324a5e7565eaf"
+    #
+    def hash_password(password)
+      password_md5 = Digest::MD5.hexdigest(password.encode('utf-8'))
+      (0...password_md5.length).step(2) do |i|
+        password_md5[i] = 'c' if password_md5[i] == '0'
+      end
+      password_md5
+    end
+
+    # Validates that the username and password are set.
+    #
+    # @raise [ConfigurationError] If either credential is missing.
+    #
+    # @example Checking credentials before login:
+    #   validate_credentials # Raises ConfigurationError if missing
+    #
+    def validate_credentials
+      raise ConfigurationError, "Username/password not set" unless username && password
+    end
+
+    # Processes the authentication response.
+    #
+    # If authentication is successful, stores the login data. Otherwise, raises an error.
+    #
+    # @param data [Hash] The response data from the Growatt portal.
+    # @raise [AuthenticationError] If authentication fails.
+    # @return [Hash] The login data if authentication succeeds.
+    #
+    # @example Handling a successful login:
+    #   process_response({ "success" => true }) # Returns login data
+    #
+    def process_response(data)
+      if data && data['success']
+        @login_data = data
+        data
+      else
+        raise AuthenticationError.new(data['error'])
+      end
+    end
+  end
+end

data/lib/growatt/client.rb

@@ -1,160 +1,219 @@
-require File.expand_path('api', __dir__)
-require File.expand_path('const', __dir__)
-require File.expand_path('error', __dir__)
-
-module Growatt
-  # Wrapper for the Growatt REST API
-  #
-  # @see no API documentation, reverse engineered
-  class Client < API
-
-    def initialize(options = {})
-      super(options)
-    end
-
-    # access data returned from login
-    def login_info
-      @login_data
-    end
-    def plant_list(user_id=nil)
-      user_id = login_info['user']['id'] unless user_id
-      _plant_list({'userId':user_id})
-    end
-    def plant_detail(plant_id,type=Timespan::DAY,date=Time.now)
-      _plant_detail( {
-        'plantId': plant_id,
-        'type': type,
-        'date': timespan_date(type,date)
-      })
-    end
-    def plant_info(plant_id)
-      _plant_info({
-        'op': 'getAllDeviceList',
-        'plantId': plant_id,
-        'pageNum': 1,
-        'pageSize': 1
-      })
-    end
-    def device_list(plant_id)
-      plant_info(plant_id).deviceList
-    end
-
-    def inverter_list(plant_id)
-      devices = device_list(plant_id)
-      devices.select { |device| 'inverter'.eql? device.deviceType  }
-    end
-
-    # get data for invertor control
-    def inverter_control_data(inverter_id)
-      _inverter_api({
-        'op': 'getMaxSetData',
-        'serialNum': inverter_id
-      }).obj.maxSetBean
-    end
-
-    def update_inverter_setting(serial_number,command,param_id,parameters)
-      command_parameters = {
-        'op': command,
-        'serialNum': serial_number,
-        'paramId': param_id
-      }
-      # repeated values to hash { param1: value1 }
-
-      parameters = parameters.map.with_index { |value, index| ["param#{index + 1}", value] }.to_h if parameters.is_a? Array
-      self.format = 'x-www-form-urlencoded'
-      data = JSON.parse(post('newTcpsetAPI.do',command_parameters.merge(parameters)).body)
-      self.format = :json
-      data['success']
-    end
-
-    # turn invertor on of off
-    def turn_inverter(serial_number,on=true)
-      onoff = (on ? Inverter::ON : Inverter::OFF )
-      update_inverter_setting(serial_number,'maxSetApi','max_cmd_on_off',[onoff])
-    end
-
-    # check if invertor is turned on
-    def inverter_on?(serial_number)
-      status = inverter_control_data(serial_number)
-      Inverter::ON.eql? status.max_cmd_on_off
-    end
-
-    def export_limit(serial_number,enable,value=nil)
-      if ExportLimit::DISABLE.eql? enable
-        params = [0]
-      else
-        raise ArgumentError, "exportlimitation enable should be ExportLimit::WATT or ExportLimit::PERCENTAGE" unless [ExportLimit::WATT,ExportLimit::PERCENTAGE].include? enable
-        raise ArgumentError, "Value should be set for export limitation" unless value
-        params = [1, value, enable]
-      end
-      update_inverter_setting(serial_number,'maxSetApi','backflow_setting',params)
-    end
-
-    # utility function to get date accordign timespan month/day
-    def timespan_date(timespan=Timespan::DAY,date=Time.now)
-      if Timespan::YEAR.eql? timespan
-        date.strftime("%Y")
-      elsif Timespan::MONTH.eql? timespan
-        date.strftime("%Y-%m")
-      elsif Timespan::DAY.eql? timespan
-        date.strftime("%Y-%m-%d")
-      end
-    end
-
-    #
-    # functions below are copied from python example code but not sure if these work with MOD9000 inverters
-    #
-    def inverter_data(inverter_id,type=Timespan::DAY,date=Time.now)
-      if Timespan::DAY.eql? type
-        operator = 'getInverterData_max'
-      elsif Timespan::MONTH.eql? type
-        operator = 'getMaxMonthPac'
-      elsif Timespan::YEAR.eql? type
-        operator = 'getMaxYearPac'
-      end
-      _inverter_api({
-        'op': operator,
-        'id': inverter_id,
-        'type': 1,
-        'date': timespan_date(type,date)
-      })
-    end
-=begin
-    def inverter_detail(inverter_id)
-      _inverter_api({
-        'op': 'getInverterDetailData',
-        'inverterId': inverter_id
-      })
-    end
-    def inverter_detail_two(inverter_id)
-      _inverter_api({
-        'op': 'getInverterDetailData_two',
-        'inverterId': inverter_id
-      })
-    end
-=end
-    def update_mix_inverter_setting(serial_number, setting_type, parameters)
-      update_inverter_setting(serial_number,'mixSetApiNew',setting_type,parameters)
-    end
-    def update_ac_inverter_setting(serial_number, setting_type, parameters)
-      update_inverter_setting(serial_number,'spaSetApi',setting_type,parameters)
-    end
-
-
-  private
-    def self.api_endpoint(method,path)
-      # all records
-      self.send(:define_method, method) do |params = {}|
-        # return data result
-        get(path,params) do |request|
-          request.headers['Accept'] = "application/#{format}"
-        end
-      end
-    end
-    api_endpoint :_plant_list, 'PlantListAPI.do'
-    api_endpoint :_plant_detail, 'PlantDetailAPI.do'
-    api_endpoint :_inverter_api, 'newInverterAPI.do'
-    api_endpoint :_plant_info, 'newTwoPlantAPI.do'
-
-  end
-end
+# frozen_string_literal: true
+
+require File.expand_path('api', __dir__)
+require File.expand_path('const', __dir__)
+require File.expand_path('error', __dir__)
+
+module Growatt
+  # Wrapper for the Growatt REST API
+  #
+  # This class provides methods to interact with the Growatt API, including:
+  # - Retrieving plant and inverter data
+  # - Managing inverters (turning them on/off, updating settings)
+  # - Handling authentication and session data
+  #
+  # @note No official API documentation is available; this was reverse-engineered.
+  #
+  # @see Growatt::Authentication For authentication-related logic.
+  class Client < API
+    # Initializes the Growatt API client.
+    #
+    # @param options [Hash] Additional options for the API client.
+    def initialize(options = {})
+      super(options)
+    end
+
+    # Retrieves login session data.
+    #
+    # @return [Hash, nil] The login data stored in @login_data.
+    def login_info
+      @login_data
+    end
+
+    # Retrieves a list of plants associated with a user.
+    #
+    # @param user_id [String, nil] The user ID; if nil, it defaults to the logged-in user's ID.
+    # @return [Hash] The list of plants.
+    def plant_list(user_id = nil)
+      user_id ||= login_info['user']['id']
+      _plant_list({ 'userId': user_id })
+    end
+
+    # Retrieves detailed information about a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @param type [String] The timespan type (default: `Timespan::DAY`).
+    # @param date [Time] The date for the requested timespan (default: `Time.now`).
+    # @return [Hash] The plant details.
+    def plant_detail(plant_id, type = Timespan::DAY, date = Time.now)
+      _plant_detail({
+        'plantId': plant_id,
+        'type': type,
+        'date': timespan_date(type, date)
+      })
+    end
+
+    # Retrieves plant information.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Hash] Plant information, including available devices.
+    def plant_info(plant_id)
+      _plant_info({
+        'op': 'getAllDeviceList',
+        'plantId': plant_id,
+        'pageNum': 1,
+        'pageSize': 1
+      })
+    end
+
+    # Retrieves a list of devices in a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Array] A list of devices.
+    def device_list(plant_id)
+      plant_info(plant_id).deviceList
+    end
+
+    # Retrieves a list of inverters in a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Array] A list of inverters.
+    def inverter_list(plant_id)
+      devices = device_list(plant_id)
+      devices.select { |device| 'inverter'.eql? device.deviceType }
+    end
+
+    # Retrieves data for inverter control.
+    #
+    # @param inverter_id [String] The inverter's serial number.
+    # @return [Hash] The inverter's control data.
+    def inverter_control_data(inverter_id)
+      _inverter_api({
+        'op': 'getMaxSetData',
+        'serialNum': inverter_id
+      }).obj.maxSetBean
+    end
+
+    # Updates an inverter's setting.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param command [String] The command to execute.
+    # @param param_id [String] The parameter ID.
+    # @param parameters [Array, Hash] The parameters to send.
+    # @return [Boolean] `true` if the update was successful, `false` otherwise.
+    def update_inverter_setting(serial_number, command, param_id, parameters)
+      command_parameters = {
+        'op': command,
+        'serialNum': serial_number,
+        'paramId': param_id
+      }
+
+      parameters = parameters.map.with_index { |value, index| ["param#{index + 1}", value] }.to_h if parameters.is_a? Array
+      self.format = 'x-www-form-urlencoded'
+      data = JSON.parse(post('newTcpsetAPI.do', command_parameters.merge(parameters)).body)
+      self.format = :json
+      data['success']
+    end
+
+    # Turns an inverter on or off.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param on [Boolean] `true` to turn on, `false` to turn off.
+    # @return [Boolean] `true` if the operation was successful.
+    def turn_inverter(serial_number, on = true)
+      onoff = (on ? Inverter::ON : Inverter::OFF)
+      update_inverter_setting(serial_number, 'maxSetApi', 'max_cmd_on_off', [onoff])
+    end
+
+    # Checks if an inverter is turned on.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @return [Boolean] `true` if the inverter is on, `false` otherwise.
+    def inverter_on?(serial_number)
+      status = inverter_control_data(serial_number)
+      Inverter::ON.eql? status.max_cmd_on_off
+    end
+
+    # Sets export limit for an inverter.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param enable [String] `ExportLimit::DISABLE`, `ExportLimit::WATT`, or `ExportLimit::PERCENTAGE`.
+    # @param value [Numeric, nil] The export limit value (required unless disabled).
+    # @return [Boolean] `true` if the setting update was successful.
+    def export_limit(serial_number, enable, value = nil)
+      if ExportLimit::DISABLE.eql? enable
+        params = [0]
+      else
+        validate_export_parameters(enable, value)
+        params = [1, value, enable]
+      end
+      update_inverter_setting(serial_number, 'maxSetApi', 'backflow_setting', params)
+    end
+
+    # Utility function to get a formatted date based on timespan.
+    #
+    # @param timespan [String] The timespan type (`Timespan::DAY`, `Timespan::MONTH`, `Timespan::YEAR`).
+    # @param date [Time] The date (default: `Time.now`).
+    # @return [String] The formatted date.
+    def timespan_date(timespan = Timespan::DAY, date = Time.now)
+      case timespan
+      when Timespan::YEAR
+        date.strftime("%Y")
+      when Timespan::MONTH
+        date.strftime("%Y-%m")
+      when Timespan::DAY
+        date.strftime("%Y-%m-%d")
+      end
+    end
+
+    # Retrieves inverter data based on timespan.
+    #
+    # @param inverter_id [String] The inverter's ID.
+    # @param type [String] The timespan type.
+    # @param date [Time] The date (default: `Time.now`).
+    # @return [Hash] The inverter data.
+    def inverter_data(inverter_id, type = Timespan::DAY, date = Time.now)
+      operator =
+        case type
+        when Timespan::DAY then 'getInverterData_max'
+        when Timespan::MONTH then 'getMaxMonthPac'
+        when Timespan::YEAR then 'getMaxYearPac'
+        end
+
+      _inverter_api({
+        'op': operator,
+        'id': inverter_id,
+        'type': 1,
+        'date': timespan_date(type, date)
+      })
+    end
+
+    private
+
+    # Defines API endpoints dynamically.
+    #
+    # @param method [Symbol] The method name.
+    # @param path [String] The API endpoint.
+    def self.api_endpoint(method, path)
+      define_method(method) do |params = {}|
+        get(path, params) do |request|
+          request.headers['Accept'] = "application/#{format}"
+        end
+      end
+    end
+
+    api_endpoint :_plant_list, 'PlantListAPI.do'
+    api_endpoint :_plant_detail, 'PlantDetailAPI.do'
+    api_endpoint :_inverter_api, 'newInverterAPI.do'
+    api_endpoint :_plant_info, 'newTwoPlantAPI.do'
+
+    # Validates export limitation parameters.
+    def validate_export_parameters(enable, value)
+      unless [ExportLimit::WATT, ExportLimit::PERCENTAGE].include?(enable)
+        raise ArgumentError, "Export limitation must be ExportLimit::WATT or ExportLimit::PERCENTAGE"
+      end
+      raise ArgumentError, "Value is required" unless value
+      raise ArgumentError, "Value must be numeric" unless value.is_a? Numeric
+    end
+  end
+end

data/lib/growatt/connection.rb

@@ -1,26 +1,45 @@
-require 'faraday'
-require 'faraday-cookie_jar'
-
-module Growatt
-  # Create connection and use cookies for authentication tokens
-  module Connection
-    def connection
-      raise ConfigurationError, "Option for endpoint is not defined" unless endpoint
-
-      options = setup_options
-      @connection ||= Faraday::Connection.new(options) do |connection|
-        connection.use :cookie_jar
-
-        connection.use Faraday::Response::RaiseError
-        connection.adapter Faraday.default_adapter
-        setup_authorization(connection)
-        setup_headers(connection)
-        connection.response :json, content_type: /\bjson$/
-        connection.use Faraday::Request::UrlEncoded
-
-        setup_logger_filtering(connection, logger) if logger
-      end
-    end
-
-  end
-end
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday-cookie_jar'
+
+module Growatt
+  # Handles HTTP connection setup and authentication management.
+  #
+  # This module establishes a Faraday connection to interact with the Growatt API,
+  # ensuring proper authentication via cookies and setting up required headers.
+  module Connection
+    # Establishes a Faraday connection with appropriate middleware and settings.
+    #
+    # @return [Faraday::Connection] The configured Faraday connection instance.
+    # @raise [ConfigurationError] If the API endpoint is not defined.
+    def connection
+      raise ConfigurationError, "Option for endpoint is not defined" unless endpoint
+
+      options = setup_options
+      @connection ||= Faraday::Connection.new(options) do |connection|
+        # Enable cookie-based authentication
+        connection.use :cookie_jar
+
+        # Handle HTTP response errors
+        connection.use Faraday::Response::RaiseError
+
+        # Set up default Faraday adapter
+        connection.adapter Faraday.default_adapter
+
+        # Configure authentication and request headers
+        setup_authorization(connection)
+        setup_headers(connection)
+
+        # Parse JSON responses automatically
+        connection.response :json, content_type: /\bjson$/
+
+        # Ensure requests are URL-encoded
+        connection.use Faraday::Request::UrlEncoded
+
+        # Configure logging if a logger is present
+        setup_logger_filtering(connection, logger) if logger
+      end
+    end
+  end
+end

data/lib/growatt/const.rb

@@ -1,29 +1,47 @@
-
-module Growatt
-  class Enum
-      def self.enum(array)
-        array.each do |c|
-          const_set c,c
-        end
-      end
-  end
-
-  class Timespan
-    HOUR = 0
-    DAY = 1
-    MONTH = 2
-    YEAR = 3
-  end
-
-  class Inverter
-    ON = "0101"
-    OFF = "0000"
-  end
-
-  class ExportLimit
-    DISABLE = -1
-    WATT = 1
-    PERCENTAGE = 0
-  end
-
-end
+# frozen_string_literal: true
+
+module Growatt
+  # A base class for defining enumerations using constants.
+  #
+  # This class dynamically defines constants from an array of strings.
+  class Enum
+    # Defines constants based on the provided array.
+    #
+    # @param array [Array<String>] The array of strings to be converted into constants.
+    def self.enum(array)
+      array.each do |c|
+        const_set c, c
+      end
+    end
+  end
+
+  # Represents different timespan options for data retrieval.
+  class Timespan
+    # Hourly data timespan
+    HOUR = 0
+    # Daily data timespan
+    DAY = 1
+    # Monthly data timespan
+    MONTH = 2
+    # Yearly data timespan
+    YEAR = 3
+  end
+
+  # Represents possible states for an inverter.
+  class Inverter
+    # Inverter is turned on
+    ON = "0101"
+    # Inverter is turned off
+    OFF = "0000"
+  end
+
+  # Represents export limit settings for an inverter.
+  class ExportLimit
+    # Disables export limitation
+    DISABLE = -1
+    # Export limit is set in watts
+    WATT = 1
+    # Export limit is set in percentage
+    PERCENTAGE = 0
+  end
+end