Skip to content

Latest commit

 

History

History
158 lines (116 loc) · 4.66 KB

README.md

File metadata and controls

158 lines (116 loc) · 4.66 KB
Raw

GoEnergy-API

build Coverage Status

GoSMAApi provides tooling for interacting with plants of SMA devices. Included are a CLI Application and a Server providing an API for interacting with SunSpec compatible plants.

Table of Contents

Energy-CLI

The application provides a simple command-line application for retrieving data from a plant using SunSpec compatible devices.

Documentation is provided by calling energy-cli help.

Fetch

fetch fetches data from a plant. It automatically detects the device type (e.g. PV-Inverter, Battery-Inverter). The data is refreshed every 10 seconds.

If the device implements a register containing a valid device address, the address is set automatically. Else, a modbus slave id can be provided using the -id parameter.

This table contains some slave IDs:

Manufacturer Slave ID
SMA 126

In case the manufacturer of your inverter isn't listed here, you can probably find some documentation by searching for < your device > modbus api.

Example:

Given three devices with the following IP addresses:

Device IP
SMA Sunny Boy 2.5 192.1.1.1
SMA Sunny Boy 6.0 192.1.1.2
SMA Sunny Boy Storage 6.0 192.1.1.3

First, the modbus (TCP) functionality must be unlocked using the configuration interface of the device. With SMA devices we can also set a custom port there, the standard port is 502.

The command should then be energy-cli fetch -id 126 -a 192.1.1.1:502 -a 192.1.1.2:502 -a 192.1.1.3:502.

If everything is successful, the output resembles something similar to this:

2020/12/21 20:28:54 connecting to 192.1.1.1:502...
2020/12/21 20:28:54 connected to 192.1.1.1:502
2020/12/21 20:28:54 connecting to 192.1.1.2:502...
2020/12/21 20:28:54 connected to 192.1.1.2:502
2020/12/21 20:28:54 connecting to 192.1.1.3:502...
2020/12/21 20:28:54 connected to 192.1.1.3:502
+--------------------+-------+-----+
|      ADDRESS       | POWER | SOC |
+--------------------+-------+-----+
| 192.168.1.1:502    | 123W  |     |
| 192.168.1.2:502    | 300W  |     |
| 192.168.1.3:502    | -20W  | 68% |
+--------------------+-------+-----+

Energy-API

The server provides access to aggregated data of a plant via an HTTP API. A configuration file describing the plant and its devices is required.

Data is fetched after a message from the plant's energy meter is received, to retrieve the most accurate data for a point in time. By default, the energymeter sends a message each second, resulting in a refresh interval of 1 second on the server.

Configuration

Environment Variables:

Environment Variable Info Default
ENERGY_PORT Port of the server 8080
ENERGY_CONFIG_PATH Path to the plant config .

Plant config:

The server must be configured using a .yml file, called plants.yml.

Example:

plant1: # name of the plant
  sunspec: # SunSpec compatible devices
    - "192.168.188.30:502" # ip address pointing to a modbus TCP endpoint
    - "192.168.188.31:502"
    - "192.168.188.32:502"
    - "192.168.188.34:502"
  energymeter: "1901401956" # energymeter serial number
plant2:
  sunspec:
    - "192.168.188.35:502"
    - "192.168.188.36:502"
  energymeter: "3006138525"

Endpoints

GET /v1/summary Returns a summary of the energy flow in one or multiple plants. The unit of each value is watts.

{
    "plant1": {
        "grid": 1.9,
        "pv": 0,
        "battery": 120,
        "selfConsumption": 121.9,
        "batterySoC": 45,
        "timestampStart": 1608579392,
        "timestampEnd": 1608579392
    },
    "plant2": {
        "grid": 929.2,
        "pv": 0,
        "battery": 0,
        "selfConsumption": 929.2,
        "batterySoC": 14,
        "timestampStart": 1608579392,
        "timestampEnd": 1608579392
    }
}

Docker

A docker image is provided for your convenience. It can be found here.

Example Usage:

docker run -v /path/to/plant.yml:/go/src/app/plants.yml -p 8080:8080 orlopau/go-energy-api

Links

Licensing

The code in this project is licensed under MIT License.