Web service that provides a REST API layer over various cloud sites/services/APIs to get statistical data of your solar panels.
Go to file
Paul van Tilburg 03c51e2a2c
Check and lint using Cargo / Check and lint (push) Successful in 2m10s Details
Release / Release (push) Successful in 1m14s Details
Release / Release Rust crate (push) Successful in 2m53s Details
Release / Release Docker image (push) Successful in 8m41s Details
Bump the version to 0.3.5
2024-02-27 15:37:56 +01:00
.gitea/workflows Fix and improve the release workflow 2023-08-26 11:47:31 +02:00
debian Add Debian packaging via cargo-deb (closes: #4) 2023-01-10 16:59:20 +01:00
src Fix clippy issue 2024-02-27 15:37:05 +01:00
.dockerignore Fix missing build script/git repo during build 2023-03-22 15:27:12 +01:00
.gitignore Add missing .gitignore 2023-01-09 21:35:41 +01:00
CHANGELOG.md Update the changelog 2024-02-27 15:37:35 +01:00
Cargo.lock Bump the version to 0.3.5 2024-02-27 15:37:56 +01:00
Cargo.toml Bump the version to 0.3.5 2024-02-27 15:37:56 +01:00
Dockerfile Switch to Debian bookworm Docker image for runtime 2023-08-27 13:28:28 +02:00
LICENSE Initial import into Git 2023-01-08 15:39:14 +01:00
README.md Add a /version API endpoint 2023-01-29 15:29:32 +01:00
Rocket.toml.example Switch the example port to 2399 2023-01-10 17:00:20 +01:00
build.rs Update build dependecy on the vergen crate to 8.1.1 2023-04-14 23:25:25 +02:00
docker-compose.yml Clarify config necessary for exposing container port 2023-01-13 11:57:24 +01:00

README.md

Solar Grabber

Solar Grabber is a web service that provides a REST API layer over various cloud sites/services/APIs to get statistical data of your solar panels.

The services that are currently supported are Hoymiles and My Autarco.

Building & running

First, you need to provide settings in the file Rocket.toml by setting the username, password and other cloud service-specific settings. You can copy and modify Rocket.toml.example for this and uncomment the part relevant for the service you want to use. For example, to configure Solar Grabber to use the My Autarco service:

[default]
# ...

# Put your solar cloud service settings below and uncomment them based on the
# service you want to use.
[default.service]
kind = "MyAutarco"
username = "foo@domain.tld"
password = "secret"
site_id = "abc123de"

You can also change this configuration to use a different address and/or port. (Note that Rocket listens on 127.0.0.1:8000 by default for debug builds, i.e. builds when you don't add --release.)

[default]
address = "0.0.0.0"
port = 2399

# ...

This will work independent of the type of build. For more about Rocket's configuration, see: https://rocket.rs/v0.5-rc/guide/configuration/.

Using Cargo

Using Cargo it is easy to build and run Solar Grabber. just run:

$ cargo run --release
...
   Compiling solar-grabber v0.1.0 (/path/to/solar-grabber)
    Finished release [optimized] target(s) in 9m 26s
     Running `/path/to/solar-grabber/target/release/solar-grabber`

Using Docker (Compose)

Using Docker Compose it is easy (to build and) run using a Docker image. If you do not change docker-compose.yml it will use Rocket.toml from the current working directory as configuration:

$ docker-compose up
...

Ensure that Rocket.toml listens on address 0.0.0.0 port 8000 for the exposing of the container port to the outside to work!

Alternatively, to use Docker directly, run to build an image and the run it:

$ docker build --rm --tag solar-grabber:latest .
...
$ docker run --rm -v ./Rocket.toml:/app/Rocket.toml -p 2399:8000 solar-grabber:latest
...

This also uses Rocket.toml from the current working directory as configuration. You can alternatively pass a set of environment variables instead. See docker-compose.yml for a list.

Status API Endpoint

The / API endpoint provides the current statistical data of your solar panels once it has successfully logged into the cloud service using your credentials. There is no path and no query parameters, just:

GET /

Status API Response

The response uses the JSON format and typically looks like this:

{"current_w":23.0,"total_kwh":6159.0,"last_updated":1661194620}

This contains the current production power (current_w) in Watt, the total of produced energy since installation (total_kwh) in kilowatt-hour and the (UNIX) timestamp that indicates when the information was last updated.

(Status) API Error Response

If the API endpoint is accessed before any statistical data has been retrieved, or if any other request than GET / is made, an error response is returned that looks like this:

{"error":"No status found (yet)"}

Version API Endpoint

The /version endpoint provides information of the current version and build of the service. This can be used to check if it needs to be updated. Again, there is no path and no query parameters, just:

GET /version

Version API Response

The response uses the JSON format and typically looks like this:

{"version":"0.2.1","timestamp":"2023-01-29T14:10:24.971748027Z","git_sha":"5cbc3a04","git_timestamp":"2023-01-16T20:18:20Z"}

(Build and git information may be out of date.)

Integration in Home Assistant

To integrate the Solar Grabber service in your Home Assistant installation, add the following three sensor entity definitions to your configuration YAML and restart:

sensors:
  # ...Already exiting sensor definitions...

  - platform: rest
    name: "Photovoltaic Invertor"
    resource: "http://solar-grabber.domain.tld:2399"
    json_attributes:
      - current_w
      - total_kwh
      - last_updated
    value_template: >
      {% if value_json["current_w"] == 0 %}
        off
      {% elif value_json["current_w"] > 0 %}
        on
      {% endif %}      

  - platform: rest
    name: "Photovoltaic Invertor Power Production"
    resource: "http://solar-grabber.domain.tld:2399"
    value_template: '{{ value_json.current_w }}'
    unit_of_measurement: W
    device_class: power
    state_class: measurement

  - platform: rest
    name: "Photovoltaic Invertor Total Energy Production"
    resource: "http://solar-grabber.domain.tld:2399"
    value_template: '{{ value_json.total_kwh }}'
    unit_of_measurement: kWh
    device_class: energy
    state_class: total_increasing

This assumes your Solar Grabber is running at http://solar-grabber.domain.tld:2399. Replace this with the URL where Solar Grabber is actually running. Also, feel free to change the names of the sensor entities.

These sensors use the RESTful sensor integration, for more information see the RESTful sensor documentation.

License

Solar Grabber is licensed under the MIT license (see the LICENSE file or http://opensource.org/licenses/MIT).