sma_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 568631fddbba2a58f8967bcc1e794502c2d79fef112429b48b98ce8120ece476
+  data.tar.gz: 1cf5bfdb6f873b24e6364abacde7adea8886415f58e0c5629fcddfd7d8ccef90
+SHA512:
+  metadata.gz: 6c3d0d6bd0f85f2cbd16ee090951bf0482cfedd13496d1852f3022ef15ca6d343fc566ca8ac12810c90f208cce3182db6815db74c6fb04f1959b763fee6bf7f7
+  data.tar.gz: 5d3db35181b73f5e64e61108f82aa46839f1ad92cad958ed5e56567c6c7be4a977013ad1fd14cec511b26a29bbbf9dc260728b1305dcf7b06293ae277c58b0e4

data/License.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Rutger Wessels
+
+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,110 @@
+# SmaApi
+
+This gem provides an API for the web interface of SMA inverters.
+
+The gem is in early development and should not be considered stable. Everything might change.
+
+## Supported inverters
+
+This gem has been developed using a SMA Sunny Boy 3.0 (SB3.0-1AV-41 902).
+Firmware version is 3.10.18.R
+
+It will probably work with other SMA products that have a recent firmware. But
+it has not been tested.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sma_api', git: 'https://github.com/rutgerw/sma_api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sma_api
+
+## Usage
+
+The web interface of the inverter does not allow an unlimited number of sessions.
+There seems to be a limit of 4 sessions. Another attempt to login will result into
+an error message from the web interface, which is turned into a `SmaApi::Error`
+that has the `Creating session failed` message. The software in the inverter will
+free up a session after a 5 minute inactivity.
+
+There are different ways of handling the session:
+- Create the `SmaApi::Client` instance just once and use it multiple times
+- Store the session id in a cache (file, Redis or another solution)
+- Use `client.destroy_session` to explicitly remove the session
+
+### Create client once
+
+```ruby
+require 'sma_api'
+
+client = SmaApi::Client.new(host: 'inverter address', password: 'password')
+
+while true do
+  # Current production
+  puts client.get_values(['6100_40263F00'])
+  sleep 5
+end
+```
+
+### Cache the session id
+
+In case the `sid` is not valid anymore, the client will try to create a new session.
+
+```ruby
+require 'sma_api'
+
+# Cache the sid in this file
+sid_file = '/tmp/sma_sid.txt'
+
+sid = File.read(sid_file).chop rescue ''
+
+client = SmaApi::Client.new(host: ENV['SMA_API_HOST'], password: ENV['SMA_API_WEB_PASSWORD'], sid: sid)
+
+while true do
+  current_yield = client.get_values(['6100_40263F00'])
+
+  # If sid has been changed, save it to the sid file
+  if client.sid != sid
+    File.open(sid_file, 'w') { |f| f.puts sid }
+  end
+
+  puts "#{Time.now}\tCurrent yield: #{current_yield}"
+
+  sleep 2
+end
+```
+
+### Use destroy_session
+
+This is the same as logging out from the web interface.
+
+```ruby
+require 'sma_api'
+
+client = SmaApi::Client.new(host: 'inverter address', password: 'password', sid: sid)
+
+# Current production
+puts client.get_values(['6100_40263F00'])
+
+client.destroy_session
+
+# or:
+at_exit { client.destroy_session }
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rutgerw/sma_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/sma_api.rb

@@ -0,0 +1,9 @@
+require "sma_api/client"
+require "sma_api/http"
+require "sma_api/version"
+
+
+module SmaApi
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/sma_api/client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SmaApi
+  # Ruby client for communicating with SMA Inverter web interface
+  class Client
+    def initialize(host:, password:, sid: nil)
+      @host = host
+      @password = password
+      @client = Http.new(host: host, password: password, sid: sid)
+    end
+
+    # The current session id. If empty, it will create a new session
+    #
+    # @return [String] the session id that will be used in subsequent requests.
+    def sid
+      @client.sid
+    end
+
+    # Logout and clear the session. This is the same as using Logout from the web interface
+    #
+    # @return [String] An empty session id
+    def destroy_session
+      @client.destroy_session
+    end
+
+    # Retrieve values specified by the keys using getValues.json endpoint.
+    #
+    # @param keys [Array<String>] List of keys
+    # @return [Hash] Key-value pairs
+    def get_values(keys)
+      result = @client.post('/dyn/getValues.json', { destDev: [], keys: keys })
+      return nil unless result['result']
+
+      keys.each_with_object({}) do |k, h|
+        h[k] = scalar_value(result['result'].first[1][k])
+      end
+    end
+
+    # Retrieve list of files and directories for the path.
+    #
+    # @return [Array] List of directories and files
+    def get_fs(path)
+      result = @client.post('/dyn/getFS.json', { destDev: [], path: path })
+
+      result['result'].first[1][path].map do |f|
+        type = f.key?('f') ? 'f' : 'd'
+        {
+          name: f['d'] || f['f'],
+          type: type,
+          last_modified: Time.at(f['tm']),
+          size: f['s']
+        }
+      end
+    end
+
+    # Download the file specified by url and store it in a file on the local file system.
+    #
+    # @param url [String] URL without /fs prefix. It should start with a '/'
+    # @param path [String] Path of the local file
+    def download(path, target)
+      @client.download(path, target)
+    end
+
+    # ObjectMetadata_Istl endpoint
+    #
+    # @return [Array] List of available object metadata
+    def object_metadata
+      @client.post('/data/ObjectMetadata_Istl.json')
+    end
+
+    private
+
+    def scalar_value(value)
+      value['1'].first['val']
+    end
+  end
+end

data/lib/sma_api/http.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module SmaApi
+  # Net::HTTP wrapper for the SMA Inverter web interface
+  class Http
+    def initialize(host:, password:, sid: nil)
+      @host = host
+      @password = password
+      @sid = sid || ''
+    end
+
+    # Perform a HTTP POST.
+    #
+    # @param url [String] URL. It should start with a '/'
+    # @param payload [Hash] The payload that will be used in the post
+    # @return [Hash] The response
+    def post(url, payload = {})
+      create_session if @sid.empty?
+
+      response = JSON.parse(http.post(url_with_sid(url), payload.to_json).body)
+
+      return response unless response.key? 'err'
+
+      raise SmaApi::Error, "Error #{response['err']} during request" unless response['err'] == 401
+
+      create_session
+      post(url, payload)
+    end
+
+    # Download the file specified by url and store it in a file on the local file system.
+    #
+    # @param url [String] URL without /fs prefix. It should start with a '/'
+    # @param path [String] Path of the local file
+    def download(url, path)
+      create_session if @sid.empty?
+
+      file = File.open(path, 'wb')
+
+      begin
+        res = retrieve_file(url)
+
+        file.write(res.body)
+      ensure
+        file.close
+      end
+    end
+
+    # Creates a session using the supplied password
+    #
+    # @raise [SmaApi::Error] Creating session failed, for example if the password is wrong
+    # @return [String] the session id that will be used in subsequent requests.
+    def create_session
+      payload = {
+        right: 'usr', pass: @password
+      }
+      result = JSON.parse(http.post('/dyn/login.json', payload.to_json).body).fetch('result', {})
+
+      raise SmaApi::Error, 'Creating session failed' unless result['sid']
+
+      @sid = result['sid']
+    end
+
+    # The current session id. If empty, it will create a new session
+    #
+    # @return [String] the session id that will be used in subsequent requests.
+    def sid
+      create_session if @sid.empty?
+
+      @sid
+    end
+
+    # Logout and clear the session. This is the same as using Logout from the web interface
+    #
+    # @return [String] An empty session id
+    def destroy_session
+      post('/dyn/logout.json', {})
+
+      @sid = ''
+    end
+
+    private
+
+    def url_with_sid(url)
+      url + "?sid=#{@sid}"
+    end
+
+    def retrieve_file(url)
+      res = http.get('/fs' + url_with_sid(url))
+
+      unless res.code == '200'
+        # Try again because invalid sid does not result in a 401
+        create_session
+        res = http.get('/fs' + url_with_sid(url))
+
+        raise "Error retrieving file (#{res.code} #{res.message})" unless res.code == '200'
+      end
+
+      res
+    end
+
+    def http
+      @http ||= configure_http_client
+    end
+
+    def configure_http_client
+      client =  Net::HTTP.new(@host, 443)
+      client.use_ssl = true
+      client.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+      client
+    end
+  end
+end

data/lib/sma_api/version.rb

@@ -0,0 +1,3 @@
+module SmaApi
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: sma_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rutger Wessels
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-07-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.39'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.39'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+description: Extract data from a SMA Inverter web interface.
+email:
+- rutger@rutgerwessels.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- License.txt
+- README.md
+- lib/sma_api.rb
+- lib/sma_api/client.rb
+- lib/sma_api/http.rb
+- lib/sma_api/version.rb
+homepage: https://github.com/rutgerw/sma_api
+licenses:
+- MIT
+metadata: {}
+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.1.2
+signing_key: 
+specification_version: 4
+summary: Extract data from a SMA Inverter web interface.
+test_files: []