Project

sma_api

0.0
The project is in a healthy, maintained state
Extract data from a SMA Inverter web interface.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Development

~> 11.1, >= 11.1.3
~> 13.0
~> 3.9
~> 0.82.0
~> 5.1
~> 3.8, >= 3.8.3
~> 2.1
 Project Readme

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:

gem '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

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.

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.

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 }

How to get the keys for get_values method

The get_values method accepts an array of keys. These keys can be found using the SMA web interface. Use the browser Developer Tools to find the keys. In the example below, the key for "Power" (Dutch: "Vermogen") is 6100_40263F00

image

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.