HYXI Cloud API

hyxi-cloud-api

PyPI Python Downloads License

Tests Coverage Security OpenSSF Scorecard

An asynchronous Python client for interacting with the HYXI Cloud API.

This library was primarily built to power the HYXI Cloud Home Assistant Integration, but it can be used in any Python 3.14 project to fetch telemetry data from HYXI solar inverters and battery systems.

📦 Installation

You can install the package directly from PyPI:

pip install hyxi-cloud-api

🚀 Quick Start

This library uses aiohttp for non-blocking network requests. You will need to provide your Developer API credentials (AK/SK), along with an active aiohttp.ClientSession.

[!NOTE] The HYXI Open API requires a separate developer account registered at open.hyxicloud.com. If your developer email is different from your main HYXI app account, you must Share your Plant from the app to your developer email address to access your data.

import asyncio
import aiohttp
from hyxi_cloud_api import HyxiApiClient

async def main():
    # Replace with your actual HYXi Cloud credentials
    ACCESS_KEY = "your_access_key"
    SECRET_KEY = "your_secret_key"
    BASE_URL = "https://open.hyxicloud.com"

    async with aiohttp.ClientSession() as session:
        # 1. Initialize the client
        client = HyxiApiClient(
            access_key=ACCESS_KEY,
            secret_key=SECRET_KEY,
            base_url=BASE_URL,
            session=session
        )

        # 2. Fetch device data
        try:
            device_data = await client.get_all_device_data()
            print("Successfully fetched HYXi data:")
            print(device_data)
        except Exception as e:
            print(f"Error communicating with HYXi Cloud: {e}")

if __name__ == "__main__":
    asyncio.run(main())

HYXI Open API base URLs vary by region. The examples in this README use the Europe endpoint by default.

Node Request Address
China https://open-cn.hyxicloud.com
Europe (default) https://open.hyxicloud.com
North America https://open-or.hyxicloud.com

🔧 Device Control

You can control inverter operating modes directly through the API. This requires a device serial number, which you can obtain from the device data response above.

async def control_example(client, device_sn):
    # Set operating mode
    await client.set_mode_self_consume(device_sn)
    await client.set_mode_charge(device_sn, watts=3000)
    await client.set_mode_discharge(device_sn, watts=2500)
    await client.set_mode_idle(device_sn)

    # Peak shaving (close, charge, discharge, stop, hold)
    await client.set_peak_shaving(device_sn, action="charge")

    # Frequency control
    await client.set_frequency_control(device_sn, enabled=True)

Control failures raise HyxiApiClient.ControlError:

try:
    await client.set_mode_charge(device_sn, watts=3000)
except client.ControlError as e:
    print(f"Control command failed: {e}")

🔔 Subscriptions

You can subscribe a callback URL to HYXI push notifications for real-time data, alarms, and FCAS/frequency-modulation real-time data.

async def subscription_example(client):
    callback_url = "https://your-public-callback-host/hyxi/callback"
    device_sns = ["60700000000001", "60700000000002"]

    real_time = await client.subscribe_real_time_data(
        callback_url,
        device_sns,
        post_rate=60000,  # milliseconds, 5000-3600000
    )

    alarm = await client.subscribe_alarm(
        callback_url,
        device_sns,
        post_rate=60000,  # milliseconds, 5000-3600000
    )

    fcas = await client.subscribe_fm_real_time_data(
        callback_url,
        device_sns,
        post_rate=1,  # hours, 1-6
    )

    await client.cancel_subscription(real_time["data"]["subscribeCode"])

Subscription failures raise HyxiApiClient.SubscriptionError.

🛠️ Requirements

  • Python 3.14 (not yet 3.15 — the upper bound lifts once 3.15 is covered by CI)
  • aiohttp >= 3.13.5

🔐 Privacy & Debug Logging

When debug logging is enabled, this library automatically masks sensitive identifiers before writing them to the log — no manual redaction needed.

Field Behaviour
Serial numbers (deviceSn, parentSn, batSn) Hashed securely using SHA-256 (first 8 chars shown) to enable deterministic cross-device tracing without exposing the original identifier, e.g. e3b0c442
Plant IDs (plantId) Same SHA-256 hashing format
Home/site address (plantAddress) Fully redacted → [REDACTED]
IMEI (gprsImei) Same SHA-256 hashing format

Masking is deterministic, so parent/child device relationships remain traceable across log lines.

⚠️ Disclaimer

This is an unofficial, community-driven project. It is not affiliated with, endorsed by, or connected to HYXiPower in any official capacity. Use this software at your own risk.

Support

If this library is useful to you and you'd like to support its development:

Buy Me a Coffee

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Veldkornet from gravatar.com Veldkornet

Credits

Author: Veldkornet

License

MIT License

Requires

Python <3.15, >=3.14

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hyxi_cloud_api-1.4.7.tar.gz (86.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hyxi_cloud_api-1.4.7-py3-none-any.whl (32.3 kB view details)

Uploaded Python 3

File details

Details for the file hyxi_cloud_api-1.4.7.tar.gz.

File metadata

  • Download URL: hyxi_cloud_api-1.4.7.tar.gz
  • Upload date:
  • Size: 86.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hyxi_cloud_api-1.4.7.tar.gz
Algorithm Hash digest
SHA256 e25f04e7cdecb1d34d8624bce31b1ab0721352e78188c47328a35fec29c647ad
MD5 e5fb476030c12ef9ecc61afb5bf80ba8
BLAKE2b-256 1a31eae0ca071b5c45a19e5796bdcc282212a42b7f63bb2623416c35abd3e72a

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyxi_cloud_api-1.4.7.tar.gz:

Publisher: ci-cd.yml on Veldkornet/hyxi-cloud-api

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hyxi_cloud_api-1.4.7-py3-none-any.whl.

File metadata

  • Download URL: hyxi_cloud_api-1.4.7-py3-none-any.whl
  • Upload date:
  • Size: 32.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hyxi_cloud_api-1.4.7-py3-none-any.whl
Algorithm Hash digest
SHA256 a1b7f60e11027da114fbe816a6ea7129ca7ed1a0e659be89dfb068ac1db4e2b9
MD5 329aca0ebcd5190e7ae2b4e8812d1e5d
BLAKE2b-256 73adb155d5f8f624c7b71b52a5d9e7dcc759841b23bf4f1cdfe5cb9f7b5d5040

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyxi_cloud_api-1.4.7-py3-none-any.whl:

Publisher: ci-cd.yml on Veldkornet/hyxi-cloud-api

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.4.7 This release

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page