growatt-protocol 0.1.0__py3-none-any.whl

growatt_protocol/__init__.py

@@ -0,0 +1,124 @@
+"""The Growatt datalogger upload protocol, and what its registers mean.
+
+A standalone, dependency-free implementation of the protocol a Growatt datalogger speaks
+to its server over TCP 5279: framing, obfuscation, checksums, record decoding, and the
+commands for reading and writing inverter registers. Nothing here imports Home Assistant
+or anything outside the standard library, and a test enforces both.
+
+Records are self-describing -- each one states the Modbus register ranges it carries --
+so decoding reads register numbers off the wire rather than indexing a per-model table of
+byte offsets::
+
+    from growatt_protocol import Frame, Framer, parse_register_record
+    from growatt_protocol.registers import decode_registers, resolve_profile
+
+    framer = Framer()
+    for raw in framer.feed(data):
+        payload = parse_register_record(Frame(raw))
+        match = resolve_profile([(g.start, g.end) for g in payload.groups])
+        values = decode_registers(match.profile, payload.registers).values
+
+For a whole server, :class:`GrowattServer` accepts connections and hands decoded records
+to a callback. :mod:`growatt_protocol.testing` provides a fake datalogger to drive it
+without hardware.
+"""
+
+from __future__ import annotations
+
+from . import registers, testing
+from .commands import (
+    REGISTER_TIME,
+    Command,
+    CommandResponse,
+    parse_command_response,
+    read_datalogger,
+    read_inverter,
+    set_time,
+    write_datalogger,
+    write_inverter,
+    write_inverter_range,
+)
+from .crc import append_crc, check_crc, modbus_crc
+from .crypt import (
+    KEY,
+    OBFUSCATED_PROTOCOLS,
+    SUPPORTED_PROTOCOLS,
+    deobfuscate,
+    obfuscate,
+    xor_payload,
+)
+from .errors import (
+    CommandTimeout,
+    FrameError,
+    GrowattProtocolError,
+    RecordError,
+)
+from .framing import DEFAULT_MAX_FRAME, Framer, frame_length
+from .records import (
+    COMMAND_RESPONSE_FUNCTIONS,
+    METER_FUNCTIONS,
+    REGISTER_RECORD_FUNCTIONS,
+    Frame,
+    Function,
+    RecordPayload,
+    RegisterGroup,
+    build_ack,
+    build_ping_echo,
+    parse_register_record,
+)
+from .relay import RelayConfig, RelayConnection
+from .server import DEFAULT_PORT, GrowattServer, ServerConfig, ServerStats
+from .session import Record, Session, SessionStats
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "COMMAND_RESPONSE_FUNCTIONS",
+    "DEFAULT_MAX_FRAME",
+    "DEFAULT_PORT",
+    "KEY",
+    "METER_FUNCTIONS",
+    "OBFUSCATED_PROTOCOLS",
+    "REGISTER_RECORD_FUNCTIONS",
+    "REGISTER_TIME",
+    "SUPPORTED_PROTOCOLS",
+    "Command",
+    "CommandResponse",
+    "CommandTimeout",
+    "Frame",
+    "FrameError",
+    "Framer",
+    "Function",
+    "GrowattProtocolError",
+    "GrowattServer",
+    "Record",
+    "RecordError",
+    "RecordPayload",
+    "RegisterGroup",
+    "RelayConfig",
+    "RelayConnection",
+    "ServerConfig",
+    "ServerStats",
+    "Session",
+    "SessionStats",
+    "__version__",
+    "append_crc",
+    "build_ack",
+    "build_ping_echo",
+    "check_crc",
+    "deobfuscate",
+    "frame_length",
+    "modbus_crc",
+    "obfuscate",
+    "parse_command_response",
+    "parse_register_record",
+    "read_datalogger",
+    "read_inverter",
+    "registers",
+    "set_time",
+    "testing",
+    "write_datalogger",
+    "write_inverter",
+    "write_inverter_range",
+    "xor_payload",
+]

