:sun_with_face: QAlphaCloud
Qt bindings for the AlphaCloud API by Alpha ESS Co., Ltd.
Table of Contents
Features
libqalphacloud
A Qt library around the AlphaCloud API. It provides both C++ and QML APIs for fetching data.
KSystemStats plug-in
A plug-in for feeding data into KDE’s System Monitor.
It enables you to create both complex monitor pages for all aspects of your solar and energy storage installation as well as add relevant meters right to your desktop.
How cool is that? You can have both CPU load and photovoltaic energy production on the same page!
KInfoCenter module
A module for displaying historic energy production and consumption data in KInfoCenter.
KInfoCenter module showing both live and historic photovoltaic information
Command-Line Interface
The library comes with a command-line interface (CLI) for easily querying data and forwarding it to your own scripts and helpers in either human-readable or JSON formats.
The --help command describes all supported arguments and endpoints.
:nerd_face: Why?
When I learned that there is an API for my solar installation, I immediately wanted to write a widget for the KDE Plasma Desktop so I could see live data anytime on my panel.
Over the course of just a few evenings I ended up creating a proper shared library that makes use of all the current best practices (automated tests and code coverage checks, full REUSE-compliance, documentation, API/ABI-compatibility guarantees, C++ and QML bindings, etc.) to show off how simple it is for a 3rd party product to make use of KDE’s libraries and how versatile they are.
KDE’s Extra CMake Modules make creating libraries with CMake a lot nicer and their powerful yet easy-to-use KQuickCharts Framework produces beautiful and fully hardware-accelerated diagrams. The KSystemStats daemon is then used to feed data into System Monitor which offers both a fully customizable UI as well as simple desktop and panel widgets.
Plasma notifying about the first ray of sun. Go start the dishwasher! (Not included in this repository yet)
While I am aware that the number of people who operate this particular system and are interested in C++/Qt development is miniscule, it’s still a useful project for me personally and is a good exercise in system integration. More importantly, though, this should serve as an inspiration for the KDE Eco initiative, for example to build an infrastructure to do system maintenance tasks such as installing updates only when the sun is shining.
:hammer: Getting Started
This project is configured using cmake and is built with Qt. It also uses some of KDE’s fantastic Frameworks.
API Keys
The API access configuration should be placed in the configuration file ~/.config/qalphacloud.ini:
To get access, sign up on Alpha Cloud Open API website, register your device using the serial number and check code written on the inverter box. You will then find the relevant AppID and Secret on the Developer Information page.
Build
Configure and run the build through cmake, for example:
Configure Options
By default, all features and dependencies (except example code) are enabled. You can disable any feature by passing the relevant -DBUILD_...=OFF switch to the cmake command:
| Option | Default | Description |
|---|---|---|
| BUILD_QML | ON | Build QML bindings |
| BUILD_KSYSTEMSTATS | ON | Build KSystemStats plug-in |
| BUILD_KINFOCENTER | ON | Build KInfoCenter module |
| BUILD_TESTING | ON | Build unit tests |
| BUILD_COVERAGE | OFF | Build with test coverage (gcov) enabled |
| BUILD_EXAMPLES | OFF | Build examples in the examples directory |
| PRESENTATION_BUILD | OFF | Hide sensitive information, such as serial numbers, for use in a presentation |
| API_URL | https://openapi.alphaess.com/api/ | API URL to use, defaults to the official endpoint |
Logging Categories
The library makes use of Categorized Logging under the qalphacloud identifier.
You can enable all debug output by running an application with:
Dependencies
This project needs Qt 5.15 and KDE Frameworks 5.80 (most notably ECM) or newer. It is possible to build just the library without the GUI components.
TL;DR
On Ubuntu 22.04 run:
The following development files are required (as well as their respective indirect dependencies):
libqalphacloud
- Qt Core and Qt Network
- Qt QML / Declarative (optional, for QML bindings)
- Qt Widgets (optional, for example code)
systemstats
- KCoreAddons (from KDE Frameworks)
- KSysGuard (from KDE Plasma)
- libsensors
infocenter
- KCoreAddons (from KDE Frameworks
- KDeclarative (from KDE Frameworks)
- KSysGuard (from KDE Plasma)
- libsensors
- QML module for Kirigami
- QML module for KQuickCharts
:electric_plug: API
You can find an extensive Doxygen documentation on GitHub Pages.
The project aims to provide ABI and API stability, however it cannot be guaranteed at this early stage of development.
Classes
All classes are found in the QAlphaCloud C++ namespace and the de.broulik.qalphacloud QML import.
QAlphaCloud *(namespace)*
Namespace with RequestStatus, SystemStatus and ErrorCode enums.
Configuration
Represents the configuration of an API consumer, i.e. the endpoint URL, App ID, and secret registered with the API.
This can either be programmatically set or read from the Configuration file mentioned above.
Connector
Represents a connection to the API with a given Configuration. This needs to be created in order to use any of the classes below.
StorageSystemsModel
Endpoint: /getEssList
Fetches the list of registered storage systems from the given Connector and provides them as a QAbstractListModel.
For convenience, the first (and typically only) serial number is offered in the primarySerialNumber property.
LastPowerData
Endpoint: /getLastPowerData
Fetches live data, such as current photovoltaic energy, battery state of charge, etc from the given Connector and serial number.
OneDateEnergy
Endpoint: /getOneDateEnergy
Fetches cumulative data energy information, such as amount of energy produced in a day, from the given Connector, serial number, and date.
OneDayPowerModel
Endpoint: /getOneDayPower
Fetches historic power data, such as a trend of photovoltaic production over a day, from the given Connector, serial number, and date, and provides them as a QAbstractListModel.
Examples
You can find examples for both C++ and QML in the examples directory.
:building_construction: To Do
- The project should be prepared for a Qt 6 build, however this has not been attempted, specifically as KDE Frameworks 6 is still in development.
- Running clang-tidy, clazy, and friends on CI
- None of the EV-related readouts are implemented.
- None of the charging configuration settings (
getChargeConfigInfo,updateChargeConfigInfo,getDisChargeConfigInfo,updateDisChargeConfigInfo) can be read or altered. - Localization. All user-visible strings are marked for translation with
trorqsTrbut the infrastructure for extracting and importing them has not been set up. - Sometimes, when rapidly switching between dates, the API returns
nullfor all fields without returning an error code. I consider this an API issue but we could do a tentative reload when this happens.
:paperclips: Licensing
This project is fully REUSE-3.0-compliant.
libqalphacloud
systemstats and infocenter
Example code and build system configuration
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Alpha ESS Co., Ltd., or any of its subsidiaries or its affiliates. The official Alpha ESS Monitoring dashboard can be found at https://cloud.alpha.ess.com.
