TSUN Local API

tsun-local-api is an asynchronous, read-only Python library for communicating with supported TSUN micro-inverters over the local network. It does not require a proxy or cloud service.

This independent project is the communication dependency prepared for the official Home Assistant integration. It is not affiliated with, approved by, or maintained by TSUN.

Features

  • local TCP telemetry with automatic protocol detection;
  • native read-only UDP discovery and bounded private-network analysis;
  • automatic logger SN discovery, with manual entry supported by applications;
  • local extraction of the logger firmware, MAC address and micro-inverter SN;
  • AC and per-input PV measurements, energy counters and raw alarm words;
  • privacy-safe diagnostic traces that exclude host addresses and serial numbers;
  • no write, control or cloud operation.

Hardware validation

Family Model PV inputs Status
TITAN TSOL-MP3000 6 Validated on physical hardware
GEN3 PLUS TSOL-MX500 1 Validated on physical hardware

Other models using the supported local protocol families may work, but must be validated on physical hardware before compatibility is claimed.

Installation

python -m pip install tsun-local-api

Python 3.13 or later is required.

Basic use

from aiohttp import ClientSession
from tsun_local_api import TsunClient, async_read_logger_metadata


async def read_micro_inverter(host: str) -> None:
    async with ClientSession() as session:
        metadata = await async_read_logger_metadata(session, host)

    if metadata.logger_sn is None:
        raise RuntimeError("The numeric logger SN must be entered manually")

    client = TsunClient(host, metadata.logger_sn, metadata=metadata)
    telemetry = await client.async_read()
    print(telemetry.device)
    print(telemetry.values)

Applications remain responsible for validating user-supplied hosts and for deciding which private networks may be analysed. Network analysis in this library is deliberately limited to private /24 networks or smaller.

Development

uv sync --group test
uv run ruff check .
uv run pytest --cov=tsun_local_api

License

Copyright 2026 Jean-Philippe TESTART (jptstar).

Distributed under the Apache License 2.0. See LICENSE and NOTICE.

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

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 jptstar from gravatar.com jptstar

Credits

Author: Jean-Philippe TESTART

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.13

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

tsun_local_api-0.2.0.tar.gz (17.7 kB view details)

Uploaded Source

Built Distribution

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

tsun_local_api-0.2.0-py3-none-any.whl (19.6 kB view details)

Uploaded Python 3

File details

Details for the file tsun_local_api-0.2.0.tar.gz.

File metadata

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

File hashes

Hashes for tsun_local_api-0.2.0.tar.gz
Algorithm Hash digest
SHA256 542abb335bac189383fae51c0b5e51c352ec297e5d7f75b22fad11b49c746b59
MD5 155ff58de5bd8f253475018f5dc94afe
BLAKE2b-256 3823b7cd9b9cf7dbaa5ea62a831191604b922dba396230371df4b8a5b2e7b0b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for tsun_local_api-0.2.0.tar.gz:

Publisher: release.yml on jptstar/tsun-local-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 tsun_local_api-0.2.0-py3-none-any.whl.

File metadata

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

File hashes

Hashes for tsun_local_api-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 91f4964bf7d7ade4e6fc6542c11bcd3f63330772fffd30fe975af356f0c88334
MD5 b3b3772d59ea769ad4bc4117f9145240
BLAKE2b-256 c64f2ae8c9ed0508a33c93049e3da116fe1928ccf55c5852d481cce14d2c228a

See more details on using hashes here.

Provenance

The following attestation bundles were made for tsun_local_api-0.2.0-py3-none-any.whl:

Publisher: release.yml on jptstar/tsun-local-api

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

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page