tecnoctl 0.1.0__py3-none-any.whl

tecnoctl/__init__.py

@@ -0,0 +1,5 @@
+"""Public API for tecnoctl."""
+
+from .client import AlarmClient, ProtocolError
+
+__all__ = ["AlarmClient", "ProtocolError"]

tecnoctl/cli.py

@@ -0,0 +1,278 @@
+"""Command-line interface for :class:`tecnoctl.AlarmClient`."""
+
+import argparse
+import getpass
+import json
+import logging
+import math
+import os
+import sys
+import time
+
+from dotenv import load_dotenv
+
+from .client import AlarmClient, ProtocolError
+
+
+def _one_based(value):
+    try:
+        number = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if not 1 <= number <= 65536:
+        raise argparse.ArgumentTypeError("must be between 1 and 65536")
+    return number - 1
+
+
+def _app_id(value):
+    try:
+        number = int(value, 0)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "must be a decimal or 0x-prefixed integer"
+        ) from exc
+    if not 0 <= number <= 0xFFFF:
+        raise argparse.ArgumentTypeError("must fit in 16 bits")
+    return number
+
+
+def _positive(value):
+    try:
+        number = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
+
+
+def _nonnegative(value):
+    try:
+        number = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if number < 0:
+        raise argparse.ArgumentTypeError("cannot be negative")
+    return number
+
+
+def _watch_interval(value):
+    try:
+        number = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be a number") from exc
+    if not 5 <= number < float("inf"):
+        raise argparse.ArgumentTypeError("must be at least 5 seconds")
+    return number
+
+
+def _clear_status_line():
+    if sys.stderr.isatty():
+        print("\r\033[2K", end="", file=sys.stderr, flush=True)
+
+
+def _countdown(seconds):
+    if not sys.stderr.isatty():
+        time.sleep(seconds)
+        return
+    deadline = time.monotonic() + seconds
+    while (remaining := deadline - time.monotonic()) > 0:
+        print(
+            f"\r\033[2Knext request in {math.ceil(remaining)} s",
+            end="",
+            file=sys.stderr,
+            flush=True,
+        )
+        time.sleep(min(1, remaining))
+    _clear_status_line()
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        description="Control a Tecnoalarm panel over direct TCP"
+    )
+    parser.add_argument("host", help="panel hostname or IP address")
+    parser.add_argument("--port", type=int, default=10001)
+    parser.add_argument("--timeout", type=float, default=10.0)
+    parser.add_argument(
+        "--debug", action="store_true", help="log connection and protocol diagnostics"
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="log connection status"
+    )
+    parser.add_argument(
+        "--app-id",
+        type=_app_id,
+        help="16-bit client ID (default: stable value derived from this machine)",
+    )
+    parser.add_argument(
+        "--passphrase", help="network passphrase (prefer TECNOCTL_PASSPHRASE)"
+    )
+    parser.add_argument(
+        "--code", help="4-6 digit user code (prefer TECNOCTL_CODE)"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("info", help="panel model, limits, session, and raw information")
+    commands.add_parser("clock", help="raw panel clock record")
+    commands.add_parser("status", help="complete panel/program/remote status")
+    commands.add_parser("panel-status", help="decoded central-unit status and all flags")
+    commands.add_parser("group-status", help="program and remote status without names")
+    commands.add_parser("permissions", help="program and remote permissions for this code")
+    commands.add_parser("programs", help="program IDs, names, permissions, and states")
+    commands.add_parser("remotes", help="remote-control IDs, names, permissions, and states")
+    zones = commands.add_parser("zones", help="zone IDs, names, and states")
+    zones.add_argument("--start", type=_one_based, default=0, metavar="ZONE")
+    zones.add_argument("--count", type=_positive)
+    zones.add_argument("--filter", choices=("all", "open", "isolated"), default="all")
+    code_names = commands.add_parser("code-names", help="code labels only; never PIN digits")
+    code_names.add_argument("--start", type=_one_based, default=0, metavar="CODE")
+    code_names.add_argument("--count", type=_positive)
+    events = commands.add_parser("events", help="event log; use --limit 0 for all")
+    events.add_argument("--limit", type=_nonnegative, default=50)
+    watch = commands.add_parser(
+        "watch", help="print alarm and program-state events as JSON lines"
+    )
+    watch.add_argument("--interval", type=_watch_interval, default=30.0)
+    watch.add_argument(
+        "--debug",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="log connection, protocol, and poll diagnostics",
+    )
+    watch.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="log connection status and meaningful poll activity",
+    )
+    commands.add_parser("sync", help="full configuration and status synchronization")
+    open_zones = commands.add_parser("open-zones", help="open zones blocking a program")
+    open_zones.add_argument("program", type=_one_based)
+    arm = commands.add_parser("arm", help="arm a program")
+    arm.add_argument("program", type=_one_based)
+    arm.add_argument("--exclude-open", action="store_true")
+    disarm = commands.add_parser("disarm", help="disarm a program")
+    disarm.add_argument("program", type=_one_based)
+    remote_on = commands.add_parser("remote-on", help="turn a remote control on")
+    remote_on.add_argument("remote", type=_one_based)
+    remote_off = commands.add_parser("remote-off", help="turn a remote control off")
+    remote_off.add_argument("remote", type=_one_based)
+    zone_status = commands.add_parser("zone-status", help="read one zone")
+    zone_status.add_argument("zone", type=_one_based)
+    isolate = commands.add_parser("isolate", help="isolate a zone (master code required)")
+    isolate.add_argument("zone", type=_one_based)
+    reintegrate = commands.add_parser(
+        "reintegrate", help="reintegrate a zone (master code required)"
+    )
+    reintegrate.add_argument("zone", type=_one_based)
+    return parser
+
+
+def main():
+    load_dotenv(".env")
+    parser = _parser()
+    args = parser.parse_args()
+    log_level = logging.DEBUG if args.debug else logging.INFO if args.verbose else None
+    if log_level is not None:
+        logging.basicConfig(
+            level=log_level,
+            format="%(asctime)s %(levelname)s %(message)s",
+            datefmt="%H:%M:%S",
+        )
+    passphrase = args.passphrase or os.getenv("TECNOCTL_PASSPHRASE")
+    code = args.code or os.getenv("TECNOCTL_CODE")
+    if passphrase is None:
+        passphrase = getpass.getpass("Network passphrase: ")
+    if code is None:
+        code = getpass.getpass("Access code: ")
+
+    try:
+        client = AlarmClient(
+            args.host,
+            passphrase,
+            code,
+            port=args.port,
+            app_id=args.app_id,
+            timeout=args.timeout,
+        )
+        if args.command == "watch":
+            print(
+                f"watching {args.host}:{args.port} every {args.interval:g} seconds; "
+                "Ctrl-C to stop",
+                file=sys.stderr,
+            )
+            try:
+                for event in client.watch(args.interval, wait=_countdown):
+                    _clear_status_line()
+                    print(json.dumps(event), flush=True)
+            except KeyboardInterrupt:
+                pass
+            finally:
+                _clear_status_line()
+                client.close()
+            return
+
+        with client as alarm:
+            if args.command == "info":
+                result = alarm.panel_info()
+            elif args.command == "clock":
+                result = {"raw": alarm.clock.hex()}
+            elif args.command == "status":
+                result = alarm.status()
+            elif args.command == "panel-status":
+                result = alarm.panel_status()
+            elif args.command == "group-status":
+                result = alarm.group_status()
+            elif args.command == "permissions":
+                result = alarm.permissions()
+            elif args.command == "programs":
+                result = alarm.programs()
+            elif args.command == "remotes":
+                result = alarm.remotes()
+            elif args.command == "zones":
+                result = alarm.zones(args.start, args.count)
+                if args.filter != "all":
+                    result = [zone for zone in result if zone[args.filter]]
+            elif args.command == "code-names":
+                result = alarm.code_names(args.start, args.count)
+            elif args.command == "events":
+                result = alarm.events(args.limit)
+            elif args.command == "sync":
+                result = alarm.sync()
+            elif args.command == "open-zones":
+                result = {"zones": [zone + 1 for zone in alarm.open_zones(args.program)]}
+            else:
+                _run_action(alarm, args)
+                return
+            print(json.dumps(result, indent=2))
+    except (OSError, ProtocolError, ValueError) as exc:
+        parser.exit(1, f"error: {exc}\n")
+
+
+def _run_action(alarm, args):
+    if args.command == "arm":
+        excluded = alarm.arm(args.program, args.exclude_open)
+        suffix = (
+            f"; excluded zones {', '.join(str(zone + 1) for zone in excluded)}"
+            if excluded
+            else ""
+        )
+        print(f"program {args.program + 1} armed{suffix}")
+    elif args.command == "disarm":
+        alarm.disarm(args.program)
+        print(f"program {args.program + 1} disarmed")
+    elif args.command in ("remote-on", "remote-off"):
+        enabled = args.command == "remote-on"
+        alarm.remote(args.remote, enabled)
+        print(f"remote {args.remote + 1} {'on' if enabled else 'off'}")
+    elif args.command == "zone-status":
+        print(json.dumps(alarm.zone_status(args.zone), indent=2))
+    else:
+        isolated = args.command == "isolate"
+        alarm.set_zone_isolation(args.zone, isolated)
+        print(f"zone {args.zone + 1} {'isolated' if isolated else 'reintegrated'}")
+
+
+if __name__ == "__main__":
+    main()