growatt_protocol/commands.py

@@ -0,0 +1,262 @@
+"""Commands the server sends to a datalogger, and the replies it gets back.
+
+Four kinds, distinguished by function code:
+
+===========  =============================================  ================
+Function     Meaning                                        Reply
+===========  =============================================  ================
+``0x19``     read a datalogger parameter                    ``0x19``
+``0x18``     write a datalogger parameter (incl. the clock) ``0x18``
+``0x05``     read an inverter holding register              ``0x05``
+``0x06``     write one inverter holding register            ``0x06``
+``0x10``     write a range of inverter holding registers    ``0x10``
+===========  =============================================  ================
+
+The body always begins with the datalogger serial, padded to the same width the device
+uses in its own records: 30 bytes on protocol 06, 10 bytes on 02 and 05. Everything after
+that shifts accordingly, which is why the response parsers take an offset.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import IntEnum
+
+from .crc import append_crc
+from .crypt import OBFUSCATED_PROTOCOLS, obfuscate
+from .errors import RecordError
+from .records import Frame, Function
+
+#: Datalogger parameter holding the wall clock, as an ASCII timestamp.
+REGISTER_TIME = 0x1F
+
+#: Other datalogger parameters, as reported by the device in 0x19 replies.
+REGISTER_UPDATE_INTERVAL = 0x04
+REGISTER_SERIAL = 0x08
+REGISTER_SERVER_IP = 0x11
+REGISTER_SERVER_PORT = 0x12
+REGISTER_TIMEZONE = 0x1E
+
+_SERIAL_WIDTH = {2: 10, 5: 10, 6: 30}
+
+
+class Target(IntEnum):
+    """What a command addresses."""
+
+    DATALOGGER = 0
+    INVERTER = 1
+
+
+def _serial_field(serial: str, protocol: int) -> bytes:
+    width = _SERIAL_WIDTH.get(protocol)
+    if width is None:
+        raise RecordError(f"no serial width known for protocol {protocol}")
+    encoded = serial.encode("ascii")
+    if len(encoded) > width:
+        raise RecordError(f"serial {serial!r} does not fit in {width} bytes")
+    return encoded.ljust(width, b"\x00")
+
+
+def _frame(sequence: int, protocol: int, device_id: int, function: int, body: bytes) -> bytes:
+    declared = 2 + len(body)
+    frame = (
+        (sequence & 0xFFFF).to_bytes(2, "big")
+        + b"\x00"
+        + bytes([protocol])
+        + declared.to_bytes(2, "big")
+        + bytes([device_id, function])
+        + body
+    )
+    if protocol in OBFUSCATED_PROTOCOLS:
+        return append_crc(obfuscate(frame, protocol))
+    return frame
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """A command ready to be given a sequence number and sent."""
+
+    function: int
+    register: int
+    body: bytes
+    device_id: int = 0x01
+
+    @property
+    def response_function(self) -> int:
+        """The function code the device answers with. Always the request's own."""
+        return self.function
+
+    def build(self, sequence: int, protocol: int) -> bytes:
+        return _frame(sequence, protocol, self.device_id, self.function, self.body)
+
+
+# ----------------------------------------------------------------------------------
+# Builders
+# ----------------------------------------------------------------------------------
+
+
+def read_datalogger(serial: str, protocol: int, register: int) -> Command:
+    """Read one datalogger parameter (0x19)."""
+    body = _serial_field(serial, protocol)
+    body += register.to_bytes(2, "big") + register.to_bytes(2, "big")
+    return Command(Function.CONFIG_READ, register, body)
+
+
+def write_datalogger(serial: str, protocol: int, register: int, value: str) -> Command:
+    """Write one datalogger parameter (0x18).
+
+    Datalogger parameters are strings, length-prefixed -- unlike inverter registers,
+    which are bare 16-bit words.
+    """
+    encoded = value.encode("utf-8")
+    body = _serial_field(serial, protocol)
+    body += register.to_bytes(2, "big")
+    body += len(encoded).to_bytes(2, "big") + encoded
+    return Command(Function.CONFIG_WRITE, register, body)
+
+
+def set_time(serial: str, protocol: int, when: datetime) -> Command:
+    """Set the datalogger clock (0x18, register 0x1f).
+
+    The device wants ``YYYY-MM-DD HH:MM:SS`` as ASCII -- 19 bytes. Sent in local time,
+    since that is what the timestamps in its own records are expressed in.
+    """
+    text = when.replace(microsecond=0).strftime("%Y-%m-%d %H:%M:%S")
+    return write_datalogger(serial, protocol, REGISTER_TIME, text)
+
+
+def read_inverter(serial: str, protocol: int, start: int, end: int | None = None) -> Command:
+    """Read one inverter holding register, or a contiguous range (0x05)."""
+    end = start if end is None else end
+    if end < start:
+        raise ValueError(f"inverted register range {start}..{end}")
+    body = _serial_field(serial, protocol)
+    body += start.to_bytes(2, "big") + end.to_bytes(2, "big")
+    return Command(Function.INVERTER_READ, start, body)
+
+
+def write_inverter(serial: str, protocol: int, register: int, value: int) -> Command:
+    """Write one inverter holding register (0x06).
+
+    Note the asymmetry with :func:`write_datalogger`: there is no length field here, the
+    value is simply a 16-bit word.
+    """
+    if not 0 <= value <= 0xFFFF:
+        raise ValueError(f"{value} does not fit in a 16-bit register")
+    body = _serial_field(serial, protocol)
+    body += register.to_bytes(2, "big") + value.to_bytes(2, "big")
+    return Command(Function.INVERTER_WRITE, register, body)
+
+
+def write_inverter_range(serial: str, protocol: int, start: int, values: list[int]) -> Command:
+    """Write a contiguous run of inverter holding registers (0x10)."""
+    if not values:
+        raise ValueError("no values to write")
+    end = start + len(values) - 1
+    body = _serial_field(serial, protocol)
+    body += start.to_bytes(2, "big") + end.to_bytes(2, "big")
+    for value in values:
+        if not 0 <= value <= 0xFFFF:
+            raise ValueError(f"{value} does not fit in a 16-bit register")
+        body += value.to_bytes(2, "big")
+    return Command(Function.INVERTER_WRITE_MULTI, start, body)
+
+
+# ----------------------------------------------------------------------------------
+# Responses
+# ----------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResponse:
+    """A device's reply to a command."""
+
+    function: int
+    register: int | None
+    value: int | str | None = None
+    result: int | None = None
+    """The device's status byte for a write. Zero means accepted."""
+
+    empty: bool = False
+    """A read that returned nothing, which is how a device reports an unknown register."""
+
+    end_register: int | None = None
+    """The last register of the range, echoed back by a read."""
+
+    values: tuple[int, ...] = ()
+    """Every word a range read returned. :attr:`value` is the first of them."""
+
+    @property
+    def ok(self) -> bool:
+        return self.result in (None, 0)
+
+
+def parse_command_response(frame: Frame) -> CommandResponse:
+    """Interpret a 0x05, 0x06, 0x10, 0x18 or 0x19 reply.
+
+    Offsets are relative to the end of the serial field, which is 20 bytes wider on
+    protocol 06.
+    """
+    function = frame.function
+    body = frame.body
+    width = frame.serial_width
+
+    if len(body) < width + 2:
+        raise RecordError(f"{function:#04x} response is too short to hold a register")
+
+    register = int.from_bytes(body[width : width + 2], "big")
+    rest = body[width + 2 :]
+
+    if function == Function.INVERTER_READ:
+        # The reply echoes the range it was asked for -- start *and* end -- before any
+        # values, mirroring the request. Reading the word straight after the start
+        # register therefore yields the end register rather than the value, which on a
+        # single-register read looks convincingly like a plausible number: asking for
+        # register 3 comes back as 3. Confirmed against real hardware.
+        #
+        # A device that does not implement the range answers with the echo and nothing
+        # after it, rather than with an error.
+        if len(rest) < 4:
+            return CommandResponse(function, register, empty=True)
+
+        end = int.from_bytes(rest[:2], "big")
+        payload = rest[2:]
+        values = tuple(
+            int.from_bytes(payload[i : i + 2], "big")
+            for i in range(0, len(payload) - len(payload) % 2, 2)
+        )
+        if not values:
+            return CommandResponse(function, register, end_register=end, empty=True)
+        return CommandResponse(function, register, value=values[0], end_register=end, values=values)
+
+    if function == Function.INVERTER_WRITE:
+        # Both fields are present and both matter: an implementation that overwrites one
+        # with the other loses the device's acceptance status.
+        if not rest:
+            raise RecordError("0x06 response carries no result byte")
+        result = rest[0]
+        value = int.from_bytes(rest[1:3], "big") if len(rest) >= 3 else None
+        return CommandResponse(function, register, value=value, result=result)
+
+    if function == Function.INVERTER_WRITE_MULTI:
+        # The register field here is the start of the range; the end follows.
+        if len(rest) < 3:
+            raise RecordError("0x10 response is truncated")
+        return CommandResponse(function, register, result=rest[2])
+
+    if function == Function.CONFIG_WRITE:
+        if not rest:
+            raise RecordError("0x18 response carries no result byte")
+        return CommandResponse(function, register, result=rest[0])
+
+    if function == Function.CONFIG_READ:
+        if len(rest) < 2:
+            return CommandResponse(function, register, empty=True)
+        length = int.from_bytes(rest[:2], "big")
+        text = rest[2 : 2 + length]
+        # ISO-8859-1 rather than UTF-8: these fields carry SSIDs and hostnames, and a
+        # stray high byte should not make the whole reply undecodable.
+        return CommandResponse(function, register, value=text.decode("ISO-8859-1").rstrip("\x00"))
+
+    raise RecordError(f"{function:#04x} is not a command response")

