npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

homebridge-solaxcloud-api

v2.3.3

Published

Integrates solar production info using public Solax/QCells Cloud API into Homebridge accessories.

Downloads

246

Readme

Solax Cloud Plugin for Homebridge

npm npm verified-by-homebridge

The Solax Cloud Plugin for Homebridge was created as a platform plugin to gather data exposed by Solax inverters to the cloud through the Solax Cloud API. Please note that QCells inverters are also supported since cloud requests share a similar approach.

Now with support for multiple inverters! Sensors will be created for each of the inverters present in the configuration. Additionally, a virtual inverter named "All inverters" will be created whenever a multiple inverters configuration is present. This inverter will present summarized power and consumption figures derived from data for all the physical inverters.

As HomeKit is still clueless about what a solar panel is, this plugin exposes a set of standard HomeKit accessories though Homebridge for each configured inverter that will allow interacting and automating your smart home based on the data made available from the Solax platform:

  • PV (PV outlet with power consumption)
  • AC (Inverter AC outlet with power and total energy consumptions)
  • To Grid (Inverter to Grid outlet with power consumption)
  • To House (Inverter to House outlet with power consumption)
  • From Grid (Grid to House outlet with power consumption)
  • Update (Motion sensor)

Battery information is also provided as Homekit accessories in case there are any batteries installed for any of the configured inverters:

  • To Battery (Outlet with inverter power charging the battery)
  • From Battery (Outlet with power drawn from the battery to the inverter)
  • Battery (Battery with State of Charge information such as level or charge state)

Please note that additional accessories are created by default with smooth power consumption curves (by applying either a simple or exponential moving average to the power series). This prevents sporadic events like a cloud passing by to have an immediate affect on provided meters.

Required information

For this plugin to work, two critical pieces of information are required from Solax/QCells Cloud:

  • Token ID: Solax/Qcells users can get inverter information through the granted tokenID. You need to obtain your tokenID on the API page of Solax/Qcells cloud.
  • SN: Registration No (communication module SN) for each desired inverter.

Installation

This plugin is supported under Homebridge. It is highly recommended that you use Homebridge Config UI X to install and configure this plugin.

Manual Installation

Install this plugin using: sudo npm install -g homebridge-solaxcloud-api. Edit config.json manually to add your Solax inverters. See below for instructions on that.

Platform configuration

Minimal platform configuration is depicted by the example configuration file below:

{
  "platforms": [
    {
      "platform": "SolaxCloudAPI",
      "inverters": [
        {
          "brand": "solax",
          "tokenId": "20200722185111234567890",
          "name": "Solax",
          "sn": "ABCDEFGHIJ"
        }
      ],
    }
  ]
}

Configuration parameters are described on the table below:

| Parameter | Type | Description | Default | Mandatory? | | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------:| :------------: | | platform | string | Platform name (must be SolaxCloudAPI) | - | Y | | inverters | array | Array of configured inverters as objects with { brand: string, tokenId: string, name: string, sn: string, hasBattery: boolean }, where brand is "solax" or "qcells", tokenID is the access token retrieved from the API page of Solax/QCells Cloud, name is the inverter name, used as prefix for accessory naming, sn is the inverter registration no. (inverter module SN) and hasBattery indicates on whether this inverter is connected to a battery. | - | Y | | pollingFrequency | number | Plugin data polling frequency from Solax Cloud (in seconds) | 300 | N | | smoothingMeters | boolean | Whether to create additional meters by smoothing raw values from Solax Cloud | true | N | | smoothingMethod | string | Statistical method to use for smoothing raw values from Solax Cloud (simple or exponential moving average - "sma" or "ema") | "sma" | N | | pureHomeApp | boolean | Whether to create meters as standard accessories that can be used on the Home App (power will show as ambient light sensors) | false | N |

NOTE: The pollingFrequency parameter defaults to 300 seconds, since Solax/QCells inverters update cloud data every 5 minutes.

Configuration through the the use of Homebridge UI plugin is also available and recommended:

Non-standard characteristics

Non-standard accessory characteristics are available through the use of Eve for HomeKit app you may download from the App Store.

This will allow some non-standard characteristics to be visible along with its historical data (like power or total energy consumption), as depicted in the image below:

If you want to rely solely on the native Home App, please enable the pureHomeApp config setting. In this case, power consumption on each meter will be exposed as an Ambient Light Sensor, as shown below (minimum value for an Ambient Light Sensor is 0.1 lux):

Automation

Automation can be achieved with the help of the virtual Update motion sensor that was specifically tailored for this effect and which is available for each inverter. This motion sensor will be triggered whenever inverter data gets updated from the Solax Cloud API (according to what is defined on the pollingFrequency configuration setting).

Motion is detected by the Update motion sensor whenever there is newly fetched inverter data from Solax Cloud. Using this sensor as a trigger combined with power and energy data from the virtual outlets enumerated above forms the basic building blocks for defining an automation.

Automation example

Since automations are probably going to be dependent on the non-standard Consumption characteristics from the virtual outlets, these must created by using the Eve App.

As an automation example, let's imagine we want to turn a pool heater pump on whenever the inverter AC power is greater than a specific figure (in Watt):

TO DO

Next planned plugin releases should include:

  • [X] Inverter AC to include Total Yield Energy
  • [X] Consumption history through the fakegato-history module
  • [x] Enable support for "pure" Home App accessories (power meters will be exposed as Ambient Light sensors)
  • [x] Add "smooth" accessories for power meters (compensating for sporadic scenarios like cloud a passing)
  • [x] Support for multiple inverters
  • [x] Support for multiple brands (between Solax and QCells)
  • [x] Accessories for battery state and consumptions