tecnoctl 0.1.0__tar.gz

tecnoctl-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,65 @@
+# 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/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tecnoctl"
+version = "0.1.0"
+description = "Unofficial client for the myTecnoalarm direct TCP protocol"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["cryptography>=47", "python-dotenv>=1"]
+
+[project.scripts]
+tecnoctl = "tecnoctl.cli:main"
+
+[project.urls]
+Repository = "https://github.com/EnricoDev1/tecnoctl"
+Issues = "https://github.com/EnricoDev1/tecnoctl/issues"

tecnoctl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tecnoctl-0.1.0/tecnoctl/__init__.py

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

tecnoctl-0.1.0/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()