growatt_protocol/crc.py

@@ -0,0 +1,55 @@
+"""CRC-16/MODBUS.
+
+Growatt frames using protocol version 05 or 06 carry a two-byte checksum after the
+declared payload. The algorithm is the standard Modbus CRC-16 (reflected polynomial
+0xA001, initial value 0xFFFF, no final XOR), but note that Growatt transmits it
+**big-endian**, which is the opposite of Modbus RTU on a serial line.
+
+This is a pure-Python replacement for the ``libscrc`` C extension, which is the only
+compiled dependency other Growatt tooling needs. A 256-entry table is built once at
+import; frames are under a kilobyte and arrive every few minutes, so this is far
+faster than it needs to be.
+"""
+
+from __future__ import annotations
+
+_POLY = 0xA001
+
+
+def _build_table() -> tuple[int, ...]:
+    table = []
+    for byte in range(256):
+        crc = byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ _POLY if crc & 1 else crc >> 1
+        table.append(crc)
+    return tuple(table)
+
+
+_TABLE = _build_table()
+
+
+def modbus_crc(data: bytes) -> int:
+    """Return the CRC-16/MODBUS of ``data`` as an unsigned 16-bit integer."""
+    crc = 0xFFFF
+    for byte in data:
+        crc = (crc >> 8) ^ _TABLE[(crc ^ byte) & 0xFF]
+    return crc
+
+
+def append_crc(frame: bytes) -> bytes:
+    """Return ``frame`` with its CRC appended big-endian, as Growatt transmits it."""
+    return frame + modbus_crc(frame).to_bytes(2, "big")
+
+
+def check_crc(frame: bytes) -> bool:
+    """Whether ``frame``'s trailing two bytes match a CRC over everything before them.
+
+    Callers should treat a mismatch as advisory. Some dataloggers have been reported to
+    fail this check on every single record while still emitting perfectly decodable
+    payloads, so refusing such records loses all data from that device. Count the
+    mismatch, log it, and decode anyway; frame length is the real validity gate.
+    """
+    if len(frame) < 3:
+        return False
+    return modbus_crc(frame[:-2]) == int.from_bytes(frame[-2:], "big")