tecnoctl/client.py

@@ -0,0 +1,846 @@
+"""Reusable client for the myTecnoalarm direct encrypted-TCP protocol."""
+
+from datetime import datetime, timedelta
+import logging
+import secrets
+import socket
+import struct
+import time
+import uuid
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms
+from cryptography.hazmat.decrepit.ciphers.modes import CFB
+
+
+logger = logging.getLogger(__name__)
+
+DLE, STX, ACK, RDY, NAK, BUSY = 0x10, 0x02, 0x06, 0x0C, 0x15, 0x0F
+BRIDGE_RECORD = 2304
+EVOLUTION_MODELS = {49, 50, 57, 58}
+LONG_TEXT_MODELS = {35, 36, 38, 39, 42, 43, 44, 45, 46, 47, 48, 49, 50, 57, 58}
+MODEL_NAMES = {
+    33: "TP888", 34: "TP888E", 35: "TP440", 36: "TP440E",
+    38: "TP42", 39: "TP42E", 42: "EV424", 43: "EV424E",
+    45: "TP888P", 46: "TP888PE", 47: "TP312", 48: "TP312E",
+    49: "EV50", 50: "EV50E", 57: "EV150", 58: "EV150E",
+}
+MODEL_LIMITS = {
+    13: (32, 16, 256, 201, 2000),
+    24: (32, 32, 512, 301, 2000),
+    25: (8, 8, 96, 201, 2000),
+    29: (8, 8, 28, 121, 1500), 30: (8, 8, 28, 121, 1500),
+    31: (8, 8, 28, 121, 1500), 32: (8, 8, 28, 121, 1500),
+    33: (8, 8, 88, 201, 1500), 34: (8, 8, 88, 201, 1500),
+    35: (32, 32, 440, 301, 2000), 36: (32, 32, 440, 301, 2000),
+    38: (8, 8, 42, 121, 1500), 39: (8, 8, 42, 121, 1500),
+    40: (8, 8, 28, 121, 1500), 41: (8, 8, 28, 121, 1500),
+    42: (6, 6, 24, 49, 2000), 43: (6, 6, 24, 49, 2000),
+    44: (32, 32, 440, 301, 2000),
+    45: (16, 16, 88, 201, 1500), 46: (16, 16, 88, 201, 1500),
+    47: (32, 32, 312, 301, 2000), 48: (32, 32, 312, 301, 2000),
+    49: (8, 32, 50, 121, 2000), 50: (8, 32, 50, 121, 2000),
+    57: (16, 32, 150, 201, 2000), 58: (16, 32, 150, 201, 2000),
+}
+RECORD_NAMES = {
+    1: "clock", 2305: "authentication", 2306: "operation",
+    2307: "program description", 2308: "remote description",
+    2309: "code description", 2310: "zone description", 2311: "start event log",
+    2312: "event log", 2313: "panel information", 2314: "permissions",
+    2316: "zone status", 2317: "program/remote status", 2318: "panel status",
+    2319: "priority", 2320: "isolate zone", 2321: "reintegrate zone",
+    2339: "Evolution remote description", 2340: "Evolution program/remote status",
+}
+PROGRAM_STATE_NAMES = {
+    0: "disarmed", 1: "pre_exit", 2: "exit", 3: "armed",
+    4: "partial_exit", 5: "partial", 6: "partial_end",
+}
+GENERAL_STATUS_BITS = (
+    ("standby", "fault", "battery_alarm", "power_alarm", "tamper_active", "anomaly_active", "robbery_active", "technical_active"),
+    ("chime", "line_status", "prealarm", "program_alarm", "access_denied", "alarm", "system_ok", "cellular_status"),
+    ("tamper_alarm", "anomaly_alarm", "false_code_alarm", "false_key_alarm", "alive_alarm", "mask_alarm", "robbery_alarm", "technical_alarm"),
+    ("generic_memory", "exit_time", "maintenance", "call_active", "partial_warning", "automatic_warning", "zones_isolated", "mask_active"),
+    ("tamper_memory", "anomaly_memory", "false_code_memory", "false_key_memory", "call_memory", "battery_memory", "power_memory", "line_memory"),
+    ("cellular_memory", "voice_memory_expired", "answerer_on", "internal_siren", "external_siren", "output_1", "output_2", "local_expansion"),
+    ("panic", "failure_alarm", "failure_active", "mask_key_active", "output_3", "output_4", "isolation_inhibited", "failure_memory"),
+    ("tecno_output_internal_siren", "tecno_output_external_siren", "tecno_output_1", "tecno_output_2", "tecno_output_3", "tecno_output_4", "reserved_6", "reserved_7"),
+)
+
+
+class ProtocolError(RuntimeError):
+    pass
+
+
+def _crc16(data):
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ (0xA001 if crc & 1 else 0)
+    return crc
+
+
+def _bridge_frame(control, session, record, index=0, payload=b""):
+    body = struct.pack(
+        "<HHHHHH", BRIDGE_RECORD, session, len(payload) + 6, record, index, len(payload)
+    ) + payload
+    return bytes((DLE, control)) + body + struct.pack("<H", _crc16(body))
+
+
+def _stuff(frame):
+    return frame[:2] + frame[2:].replace(b"\x10", b"\x10\x10")
+
+
+def _take_frame(buffer):
+    """Return (unescaped frame, consumed bytes), or None for incomplete input."""
+    if len(buffer) < 2:
+        return None
+    if buffer[0] != DLE:
+        raise ProtocolError(f"invalid response prefix 0x{buffer[0]:02x}")
+
+    offset = 0
+    if buffer[1] == BUSY:
+        if len(buffer) < 4:
+            return None
+        if buffer[2] != DLE:
+            raise ProtocolError("invalid BUSY response")
+        offset = 2
+
+    control = buffer[offset + 1]
+    if control in (ACK, NAK):
+        return bytes(buffer[: offset + 2]), offset + 2
+    if control != RDY:
+        raise ProtocolError(f"unexpected control byte 0x{control:02x}")
+
+    decoded = bytearray(buffer[: offset + 2])
+    cursor = offset + 2
+    wanted = None
+    while cursor < len(buffer):
+        byte = buffer[cursor]
+        decoded.append(byte)
+        cursor += 1
+        if byte == DLE:
+            if cursor == len(buffer):
+                return None
+            if buffer[cursor] != DLE:
+                raise ProtocolError("invalid DLE escaping")
+            cursor += 1
+
+        if wanted is None and len(decoded) >= offset + 14:
+            payload_length = int.from_bytes(decoded[offset + 12 : offset + 14], "little")
+            if payload_length > 4096:
+                raise ProtocolError(f"implausible payload length {payload_length}")
+            wanted = offset + payload_length + 16
+        if wanted is not None and len(decoded) == wanted:
+            return bytes(decoded), cursor
+        if wanted is not None and len(decoded) > wanted:
+            raise ProtocolError("response exceeded declared length")
+    return None
+
+
+def _parse_response(frame, session, record, index, expected_length):
+    offset = 2 if frame[1] == BUSY else 0
+    control = frame[offset + 1]
+    if control == NAK:
+        raise ProtocolError("alarm rejected the request (NAK)")
+    if control == ACK:
+        if expected_length:
+            raise ProtocolError("alarm returned ACK without the expected data")
+        return b""
+    if control != RDY:
+        raise ProtocolError(f"unexpected response control 0x{control:02x}")
+
+    outer, response_session, inner_length, response_record, response_index, payload_length = (
+        struct.unpack_from("<HHHHHH", frame, offset + 2)
+    )
+    if outer != BRIDGE_RECORD:
+        raise ProtocolError(f"unexpected bridge record {outer}")
+    if response_session != session:
+        raise ProtocolError(f"session mismatch: expected {session}, got {response_session}")
+    if inner_length != payload_length + 6:
+        raise ProtocolError("invalid inner length")
+    if response_record != record or response_index != index:
+        raise ProtocolError(
+            f"response mismatch: record/index {response_record}/{response_index}"
+        )
+    if payload_length != expected_length:
+        raise ProtocolError(
+            f"unexpected payload length: expected {expected_length}, got {payload_length}"
+        )
+
+    body_start = offset + 2
+    payload_start = offset + 14
+    payload_end = payload_start + payload_length
+    received_crc = int.from_bytes(frame[payload_end : payload_end + 2], "little")
+    if received_crc != _crc16(frame[body_start:payload_end]):
+        raise ProtocolError("response CRC mismatch")
+    return frame[payload_start:payload_end]
+
+
+class AlarmClient:
+    """A direct TCP session with a Tecnoalarm panel.
+
+    Program, remote, and zone arguments use zero-based indexes. Returned IDs
+    are one-based for display.
+    """
+
+    def __init__(
+        self, host, passphrase, code, *, port=10001, app_id=None, timeout=10.0
+    ):
+        if app_id is None:
+            app_id = uuid.getnode() & 0xFFFF or 1
+        if not host:
+            raise ValueError("host is required")
+        if not 1 <= port <= 65535:
+            raise ValueError("port must be between 1 and 65535")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        if not code.isdigit() or not 4 <= len(code) <= 6:
+            raise ValueError("access code must contain 4 to 6 digits")
+        if not passphrase:
+            raise ValueError("passphrase is required")
+        if not 0 <= app_id <= 0xFFFF:
+            raise ValueError("app ID must fit in 16 bits")
+
+        self.host, self.port, self.timeout = host, port, timeout
+        self.key = bytes(ord(char) & 0xFF for char in passphrase[:16].ljust(16))
+        self.code, self.app_id = code, app_id
+        self.session = 0
+        self.clock = b""
+        self._info = None
+        self._permissions = None
+        self.sock = self.encryptor = self.decryptor = None
+        self.rx = bytearray()
+
+    def __enter__(self):
+        return self.connect()
+
+    def __exit__(self, *_):
+        self.close()
+
+    def connect(self):
+        logger.debug(
+            "connecting to %s:%d (timeout=%g seconds)",
+            self.host,
+            self.port,
+            self.timeout,
+        )
+        try:
+            self.session = 0
+            self.clock = b""
+            self._info = self._permissions = None
+            self.rx.clear()
+            self.sock = socket.create_connection((self.host, self.port), self.timeout)
+            self.sock.settimeout(self.timeout)
+            logger.debug("TCP connection established; starting encrypted handshake")
+            iv = secrets.token_bytes(16)
+            cipher = Cipher(algorithms.AES(self.key), CFB(iv))
+            self.encryptor, self.decryptor = cipher.encryptor(), cipher.decryptor()
+            time.sleep(0.5)  # The official app gives the panel time to enter crypto mode.
+            self.sock.sendall(iv)
+
+            try:
+                self.clock = self._exchange(1, expected_length=10)
+            except (OSError, ProtocolError) as exc:
+                raise ProtocolError(
+                    "clock handshake (record 1) failed: "
+                    f"{exc}; check the direct-TCP port and network passphrase"
+                ) from exc
+            logger.debug("clock handshake succeeded")
+            auth = bytearray(48)
+            auth[:2] = self.app_id.to_bytes(2, "little")
+            auth[2 : 2 + len(self.code)] = bytes(map(int, self.code))
+            auth[8] = 1
+            try:
+                response = self._exchange(2305, payload=auth, expected_length=3)
+            except (OSError, ProtocolError) as exc:
+                raise ProtocolError(
+                    "authentication handshake (record 2305) failed: "
+                    f"{exc}; check the access code, app ID, and user permissions"
+                ) from exc
+            if response[0] != ACK:
+                raise ProtocolError(
+                    "authentication handshake (record 2305) returned "
+                    f"{response.hex()} instead of ACK; check the access code, app ID, "
+                    "and user permissions"
+                )
+            self.session = int.from_bytes(response[1:3], "little")
+            logger.info(
+                "connected to %s:%d; authenticated session=%d",
+                self.host,
+                self.port,
+                self.session,
+            )
+            return self
+        except Exception as exc:
+            logger.info("connection failed: %s", exc)
+            self.close()
+            raise
+
+    def close(self):
+        if self.sock is not None:
+            self.sock.close()
+            self.sock = None
+            logger.debug("connection closed")
+
+    def _exchange(self, record, index=0, payload=b"", expected_length=0):
+        name = RECORD_NAMES.get(record, "unknown")
+        started = time.monotonic()
+        logger.debug(
+            "requesting %s (record=%d index=%d payload=%d bytes)",
+            name,
+            record,
+            index,
+            len(payload),
+        )
+        try:
+            frame = _bridge_frame(STX, self.session, record, index, bytes(payload))
+            self.sock.sendall(self.encryptor.update(_stuff(frame)))
+            while True:
+                complete = _take_frame(self.rx)
+                if complete is not None:
+                    response, consumed = complete
+                    del self.rx[:consumed]
+                    result = _parse_response(
+                        response, self.session, record, index, expected_length
+                    )
+                    logger.debug(
+                        "received %s (record=%d index=%d response=%d bytes) in %.3fs",
+                        name,
+                        record,
+                        index,
+                        len(result),
+                        time.monotonic() - started,
+                    )
+                    return result
+                chunk = self.sock.recv(4096)
+                if not chunk:
+                    raise ProtocolError("alarm closed the connection")
+                self.rx.extend(self.decryptor.update(chunk))
+        except (OSError, ProtocolError) as exc:
+            logger.debug(
+                "%s request failed after %.3fs: %s",
+                name,
+                time.monotonic() - started,
+                exc,
+            )
+            raise ProtocolError(
+                f"{name} request (record {record}, index {index}) failed: {exc}"
+            ) from exc
+
+    def _panel_info_raw(self):
+        if self._info is None:
+            self._info = self._exchange(2313, expected_length=16)
+        return self._info
+
+    def profile(self):
+        info = self._panel_info_raw()
+        programs, remotes, zones, codes, events = MODEL_LIMITS.get(
+            info[0], (8, 8, 28, 121, 1500)
+        )
+        return {
+            "model_id": info[0],
+            "model": MODEL_NAMES.get(info[0], f"model-{info[0]}"),
+            "firmware_nature": info[1],
+            "max_programs": programs,
+            "max_remotes": remotes,
+            "max_zones": zones,
+            "max_code_names": codes,
+            "event_capacity": events,
+        }
+
+    def panel_info(self):
+        info = self._panel_info_raw()
+        return {
+            **self.profile(),
+            "session": self.session,
+            "master_session": self.session == 1,
+            "app_id": self.app_id,
+            "raw": info.hex(),
+        }
+
+    def panel_status(self):
+        data = self._exchange(2318, expected_length=16)
+        general = data[8:16]
+        flags = {
+            name: bool(general[byte] & (1 << bit))
+            for byte, names in enumerate(GENERAL_STATUS_BITS)
+            for bit, name in enumerate(names)
+        }
+        flags.update(
+            battery=flags["battery_alarm"] or flags["battery_memory"],
+            powerless=flags["power_alarm"] or flags["power_memory"],
+            tamper=flags["tamper_active"] or flags["tamper_memory"],
+            anomaly=flags["anomaly_active"] or flags["anomaly_memory"],
+            false_code=flags["false_code_alarm"] or flags["false_code_memory"],
+            false_key=flags["false_key_alarm"] or flags["false_key_memory"],
+        )
+        return {
+            "firmware_nature": data[0],
+            "firmware_release": data[1],
+            "hardware_release": data[2],
+            "vocabulary_nature": data[3],
+            "vocabulary_release": data[4],
+            "supply_voltage_raw": data[5],
+            "battery_voltage_raw": data[6],
+            "phone_call_active": bool(data[7] & 0x01),
+            "answerer_active": bool(data[7] & 0x02),
+            "secure_connection": bool(data[7] & 0x04),
+            "general": flags,
+            "raw": data.hex(),
+        }
+
+    @staticmethod
+    def _group_layout(model):
+        if model == 13:
+            return 34, 2, 2, 32
+        if model in (24, 35, 36, 44, 47, 48):
+            return 36, 4, 4, 32
+        if model in (57, 58):
+            return 64, 4, 32, 16
+        if model in (45, 46):
+            return 20, 4, 4, 16
+        if model in (49, 50):
+            return 64, 4, 32, 8
+        if model in (42, 43):
+            return 12, 2, 4, 6
+        return 12, 4, 4, 8
+
+    def group_status(self):
+        profile = self.profile()
+        length, remote_bytes, program_offset, program_count = self._group_layout(
+            profile["model_id"]
+        )
+        record = 2340 if profile["model_id"] in EVOLUTION_MODELS else 2317
+        data = self._exchange(record, expected_length=length)
+        remote_bits = int.from_bytes(data[:remote_bytes], "little")
+        return {
+            "programs": [
+                {
+                    "program": i + 1,
+                    "state": value & 0x0F,
+                    "state_name": PROGRAM_STATE_NAMES.get(value & 0x0F, "unknown"),
+                    "state_group": (
+                        "disarmed" if (value & 0x0F) == 0
+                        else "partial" if (value & 0x0F) in (4, 5)
+                        else "armed-or-transition"
+                    ),
+                    "armed": (value & 0x0F) != 0,
+                    "prealarm": bool(value & 0x10),
+                    "alarm": bool(value & 0x20),
+                    "alarm_memory": bool(value & 0x40),
+                    "flags": value & 0xF0,
+                }
+                for i, value in enumerate(
+                    data[
+                        program_offset : program_offset
+                        + min(program_count, profile["max_programs"])
+                    ]
+                )
+            ],
+            "remotes": [
+                {"remote": i + 1, "on": bool(remote_bits & (1 << i))}
+                for i in range(profile["max_remotes"])
+            ],
+            "raw": data.hex(),
+        }
+
+    def permissions(self):
+        if self._permissions is not None:
+            return self._permissions
+        model = self.profile()["model_id"]
+        length = 12 if model in (35, 36, 47, 48) else 8
+        data = self._exchange(2314, index=self.session, expected_length=length)
+        program_mask = int.from_bytes(data[:4], "little")
+        remote_flag_offset = (4 if model in (35, 36, 47, 48, 57, 58) else 0) + 6
+        self._permissions = {
+            "program_mask": program_mask,
+            "programs": [
+                i + 1
+                for i in range(self.profile()["max_programs"])
+                if program_mask & (1 << i)
+            ],
+            "remote_access": (
+                not bool(data[remote_flag_offset] & 0x02)
+                if remote_flag_offset < len(data)
+                else None
+            ),
+            "raw": data.hex(),
+        }
+        return self._permissions
+
+    def _description(self, kind, index):
+        if kind not in ("program", "remote", "zone", "code"):
+            raise ValueError(f"unknown description type {kind!r}")
+        profile = self.profile()
+        model = profile["model_id"]
+        maximum = profile["max_code_names" if kind == "code" else f"max_{kind}s"]
+        if not 0 <= index < maximum:
+            raise ValueError(f"{kind} must be between 1 and {maximum}")
+
+        if kind == "program":
+            record, length, fallback = 2307, (32 if model in LONG_TEXT_MODELS else 24), f"P{index + 1}"
+        elif kind == "remote":
+            record = 2339 if model in EVOLUTION_MODELS else 2308
+            length = 38 if model in EVOLUTION_MODELS else (34 if model in LONG_TEXT_MODELS else 26)
+            fallback = f"T{index + 1}"
+        elif kind == "zone":
+            record, length, fallback = 2310, (32 if model in LONG_TEXT_MODELS else 24), f"Z{index + 1}"
+        else:
+            record, length, fallback = 2309, (24 if model in LONG_TEXT_MODELS else 16), f"Cod{index + 1}"
+
+        raw = self._exchange(record, index=index, expected_length=length)
+        encoded = raw[:16].split(b"\0", 1)[0]
+        encoding = "iso-8859-7" if profile["firmware_nature"] == 5 else "utf-8"
+        return encoded.decode(encoding, "replace").rstrip() or fallback
+
+    def descriptions(self, kind, start=0, count=None):
+        if kind not in ("program", "remote", "zone", "code"):
+            raise ValueError(f"unknown description type {kind!r}")
+        profile = self.profile()
+        maximum = profile["max_code_names" if kind == "code" else f"max_{kind}s"]
+        start, count = self._range(kind, start, count, maximum)
+        return [
+            {kind: i + 1, "name": self._description(kind, i)}
+            for i in range(start, start + count)
+        ]
+
+    @staticmethod
+    def _range(kind, start, count, maximum):
+        if not 0 <= start < maximum:
+            raise ValueError(f"first {kind} must be between 1 and {maximum}")
+        if count is None:
+            count = maximum - start
+        if count < 1 or start + count > maximum:
+            raise ValueError(f"{kind} range exceeds 1..{maximum}")
+        return start, count
+
+    def programs(self):
+        states = self.group_status()["programs"]
+        enabled = set(self.permissions()["programs"])
+        for item in states:
+            item["name"] = self._description("program", item["program"] - 1)
+            item["enabled"] = item["program"] in enabled
+        return states
+
+    def remotes(self):
+        states = self.group_status()["remotes"]
+        access = self.permissions()["remote_access"]
+        for item in states:
+            item["name"] = self._description("remote", item["remote"] - 1)
+            item["enabled"] = access
+        return states
+
+    @staticmethod
+    def _decode_zone(zone, data):
+        return {
+            "zone": zone + 1,
+            "open": bool(data[0] & 0x02 or data[3] & 0x02),
+            "isolated": bool(data[0] & 0x01),
+            "raw": data.hex(),
+        }
+
+    def zone_statuses(self, start=0, count=None):
+        maximum = self.profile()["max_zones"]
+        start, count = self._range("zone", start, count, maximum)
+        result = []
+        while count:
+            batch = min(count, 25)
+            raw = self._exchange(
+                2316, index=start, payload=struct.pack("<H", batch),
+                expected_length=batch * 4,
+            )
+            result.extend(
+                self._decode_zone(start + i, raw[i * 4 : i * 4 + 4])
+                for i in range(batch)
+            )
+            start += batch
+            count -= batch
+        return result
+
+    def zone_status(self, zone):
+        return self.zone_statuses(zone, 1)[0]
+
+    def zones(self, start=0, count=None):
+        result = self.zone_statuses(start, count)
+        for item in result:
+            item["name"] = self._description("zone", item["zone"] - 1)
+        return result
+
+    def code_names(self, start=0, count=None):
+        return self.descriptions("code", start, count)
+
+    def sync(self):
+        return {
+            "panel": self.panel_info(),
+            "permissions": self.permissions(),
+            "programs": self.programs(),
+            "remotes": self.remotes(),
+            "zones": self.zones(),
+            "code_names": self.code_names(),
+        }
+
+    def events(self, limit=50):
+        if limit < 0:
+            raise ValueError("event limit cannot be negative")
+        capacity = self.profile()["event_capacity"]
+        wanted = capacity if limit == 0 else min(limit, capacity)
+        start_index = int.from_bytes(self._exchange(2311, expected_length=2), "little")
+        result = []
+        finished = False
+        while len(result) < wanted and not finished:
+            batch = min(12, wanted - len(result))
+            raw = self._exchange(
+                2312, index=len(result) + 1, payload=struct.pack("<H", batch),
+                expected_length=batch * 8,
+            )
+            for i in range(batch):
+                event = raw[i * 8 : i * 8 + 8]
+                if event[:4] == b"\xff\xff\xff\xff":
+                    finished = True
+                    break
+                result.append(self._decode_event(len(result) + 1, event))
+        return {"start_index": start_index, "events": result}
+
+    @staticmethod
+    def _decode_event(index, data):
+        seconds = int.from_bytes(data[4:8], "little")
+        timestamp = datetime(2000, 1, 1) + timedelta(seconds=seconds)
+        return {
+            "index": index,
+            "timestamp": timestamp.isoformat(sep=" "),
+            "event": data[0] | ((data[1] << 8) & 0x300),
+            "argument": data[2] | ((data[3] << 8) & 0x300),
+            "detail_1": (data[1] >> 2) & 0x3F,
+            "detail_2": (data[3] >> 2) & 0x3F,
+            "raw": data.hex(),
+        }
+
+    def status(self):
+        return {
+            "panel": self.panel_info(),
+            "clock_raw": self.clock.hex(),
+            "status": self.panel_status(),
+            **self.group_status(),
+        }
+
+    def watch(self, interval=30.0, reconnect_delay=30.0, wait=None):
+        """Yield alarm and connection events, closing the panel between polls."""
+        if not 5 <= interval < float("inf"):
+            raise ValueError("watch interval must be at least 5 seconds")
+        if not 5 <= reconnect_delay < float("inf"):
+            raise ValueError("reconnect delay must be at least 5 seconds")
+        if self.sock is None:
+            self.connect()
+        wait = wait or time.sleep
+
+        previous = None
+        disconnected = False
+        while True:
+            pending = []
+            delay = interval
+            try:
+                if self.sock is None:
+                    self.connect()
+                group = self.group_status()
+                programs = group["programs"]
+                started = []
+                state_changes = []
+                changes = []
+                if previous is not None:
+                    for program in programs:
+                        before = previous.get(program["program"], {})
+                        detected_by = [
+                            name
+                            for name in ("alarm", "alarm_memory")
+                            if program[name] and not before.get(name, False)
+                        ]
+                        if detected_by:
+                            started.append((program, detected_by))
+                        state = program["state"]
+                        before_state = before.get("state")
+                        if state != before_state:
+                            changes.append(
+                                f"program {program['program']} "
+                                f"{PROGRAM_STATE_NAMES.get(before_state, 'unknown')}"
+                                f"({before_state}) -> {program['state_name']}({state}), "
+                                f"flags=0x{program['flags']:02x}"
+                            )
+                            if before_state == 0 and state in (1, 2, 4):
+                                state_changes.append(
+                                    ("program_arming", program, before_state)
+                                )
+                            elif state in (3, 5, 6):
+                                state_changes.append(
+                                    ("program_armed", program, before_state)
+                                )
+                            elif state == 0:
+                                state_changes.append(
+                                    ("program_disarmed", program, before_state)
+                                )
+                panel = self.panel_status()["general"] if started else None
+                log = self.events(1)["events"] if started else []
+                if previous is None:
+                    active = [
+                        f"program {program['program']} {program['state_name']}"
+                        f"({program['state']}) flags=0x{program['flags']:02x}"
+                        for program in programs
+                        if program["state"] or program["flags"]
+                    ]
+                    poll_result = "baseline: " + (
+                        "; ".join(active) or "all programs disarmed"
+                    )
+                else:
+                    poll_result = "; ".join(changes) or "no program changes"
+                poll_logger = (
+                    logger.info
+                    if previous is None or changes or started
+                    else logger.debug
+                )
+                poll_logger(
+                    "watch poll succeeded: %s; next request in %g seconds",
+                    poll_result,
+                    interval,
+                )
+            except (OSError, ProtocolError) as exc:
+                if not disconnected:
+                    pending.append(
+                        {
+                            "type": "connection_lost",
+                            "timestamp": datetime.now()
+                            .astimezone()
+                            .isoformat(timespec="seconds"),
+                            "error": str(exc),
+                        }
+                    )
+                disconnected = True
+                delay = reconnect_delay
+                logger.info(
+                    "watch poll failed: %s; next request in %g seconds",
+                    exc,
+                    reconnect_delay,
+                )
+            else:
+                timestamp = datetime.now().astimezone().isoformat(timespec="seconds")
+                if disconnected:
+                    pending.append(
+                        {"type": "connection_restored", "timestamp": timestamp}
+                    )
+                    disconnected = False
+                for program, detected_by in started:
+                    pending.append(
+                        {
+                            "type": "alarm",
+                            "timestamp": timestamp,
+                            "program": program["program"],
+                            "detected_by": detected_by,
+                            "program_status": program,
+                            "panel_status": panel,
+                            "latest_event": log[0] if log else None,
+                        }
+                    )
+                for event_type, program, before_state in state_changes:
+                    pending.append(
+                        {
+                            "type": event_type,
+                            "timestamp": timestamp,
+                            "program": program["program"],
+                            "previous_state": before_state,
+                            "previous_state_name": PROGRAM_STATE_NAMES.get(
+                                before_state, "unknown"
+                            ),
+                            "mode": (
+                                "partial"
+                                if program["state"] in (4, 5)
+                                else "full"
+                                if program["state"] in (1, 2, 3, 6)
+                                else None
+                            ),
+                            "program_status": program,
+                        }
+                    )
+                previous = {program["program"]: program for program in programs}
+            finally:
+                self.close()
+
+            yield from pending
+            wait(delay)
+
+    @staticmethod
+    def _operation_payload(action, target, session, open_zones=()):
+        if not 0 <= target <= 0xFF:
+            raise ValueError("program/remote number is out of range")
+        if len(open_zones) > 25:
+            raise ProtocolError("the panel reported more than 25 open zones")
+        payload = bytearray(60)
+        payload[0], payload[1] = action, target
+        payload[4:6] = session.to_bytes(2, "little")
+        payload[6], payload[7] = 14, 32
+        for position, zone in enumerate(open_zones):
+            struct.pack_into("<H", payload, 10 + position * 2, zone)
+        return payload
+
+    def _operation(self, action, target, open_zones=()):
+        payload = self._operation_payload(action, target, self.session, open_zones)
+        response = self._exchange(2306, payload=payload, expected_length=1)
+        if response != bytes((ACK,)):
+            raise ProtocolError(f"operation failed: {response.hex()}")
+
+    def _priority(self):
+        self._exchange(2319, payload=b"\x01\x00\x00\x00")
+
+    def _check_target(self, kind, target):
+        maximum = self.profile()[f"max_{kind}s"]
+        if not 0 <= target < maximum:
+            raise ValueError(f"{kind} must be between 1 and {maximum}")
+
+    def open_zones(self, program):
+        self._check_target("program", program)
+        payload = self._operation_payload(24, program, self.session)
+        response = self._exchange(2306, payload=payload, expected_length=104)
+        if response[0] != ACK:
+            raise ProtocolError(f"open-zone query failed: {response.hex()}")
+        count = int.from_bytes(response[2:4], "little")
+        if count > 50:
+            raise ProtocolError(f"invalid open-zone count {count}")
+        return [int.from_bytes(response[4 + i * 2 : 6 + i * 2], "little") for i in range(count)]
+
+    def arm(self, program, exclude_open=False):
+        self._check_target("program", program)
+        if program + 1 not in self.permissions()["programs"]:
+            raise ProtocolError(f"access code cannot control program {program + 1}")
+        if self.panel_status()["general"]["maintenance"]:
+            raise ProtocolError("the panel is in maintenance mode")
+        zones = self.open_zones(program)
+        if zones and not exclude_open:
+            shown = ", ".join(str(zone + 1) for zone in zones)
+            raise ProtocolError(
+                f"program has open zones ({shown}); close them or rerun with --exclude-open"
+            )
+        if len(zones) > 25:
+            raise ProtocolError("cannot exclude more than 25 open zones")
+        self._priority()
+        self._operation(3, program, zones)
+        return zones
+
+    def disarm(self, program):
+        self._check_target("program", program)
+        if program + 1 not in self.permissions()["programs"]:
+            raise ProtocolError(f"access code cannot control program {program + 1}")
+        self._priority()
+        self._operation(4, program)
+
+    def remote(self, remote, turn_on):
+        self._check_target("remote", remote)
+        if self.permissions()["remote_access"] is False:
+            raise ProtocolError("access code cannot control remotes")
+        self._priority()
+        self._operation(11 if turn_on else 12, remote)
+
+    def set_zone_isolation(self, zone, isolated):
+        self._check_target("zone", zone)
+        if self.session != 1:
+            raise ProtocolError("zone isolation requires a master access code")
+        self._priority()
+        response = self._exchange(2320 if isolated else 2321, index=zone, expected_length=1)
+        if response != bytes((ACK,)):
+            raise ProtocolError(f"zone operation failed: {response.hex()}")

tecnoctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: tecnoctl
+Version: 0.1.0
+Summary: Unofficial client for the myTecnoalarm direct TCP protocol
+License-Expression: MIT
+Project-URL: Repository, https://github.com/EnricoDev1/tecnoctl
+Project-URL: Issues, https://github.com/EnricoDev1/tecnoctl/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=47
+Requires-Dist: python-dotenv>=1
+Dynamic: license-file
+
+# tecnoctl
+
+Unofficial Python client and CLI for the direct TCP interface used by the
+myTecnoalarm Android application. It does not use Tecnoalarm cloud, HTTP, or
+video services.
+
+> Experimental: This project was developed with AI assistance. The protocol was reverse-engineered and has not been tested on
+> every hardware. Start with read-only commands. The protocol uses unauthenticated
+> AES-CFB; never expose TCP port 10001 to the Internet. Use a trusted LAN or VPN.
+
+## Install
+
+```sh
+python3 -m pip install .
+```
+
+## CLI
+
+```sh
+cp .env.example .env
+# Edit .env with your credentials.
+
+tecnoctl HOST status
+tecnoctl HOST --verbose status
+tecnoctl HOST --debug status
+tecnoctl HOST zones
+tecnoctl HOST watch
+tecnoctl HOST arm 1
+tecnoctl HOST disarm 1
+```
+
+The CLI loads `.env` automatically; exported variables take precedence. Run
+`tecnoctl --help` for all commands. CLI IDs are one-based. `watch` connects,
+checks, and disconnects every 30 seconds, then prints JSON when an alarm starts,
+a program starts arming or becomes armed/disarmed, or connectivity changes. The
+minimum `--interval` is 5 seconds. Add `--debug` before any command for
+connection and protocol diagnostics, or `--verbose` for quieter connection
+status. 
+
+> `watch` is experimental and is not a primary alarm notification system. Some
+> panels accept only one direct TCP client, so each check may briefly delay the
+> official app.
+
+## Python API
+
+```python
+from tecnoctl import AlarmClient
+
+with AlarmClient("192.168.1.20", "network passphrase", "123456") as alarm:
+    print(alarm.status())
+    alarm.arm(0)  # Library indexes are zero-based.
+```
+
+The class also exposes panel, program, remote, zone, permission, and event-log
+queries. `alarm.watch()` yields JSON-friendly alarm and connection events. See
+`AlarmClient` in `tecnoctl/client.py`.
+
+## Development
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+MIT licensed. Tecnoalarm is a trademark of its owner; this project is not
+affiliated with or endorsed by Tecnoalarm.

tecnoctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tecnoctl/__init__.py,sha256=uES9w0iuTW-LAHqdl65aA9be2suI0AlKc-sWM90iB48,123
+tecnoctl/cli.py,sha256=C8X9QU_TYIOet_gbJ2kXvt8q3vj-XWzAigvHIDL0k68,10451
+tecnoctl/client.py,sha256=l__wb-tr5GtyHNIW8QCxYviREygotHnxyxMOF2XQgj4,34645
+tecnoctl-0.1.0.dist-info/licenses/LICENSE,sha256=ntSkcBE0pYiR6FqDRWMZG0e-3RyBm8otTxW3kJltpOs,1063
+tecnoctl-0.1.0.dist-info/METADATA,sha256=VtsQQuao4vs3Pmjvac3R-GK0gllOUX8dm_9YTLtCyAM,2452
+tecnoctl-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tecnoctl-0.1.0.dist-info/entry_points.txt,sha256=wwlcylXrI4_LH-IPlHseurU2tHU4yOQAHZRiynviujQ,47
+tecnoctl-0.1.0.dist-info/top_level.txt,sha256=87qt0VncNtLnhj3iXXFw5VWWerspseRKhU7eZAYwKWg,9
+tecnoctl-0.1.0.dist-info/RECORD,,

tecnoctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tecnoctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tecnoctl = tecnoctl.cli:main

tecnoctl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enrico
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tecnoctl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tecnoctl