alpha_ess 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68832aefca51b56b3377029413e5e45c0becbb9cc013c4f4bfe26fc0d34f4b72
+  data.tar.gz: '032388588e713ebaf563c051cf3908e43e8590466b090d8bb28e7ad3a68dcbb3'
+SHA512:
+  metadata.gz: cc3b2139df295df17edb54869d87bf8ff60c7c9b3cb03811ecc8af7ac1d9b87af748ba5d1608b62555eb3b5cac445e7d5e3a448d2ec07970295bfc30e30f7c30
+  data.tar.gz: 8abb15e9dfe30b362b8870c55032171b2fac00a87ff14fe7d25d465aa29d6f17c3923bfcab3f1ccd5c70efb350019fea41299e3a9e9a040f3730fce16c474bd4

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2022 Oliver Gaida
+
+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,144 @@
+# Was haben wir hier?
+
+API-Calls für Alpha Ess
+
+Es gibt keine öffentliche Dokumentation zur aktuellen API von Alpha Ess. Ich habe den Netzwerkverkehr meines Browsers etwas unter die Lupe genommen und hier die entscheidenen Request nachgebaut.
+
+# Abgrenzung
+
+Ich übernehme keinerlei Haftung für die Verwendung dieses Ruby-Modules. Das Modul ist selbstgebaut und ist nur rudimentär getestet. Also alles komplett auf eigenes Risiko.
+
+# Installation 
+
+```bash
+gem install alpha_ess
+```
+
+# Verwendung
+
+## Umgebunsvariablen
+
+Die verwendeten Umgebungsvariablen am besten in ein Textfile schreiben, wodrin die Variablen exportiert werden und dann das Textfile in der bash sourcen.
+
+Vor der Ausführung des Ruby-Scriptes sollten folgende Umgebungsvariablen gesetzt werden:
+
+### für Alpha Ess Api
+
+ess_serial, ess_username und ess_password
+
+Das Textfile mit dem Namen `ess_env` könnte also wie folgt aussehen:
+
+```
+export ess_serial=ABC000123
+export ess_username=meine@email.de
+export ess_password=mein_password
+```
+
+dann source mit 
+
+```
+. ./ess_env
+```
+
+### für optionale pushover notifications
+
+po_user und po_token , beides über pushover Website einstellen. Pushover App gibt es für Smartphones und Tablets für einmalig 5 €.
+
+Das Textfile mit dem Namen `po_env` könnte also wie folgt aussehen:
+
+```
+export po_token=sdfisdfoiodisosdifs
+export po_user=dflgkdlkjneofifslkdnv
+```
+
+dann source mit 
+
+```
+. ./po_env
+```
+
+### Ablauf
+
+Vor dem Start des Scripts beide Env-Files sourcen und dann das Ruby-Script mit dem gewünschten Code ausführen.
+
+```bash
+. ./ess_env
+. ./po_env
+./a_ess_script.rb
+```
+
+Alternativ kann man die Variablen auch direkt im Rubyscript setzen und die Funktionen damit aufrufen:
+
+```ruby
+ae = AlphaEss.new(ess_serial, ess_username, ess_password)
+...
+ae.send_pushover_alarm_by_soc("Nachrichtentext ...", po_user, po_token)
+```
+
+## Datenstruktur selbst erkunden
+
+Wenn ihr wissen wollt, was die einzelnen Funktionen zurückgeben und wo ihr welche Daten findet, dann probiert es einfach aus. Ich werde sicherlich bald ein youtube Video dazu machen, wo ich das vorführe.
+
+Folgende 3 Funktionen für das Abholen von Daten gibt es derzeit:
+
+- get_stics_by_day, bringt statische Daten des Tages
+- get_last_power_data, bringt aktuelle Betriebsdaten (momentaner Verbrauch / Erzeugung etc.)
+- get_custom_use_ess_setting, holt Daten zur aktuellen Systemeinstellung
+
+## aktuellen Status abfragen
+
+Die Daten über `/api/ESS/GetLastPowerDataBySN` werden alle 10 Sekunden von der API neu bereitgestellt.
+
+```ruby
+load "alpha_ess.rb" # require "alpha_ess"
+ae = AlphaEss.new
+data = ae.get_last_power_data()
+netz = data["pmeter_l1"].to_f + data["pmeter_l2"].to_f + data["pmeter_l3"].to_f
+
+puts "
+
+    Batteriestatus: #{data["soc"]}
+    PV-Leistung: #{data["ppv1"]}
+    Netzbezug / Einspeisung: #{netz}
+    Batteriebezug / Ladung: #{data["pbat"]}
+    Verbrauch: #{data["pbat"] + data["ppv1"].to_f + netz}
+
+    
+"
+```
+
+Hier die Ausgabe und der Vergleich zur Website:
+
+![picture 1](images/b965404834760626afe73785811995faa1629d2ab66a53f966443fbf22463a67.png)  
+
+
+## pushover Alarm auslösen, wenn die PV-Anlage einen speziellen Status hat
+
+```ruby
+load "alpha_ess.rb"
+ae = AlphaEss.new
+ae_data = ae.get_last_power_data()
+batterie_ladung_erwartet = 40
+if (ae_data["soc"].to_f < soc_expexcted) 
+    ae.send_pushover_alarm_by_soc "Die Batterie hat aktuell weniger als #{soc_expexcted} % Ladung!"
+end
+# ae.set_min_soc(((ae_data["soc"].to_f)+0.9).to_i)
+# sleep 10
+min_netzbezug_erwartet = 50 # Watt
+aktueller_netzbezug = ae_data["pmeter_l1"].to_f + ae_data["pmeter_l2"].to_f + ae_data["pmeter_l3"].to_f
+if (aktueller_netzbezug < min_netzbezug_erwartet)
+    ae.send_pushover_alarm_by_soc "Stromausfall ???"
+end
+```
+
+## update ESS Settings
+
+```ruby
+load "alpha_ess.rb"
+ae = AlphaEss.new
+bat_min = ae.get_custom_use_ess_setting()["bat_use_cap"]
+puts "Batterie-Minimum: #{bat_min}"
+ae.set_custom_use_ess_setting({"bat_use_cap" => 15})
+bat_min = ae.get_custom_use_ess_setting()["bat_use_cap"]
+puts "Batterie-Minimum neu: #{bat_min}"
+```