growatt_protocol/crypt.py

@@ -0,0 +1,58 @@
+"""The XOR obfuscation used by Growatt protocol versions 05 and 06.
+
+The payload is XORed with the repeating ASCII key ``Growatt``. Two details matter and
+are easy to get wrong:
+
+* The eight-byte header is **not** obfuscated. It is transmitted in clear so that a
+  receiver can read the protocol version and length before it knows whether to
+  deobfuscate anything.
+* The keystream index restarts at zero at byte offset 8, so the byte at offset 8 is
+  XORed with ``'G'``, not with ``KEY[8 % 7]``.
+
+Protocol version 02 is not obfuscated at all. Do not apply this unconditionally.
+
+The transform is its own inverse, so the same function encrypts outbound frames.
+"""
+
+from __future__ import annotations
+
+KEY = b"Growatt"
+
+HEADER_LENGTH = 8
+
+#: Protocol versions whose payload is XOR-obfuscated and which carry a trailing CRC.
+OBFUSCATED_PROTOCOLS = frozenset({5, 6})
+
+#: Every protocol version this implementation understands.
+SUPPORTED_PROTOCOLS = frozenset({2, 5, 6})
+
+
+def xor_payload(frame: bytes) -> bytes:
+    """Return ``frame`` with its payload XORed against the repeating key.
+
+    The first :data:`HEADER_LENGTH` bytes are copied unchanged. Applying this twice
+    returns the original frame.
+    """
+    if len(frame) <= HEADER_LENGTH:
+        return bytes(frame)
+
+    header = bytes(frame[:HEADER_LENGTH])
+    body = memoryview(frame)[HEADER_LENGTH:]
+    key_len = len(KEY)
+    # Build a keystream that is at least as long as the body, then truncate. This is
+    # meaningfully faster than a per-byte modulo for the sizes involved.
+    repeats = -(-len(body) // key_len)
+    keystream = (KEY * repeats)[: len(body)]
+    return header + bytes(a ^ b for a, b in zip(body, keystream, strict=True))
+
+
+def deobfuscate(frame: bytes, protocol: int) -> bytes:
+    """Return the plaintext of ``frame`` for the given protocol version."""
+    if protocol in OBFUSCATED_PROTOCOLS:
+        return xor_payload(frame)
+    return bytes(frame)
+
+
+def obfuscate(frame: bytes, protocol: int) -> bytes:
+    """Inverse of :func:`deobfuscate`. Identical, but named for the calling direction."""
+    return deobfuscate(frame, protocol)

growatt_protocol/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions raised by the protocol layer."""
+
+from __future__ import annotations
+
+
+class GrowattProtocolError(Exception):
+    """Base class for every protocol-layer failure."""
+
+
+class FrameError(GrowattProtocolError):
+    """A byte stream could not be split into frames.
+
+    Raised for structurally impossible framing -- an unsupported protocol version, a
+    declared length that cannot be valid, or a frame larger than the configured
+    maximum. The connection should be closed, because the stream position is no longer
+    trustworthy.
+    """
+
+
+class RecordError(GrowattProtocolError):
+    """A frame was well-framed but its payload could not be interpreted.
+
+    Unlike :class:`FrameError` this is recoverable: the frame boundary was correct, so
+    the connection can continue with the next frame.
+    """
+
+
+class CommandTimeout(GrowattProtocolError):
+    """A command was sent but no matching response arrived in time."""

growatt_protocol/framing.py

@@ -0,0 +1,109 @@
+"""Incremental reassembly of Growatt frames from a TCP byte stream.
+
+TCP is a stream, not a message queue. A datalogger's records arrive split across several
+segments, or several records arrive coalesced into one. Treating each ``recv()`` as
+exactly one record -- which is a common shortcut in this problem space -- corrupts data
+as soon as either happens.
+
+Feed arbitrary chunks to :meth:`Framer.feed` and it yields whole frames.
+
+Frame length is derived from the header::
+
+    total = 6 + declared_length + (2 if protocol in (5, 6) else 0)
+
+``declared_length`` counts the device-id and function-code bytes plus the payload, but
+excludes the trailing CRC that protocol 05/06 appends.
+"""
+
+from __future__ import annotations
+
+from .crypt import OBFUSCATED_PROTOCOLS, SUPPORTED_PROTOCOLS
+from .errors import FrameError
+
+#: Largest frame we will assemble. Real records are well under 1 KB; this exists so a
+#: corrupt or hostile length field cannot make us buffer without bound.
+DEFAULT_MAX_FRAME = 8192
+
+#: Bytes of header needed before the total frame length can be computed.
+_LENGTH_PREFIX = 6
+
+#: Smallest meaningful declared length: the device id and function code alone.
+_MIN_DECLARED_LENGTH = 2
+
+
+def frame_length(header: bytes) -> int:
+    """Return the total on-the-wire length of the frame beginning with ``header``.
+
+    ``header`` must be at least :data:`_LENGTH_PREFIX` bytes.
+
+    Raises:
+        FrameError: if the protocol version is unsupported or the declared length is
+            structurally impossible.
+    """
+    if len(header) < _LENGTH_PREFIX:
+        raise ValueError(f"need at least {_LENGTH_PREFIX} bytes to compute frame length")
+
+    protocol = header[3]
+    if protocol not in SUPPORTED_PROTOCOLS:
+        raise FrameError(f"unsupported Growatt protocol version 0x{protocol:02x}")
+
+    declared = int.from_bytes(header[4:6], "big")
+    if declared < _MIN_DECLARED_LENGTH:
+        raise FrameError(f"declared frame length {declared} is below the minimum")
+
+    crc_length = 2 if protocol in OBFUSCATED_PROTOCOLS else 0
+    return _LENGTH_PREFIX + declared + crc_length
+
+
+class Framer:
+    """Stateful reassembler. One instance per connection, per direction."""
+
+    def __init__(self, max_frame: int = DEFAULT_MAX_FRAME) -> None:
+        if max_frame < _LENGTH_PREFIX + _MIN_DECLARED_LENGTH:
+            raise ValueError("max_frame is too small to hold any valid frame")
+        self.max_frame = max_frame
+        self._buffer = bytearray()
+
+    @property
+    def pending(self) -> bytes:
+        """Bytes buffered so far that do not yet form a complete frame."""
+        return bytes(self._buffer)
+
+    def reset(self) -> None:
+        """Discard buffered bytes. Use after an error, before reusing the instance."""
+        self._buffer.clear()
+
+    def feed(self, chunk: bytes) -> list[bytes]:
+        """Add ``chunk`` to the buffer and return every frame it completes.
+
+        Frames are returned in arrival order. Any trailing partial frame stays buffered
+        for the next call.
+
+        This is deliberately eager rather than a generator: the buffer must be updated
+        even when the caller does not consume the result, and an error must surface at
+        the call site rather than at some later iteration.
+
+        Raises:
+            FrameError: on an unsupported protocol version, an impossible declared
+                length, or a frame exceeding ``max_frame``. The connection should be
+                closed: once the length field is untrustworthy, so is the stream
+                position. Frames completed before the bad one are lost with the
+                exception, which is the right trade -- a stream we can no longer
+                position ourselves in has no salvageable remainder.
+        """
+        self._buffer.extend(chunk)
+        frames: list[bytes] = []
+
+        while len(self._buffer) >= _LENGTH_PREFIX:
+            total = frame_length(self._buffer)
+
+            if total > self.max_frame:
+                raise FrameError(f"frame length {total} exceeds maximum {self.max_frame}")
+
+            if len(self._buffer) < total:
+                break
+
+            frames.append(bytes(self._buffer[:total]))
+            del self._buffer[:total]
+
+        return frames