Skip to content

solectrus/senec

Repository files navigation

Continuous integration wakatime Maintainability Test Coverage

Unofficial Ruby Client for SENEC Home

Access your local SENEC Solar Battery Storage System or the SENEC Cloud from Ruby.

WARNING: I'm not affiliated in any way with the SENEC company.

Inspired by:

Installation

$ gem install senec

Usage

Cloud access (V2.1, V3 and V4)

require 'senec'

# Login to the SENEC cloud
connection = Senec::Cloud::Connection.new(username: 'me@example.com', password: 'my-secret-senec-password')

# List all available systems
puts connection.systems

# => [{"id"=>"123456", "steuereinheitnummer"=>"S123XXX", "gehaeusenummer"=>"DE-V3-XXXX", "strasse"=>"Musterstraße", "hausnummer"=>"27a", "postleitzahl"=>"99999", "ort"=>"Musterort", "laendercode"=>"DE", "zeitzone"=>"Europe/Berlin", "wallboxIds"=>["1"], "systemType"=>"V3"}]

# Get the Dashboard data of first systems (without knowing the ID):
puts Senec::Cloud::Dashboard[connection].first.data

# => {"aktuell"=>
#   {"stromerzeugung"=>{"wert"=>0.01, "einheit"=>"W"},
#    "stromverbrauch"=>{"wert"=>860.0, "einheit"=>"W"},
#    "netzeinspeisung"=>{"wert"=>0.01, "einheit"=>"W"},
#    "netzbezug"=>{"wert"=>852.6270000000001, "einheit"=>"W"},
#    "speicherbeladung"=>{"wert"=>0.01, "einheit"=>"W"},
#    "speicherentnahme"=>{"wert"=>11.68, "einheit"=>"W"},
#    "speicherfuellstand"=>{"wert"=>1.0e-05, "einheit"=>"%"},
#    "autarkie"=>{"wert"=>1.35, "einheit"=>"%"},
#    "wallbox"=>{"wert"=>0.01, "einheit"=>"W"}},
#  "heute"=>
#   {"stromerzeugung"=>{"wert"=>3339.84375, "einheit"=>"Wh"},
#    "stromverbrauch"=>{"wert"=>21000.0, "einheit"=>"Wh"},
#    "netzeinspeisung"=>{"wert"=>13.671875, "einheit"=>"Wh"},
#    "netzbezug"=>{"wert"=>17546.38671875, "einheit"=>"Wh"},
#    "speicherbeladung"=>{"wert"=>119.140625, "einheit"=>"Wh"},
#    "speicherentnahme"=>{"wert"=>254.39453125, "einheit"=>"Wh"},
#    "speicherfuellstand"=>{"wert"=>0.0, "einheit"=>"%"},
#    "autarkie"=>{"wert"=>16.47, "einheit"=>"%"},
#    "wallbox"=>{"wert"=>0.0, "einheit"=>"Wh"}},
#  "zeitstempel"=>"2023-11-26T18:45:23Z",
#  "electricVehicleConnected"=>false}

# Get the Dashboard data of a specific system (by ID):
puts Senec::Cloud::Dashboard[connection].find("123456").data

# => {"aktuell"=>
#   {"stromerzeugung"=>{"wert"=>0.01, "einheit"=>"W"},
# ....

# Get the Technical Data of a specific system (by ID):

puts Senec::Cloud::TechnicalData[connection].find("123456").data

# => {"systemOverview"=>{"systemId"=>123456, "productName"=>"SENEC.Home V3 hybrid duo", ...

# Get the Technical Data of first systems (without knowing the ID):

puts Senec::Cloud::TechnicalData[connection].first.data

# => {"systemOverview"=>{"systemId"=>123456, "productName"=>"SENEC.Home V3 hybrid duo", ...

Local access (V2.1 and V3 only)

require 'senec'

connection = Senec::Local::Connection.new(host: '192.168.178.123', schema: 'https')
request = Senec::Local::Request.new(connection:)

puts "PV production: #{request.inverter_power} W"
puts "House power consumption: #{request.house_power} W"
puts "\n"
puts "Battery charge power: #{request.bat_power} W"
puts "Battery fuel charge: #{request.bat_fuel_charge} %"
puts "Battery charge current: #{request.bat_charge_current} A"
puts "Battery voltage: #{request.bat_voltage} V"
puts "\n"
puts "Case temperature: #{request.case_temp} °C"
puts "\n"
puts "Wallbox charge power: [ #{request.wallbox_charge_power.join(',')} ] W"
puts "\n"
puts "Grid power: #{request.grid_power} W"
puts "Current state of the system: #{request.current_state_code}"
puts "Measure time: #{Time.at request.measure_time}"

# Example result:
#
# PV production: 1530 W
# House power consumption: 870 W
#
# Battery charge power: 974 W
# Battery fuel charge: 11.3 %
# Battery charge current: 19.8 A
# Battery voltage: 49.2 V
#
# Case temperature: 31.3 °C
#
# Wallbox charge power: [ 8680, 0, 0, 0 ] W
#
# Grid power: 315 W
# Current state of the system: 14
# Measure time: 2021-10-06 17:50:22 +0200

To get the state name (in English, German or Italian) instead of just the number:

# Get a Hash with all available state names:
state_names = Senec::State.new(connection:).names(language: :de) # or :en or :it
# Use this hash for the number => string mapping:
request = Senec::Request.new(connection:, state_names:)

puts request.current_state_name
# => "LADEN"

The state names are extracted from the JavaScript source code returned by the SENEC web interface.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. 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 tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/solectrus/senec. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Copyright (c) 2020-2024 Georg Ledermann

Code of Conduct

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.