data/alpha_ess.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |spec|
+  spec.name = 'alpha_ess'
+  spec.version = '1.0'
+  spec.date = '2022-10-02'
+  spec.summary = "Alpha Ess API Calls"
+  spec.description = "a Ruby class for Alpha-Ess-API-Calls"
+  spec.authors = ["Oliver Gaida"]
+  spec.email = 'ogaida@t-online.de'
+  spec.files = `git ls-files`.split($/)
+  spec.homepage = 'https://github.com/ogaida/alpha_ess'
+  #spec.executables = %w(rusdc)
+  spec.add_runtime_dependency 'httparty'
+  #spec.add_runtime_dependency 'json', '~> 2.1', '>= 2.1.0'
+  spec.license = 'MIT'
+end

data/lib/alpha_ess.rb

@@ -0,0 +1,107 @@
+require "httparty"
+
+class AlphaEss
+
+    def initialize(sn = ENV["ess_serial"], u = ENV["ess_username"], p = ENV["ess_password"])
+        @serial, @username, @password = sn, u, p
+        get_token()
+    end
+
+    def get_stics_by_day()
+        today = Time.now.strftime("%Y-%m-%d")
+        body = {
+            "sn" => @serial,
+            "userId" => @serial,
+            "szDay" => today,
+            "isOEM" => 0,
+            "sDate" => today
+        }
+        url = "https://cloud.alphaess.com/api/Power/SticsByDay"
+        res = HTTParty.post(url, headers: header(), body: body.to_json)
+        res.parsed_response["data"]
+    end
+
+    def get_last_power_data()
+        body = {
+            "sys_sn" => @serial,
+            "noLoading" => true
+        }
+        url = "https://cloud.alphaess.com/api/ESS/GetLastPowerDataBySN"
+        res = HTTParty.post(url, headers: header(), body: body.to_json)
+        res.parsed_response["data"]
+    end
+
+    def get_custom_use_ess_setting()
+        url = "https://cloud.alphaess.com/api/Account/GetCustomUseESSSetting"
+        res = HTTParty.get(url, headers: header())
+        res.parsed_response["data"]
+    end
+
+    def set_custom_use_ess_setting(hash={})
+        data = self.get_custom_use_ess_setting
+        data.update(hash)
+        url = "https://cloud.alphaess.com/api/Account/CustomUseESSSetting"
+        res = HTTParty.post(url, headers: header(), body: data.to_json)
+    end
+
+    def send_pushover_alarm_by_soc(message, po_user = ENV["po_user"], po_token = ENV["po_token"])
+        # po_user: pushover username
+        # po_token: pushover token
+        body = {
+            "user" => po_user,
+            "token" => po_token,
+            "message" => message
+        }
+        url = "https://api.pushover.net/1/messages.json"
+        res = HTTParty.post(url, headers: {
+            "Content-Type" => "application/json;charset=UTF-8"
+        }, body: body.to_json)
+    end
+
+    private
+
+    def get_token()
+        Dir.mkdir "#{ENV["HOME"]}/.alpha_ess" if ! (Dir.exists?"#{ENV["HOME"]}/.alpha_ess")
+        read_token() if File.exists?"#{ENV["HOME"]}/.alpha_ess/token"
+        if !(defined?@token_valid_to) or @token_valid_to.to_i < (Time.now.to_i+10)
+            create_token()
+        end
+    end
+
+    def save_token()
+        cmd = %(echo "#{@token_valid_to}:#{@token}" > #{ENV["HOME"]}/.alpha_ess/token)
+        `#{cmd}`
+    end
+
+    def read_token()
+        token_valid_to, @token = File.open("#{ENV["HOME"]}/.alpha_ess/token").readline.chop.split(/:/)
+        @token_valid_to = token_valid_to.to_i
+    end
+
+    def create_token()
+        url = "https://cloud.alphaess.com/api/Account/Login"
+        body = {
+            "username" => @username,
+            "password" => @password
+        }
+        res = HTTParty.post(url, headers: {
+            "Accept" => "application/json",
+            "Content-Type" => "application/json;charset=UTF-8"
+        }, body: body.to_json)
+        @token = res.parsed_response["data"]["AccessToken"]
+        @token_valid_to = Time.now.to_i+36000
+        save_token()
+    end
+
+    def header(hash={})
+        get_token()
+        hash = {
+            "Accept" => "application/json",
+            "Content-Type" => "application/json;charset=UTF-8",
+            "Authorization" => "Bearer #{@token}"
+        }.update hash
+        hash
+    end
+end
+
+

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: alpha_ess
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Oliver Gaida
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: a Ruby class for Alpha-Ess-API-Calls
+email: ogaida@t-online.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- alpha_ess.gemspec
+- images/b965404834760626afe73785811995faa1629d2ab66a53f966443fbf22463a67.png
+- lib/alpha_ess.rb
+homepage: https://github.com/ogaida/alpha_ess
+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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Alpha Ess API Calls
+test_files: []