Getting Started

Everything you need to go from a freshly cloned repository to live inverter telemetry on your LAN.

Requirements


Python	3.10 or newer
Dependency	`pycryptodome` `>= 3.19`
Network	The dongle and your machine on the same LAN (it is not exposed to the internet)
Optional	`uv` for environment management

The dongle serves plain TCP on port 7078. It is reached by IP or hostname on your local network; there is no cloud call anywhere in this project.

Install

From the repository root:

uv venv && uv sync

This creates a virtual environment and installs the package in editable mode along with the sitsolar-dongle console script.

To install the test dependencies as well:

uv sync --extra dev

From the repository root:

python -m venv .venv
source .venv/bin/activate
pip install -e .

On Windows, activate with .venv\Scripts\activate instead.

To install the test dependencies as well:

pip install -e ".[dev]"

Verify the install:

sitsolar-dongle --version

Find your dongle

The dongle obtains an address over DHCP. Locate it on your network with your router's client list, an IP scan, or an mDNS/hostname lookup. It listens strictly on TCP port 7078, which is a reliable way to single it out:

# example: probe a subnet for anything answering on 7078
nmap -p 7078 192.168.1.0/24

Find the dongle serial number

--sn takes the serial printed on the dongle itself — a label on the casing — not the inverter's serial. This distinction matters: the dongle is what terminates the TCP session, and both session keys are derived from its serial.

The serial number is a credential

The key derivation is:

aes_key  = MD5(sn || crc16_be(sn))
hmac_key = MD5(reverse(sn) || crc16_be(reverse(sn)))

Both keys come from the serial alone. Anyone on your network who knows it can open an authenticated session with your dongle, so treat it exactly like a password: do not commit it, do not paste it into GitHub issues, and redact it from logs and packet captures before sharing.

The project's own test suite and examples use the placeholder <DONGLE_SERIAL>.

If the serial is wrong, every frame fails authentication and the tool fails fast with:

HMAC mismatch (wrong serial number?)

Run your first poll

sitsolar-dongle 192.168.1.50 --sn <DONGLE_SERIAL>

A single-shot run prints a section-grouped table of decoded values:

dongle   SiNeng Si-Dongle-L  sn=…  time=…

device_info
  device_type             30000       51  (single phase high voltage)
  rated_power           30081~30082   3000  W
…

AC_side
  grid_frequency        31002~31003   50.010  Hz
  phase_r_voltage            31000      230.1  V

Each line shows the register key, its address span, the decoded value, and the unit. Registers the firmware did not return are listed as unavailable rather than aborting the whole poll — see Caveats.

Common invocations

# Machine-readable JSON, one object
sitsolar-dongle 192.168.1.50 --sn ... --json

# Follow forever, one sample every 15 s — ideal for Home Assistant / MQTT
sitsolar-dongle 192.168.1.50 --sn ... --interval 15 --json

# Only the AC measurements, with raw register words alongside decoded values
sitsolar-dongle 192.168.1.50 --sn ... --section "AC_side" --raw

# A few specific values by key
sitsolar-dongle 192.168.1.50 --sn ... --key grid_frequency --key battery_soc

# Raw reads, bypassing the register map entirely
sitsolar-dongle 192.168.1.50 --sn ... --read 31002:2 --read 30100:1

# Print the built-in register map and exit
sitsolar-dongle --list

See the CLI Reference for the complete option list.

Continuous sampling

Passing --interval turns the tool into a long-running poller. Each cycle prints one sample, then sleeps. Combine it with --json to emit newline-free JSON objects that a supervisor, MQTT bridge, or mosquitto_pub wrapper can consume:

sitsolar-dongle 192.168.1.50 --sn ... --interval 15 --json

One connection at a time

The dongle stops accepting new TCP connections for roughly 75 seconds after a rapid reconnect. A long-running --interval session is the friendly pattern; repeatedly starting and stopping the tool is not. See Connection limits.

Next steps

CLI Reference — every option, exit code, and output mode.
Python API — embed polling in your own application.
Register Map — what each key means.
Caveats & Troubleshooting — when something does not add up.