ttypal-ai 0.1.0__tar.gz

ttypal_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hjp
+
+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.

ttypal_ai-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: ttypal-ai
+Version: 0.1.0
+Summary: Serial port debug tool for humans and AI agents
+License: MIT
+Keywords: serial,uart,debug,embedded,AI,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Dynamic: license-file
+
+# ttypal
+
+Serial port debug tool designed for both humans and AI agents.
+
+## Features
+
+- Interactive terminal (like minicom, but better)
+- Auto-logging with timestamps and rotation
+- External command injection via Unix socket (for AI/scripts)
+- Record/replay serial sessions
+- Board config management
+- Claude Code plugin for AI-driven serial debugging
+
+## Install
+
+```bash
+pip install ttypal
+```
+
+## Quick Start
+
+```bash
+# Interactive mode
+ttypal
+
+# Headless daemon (for AI automation)
+ttypal-daemon start -b myboard
+
+# Send commands from another process
+ttypal-send --wait "# " "uname -a"
+
+# Read recent serial output
+ttypal-tail -n 50
+```
+
+## Claude Code Integration
+
+```bash
+claude --plugin-dir /path/to/ttypal
+# Then use /ttypal skill or just ask AI to operate the serial port
+```
+
+## License
+
+MIT

ttypal_ai-0.1.0/README.md

@@ -0,0 +1,45 @@
+# ttypal
+
+Serial port debug tool designed for both humans and AI agents.
+
+## Features
+
+- Interactive terminal (like minicom, but better)
+- Auto-logging with timestamps and rotation
+- External command injection via Unix socket (for AI/scripts)
+- Record/replay serial sessions
+- Board config management
+- Claude Code plugin for AI-driven serial debugging
+
+## Install
+
+```bash
+pip install ttypal
+```
+
+## Quick Start
+
+```bash
+# Interactive mode
+ttypal
+
+# Headless daemon (for AI automation)
+ttypal-daemon start -b myboard
+
+# Send commands from another process
+ttypal-send --wait "# " "uname -a"
+
+# Read recent serial output
+ttypal-tail -n 50
+```
+
+## Claude Code Integration
+
+```bash
+claude --plugin-dir /path/to/ttypal
+# Then use /ttypal skill or just ask AI to operate the serial port
+```
+
+## License
+
+MIT

ttypal_ai-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ttypal-ai"
+version = "0.1.0"
+description = "Serial port debug tool for humans and AI agents"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["serial", "uart", "debug", "embedded", "AI", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: System :: Hardware",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = [
+    "pyserial>=3.5",
+    "tomli-w>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.scripts]
+ttypal = "ttypal.main:main"
+ttypal-send = "ttypal.cli_send:main"
+ttypal-tail = "ttypal.cli_tail:main"
+ttypal-daemon = "ttypal.cli_headless:main"
+
+[tool.setuptools.packages.find]
+include = ["ttypal*"]

ttypal_ai-0.1.0/setup.cfg

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

ttypal_ai-0.1.0/tests/test_ai_e2e.py

@@ -0,0 +1,169 @@
+"""
+AI 端到端测试：验证通过 socket 发命令能得到正确的设备回复。
+模拟 AI 的完整工作流：ttypal-send --wait "# " "command"
+"""
+import json
+import socket
+import threading
+import time
+from pathlib import Path
+
+from ttypal.replay_backend import ReplayBackend
+from ttypal.logger import Logger
+from ttypal.socket_server import SocketServer
+
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def _start_reader(backend, logger, stop_event):
+    """模拟 terminal 的 reader 线程：从串口读数据写入 logger"""
+    while not stop_event.is_set():
+        data = backend.read()
+        if data:
+            logger.write(data)
+        elif not backend.is_open:
+            break
+        else:
+            time.sleep(0.01)
+
+
+def _send_request(sock_path, req):
+    """通过 socket 发请求，返回响应"""
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.connect(sock_path)
+    s.sendall(json.dumps(req).encode() + b"\n")
+    s.shutdown(socket.SHUT_WR)
+
+    resp_data = b""
+    while True:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        resp_data += chunk
+    s.close()
+    return json.loads(resp_data)
+
+
+def test_ai_send_echo_gets_correct_output(tmp_path):
+    """AI 发送 'echo hello'，验证返回内容包含 'hello'"""
+    backend = ReplayBackend(str(FIXTURES / "basic_commands.rec"), realtime=True)
+    backend.open()
+
+    logger = Logger("ai_test", directory=str(tmp_path / "logs"))
+    sock_path = str(tmp_path / "ai.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    stop = threading.Event()
+    reader = threading.Thread(target=_start_reader, args=(backend, logger, stop))
+    reader.start()
+
+    # 等录制前几个 RX 事件播放完（prompt 出现）
+    time.sleep(0.3)
+
+    resp = _send_request(sock_path, {
+        "cmd": "send_wait",
+        "data": "echo hello",
+        "prompt": "# ",
+        "timeout": 5,
+    })
+
+    assert resp["status"] == "ok"
+    assert "hello" in resp["output"]
+
+    stop.set()
+    srv.stop()
+    reader.join(timeout=2)
+    logger.close()
+
+
+def test_ai_send_uname_gets_kernel_info(tmp_path):
+    """AI 发送 'uname -a'，验证返回内容包含 Linux 内核信息"""
+    backend = ReplayBackend(str(FIXTURES / "basic_commands.rec"), realtime=True)
+    backend.open()
+
+    logger = Logger("ai_test2", directory=str(tmp_path / "logs"))
+    sock_path = str(tmp_path / "ai2.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    stop = threading.Event()
+    reader = threading.Thread(target=_start_reader, args=(backend, logger, stop))
+    reader.start()
+
+    # 等所有 RX 播放完
+    time.sleep(0.5)
+
+    resp = _send_request(sock_path, {
+        "cmd": "send_wait",
+        "data": "uname -a",
+        "prompt": "# ",
+        "timeout": 5,
+    })
+
+    assert resp["status"] == "ok"
+    assert "Linux" in resp["output"]
+    assert "rockchip" in resp["output"]
+
+    stop.set()
+    srv.stop()
+    reader.join(timeout=2)
+    logger.close()
+
+
+def test_ai_send_simple_no_wait(tmp_path):
+    """AI 发送命令不等待回复（fire-and-forget），验证命令被发到串口"""
+    backend = ReplayBackend(str(FIXTURES / "basic_commands.rec"), realtime=False)
+    backend.open()
+
+    logger = Logger("ai_test3", directory=str(tmp_path / "logs"))
+    sock_path = str(tmp_path / "ai3.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    time.sleep(0.1)
+
+    resp = _send_request(sock_path, {
+        "cmd": "send",
+        "data": "reboot",
+    })
+
+    assert resp["status"] == "ok"
+    assert b"reboot\r\n" in backend.sent_data
+
+    srv.stop()
+    logger.close()
+
+
+def test_ai_send_wait_timeout(tmp_path):
+    """AI 发命令等待一个不会出现的 prompt，验证超时后仍返回已收集的数据"""
+    backend = ReplayBackend(str(FIXTURES / "basic_commands.rec"), realtime=True)
+    backend.open()
+
+    logger = Logger("ai_test4", directory=str(tmp_path / "logs"))
+    sock_path = str(tmp_path / "ai4.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    stop = threading.Event()
+    reader = threading.Thread(target=_start_reader, args=(backend, logger, stop))
+    reader.start()
+
+    time.sleep(0.3)
+
+    resp = _send_request(sock_path, {
+        "cmd": "send_wait",
+        "data": "ls",
+        "prompt": "IMPOSSIBLE_PROMPT>>> ",
+        "timeout": 1,
+    })
+
+    # 超时也应该返回 ok 并附带已收集的输出
+    assert resp["status"] == "ok"
+    assert "output" in resp
+
+    stop.set()
+    srv.stop()
+    reader.join(timeout=2)
+    logger.close()

ttypal_ai-0.1.0/tests/test_config.py

@@ -0,0 +1,42 @@
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from ttypal.config import (
+    load_board, save_board, list_boards, delete_board, DEFAULT_CONFIG,
+)
+
+
+@pytest.fixture
+def config_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr("ttypal.config.CONFIG_DIR", tmp_path)
+    return tmp_path
+
+
+def test_save_and_load(config_dir):
+    cfg = {"serial": {"port": "/dev/ttyUSB0", "baudrate": 115200},
+           "log": {}, "socket": {}}
+    save_board("test1", cfg)
+    loaded = load_board("test1")
+    assert loaded["serial"]["port"] == "/dev/ttyUSB0"
+    assert loaded["serial"]["baudrate"] == 115200
+
+
+def test_list_boards(config_dir):
+    save_board("alpha", DEFAULT_CONFIG)
+    save_board("beta", DEFAULT_CONFIG)
+    boards = list_boards()
+    assert boards == ["alpha", "beta"]
+
+
+def test_delete_board(config_dir):
+    save_board("todelete", DEFAULT_CONFIG)
+    assert "todelete" in list_boards()
+    delete_board("todelete")
+    assert "todelete" not in list_boards()
+
+
+def test_load_nonexistent(config_dir):
+    assert load_board("nope") is None

ttypal_ai-0.1.0/tests/test_integration.py

@@ -0,0 +1,130 @@
+"""
+集成测试：用 ReplayBackend 跑完整链路
+- socket server 接收命令 → 写入串口
+- logger 记录输出
+"""
+import json
+import socket
+import threading
+import time
+from pathlib import Path
+
+from ttypal.replay_backend import ReplayBackend
+from ttypal.logger import Logger
+from ttypal.socket_server import SocketServer
+
+
+def _create_recording(tmp_path):
+    rec_file = tmp_path / "session.rec"
+    # 模拟设备输出 prompt，然后输出命令结果，再输出 prompt
+    events = [
+        {"t": 0.0, "dir": "rx", "hex": b"root@board:~# ".hex()},
+        {"t": 0.5, "dir": "rx", "hex": b"file1  file2\r\n".hex()},
+        {"t": 0.6, "dir": "rx", "hex": b"root@board:~# ".hex()},
+    ]
+    with open(rec_file, "w") as f:
+        for e in events:
+            f.write(json.dumps(e) + "\n")
+    return str(rec_file)
+
+
+def test_socket_send(tmp_path):
+    rec_path = _create_recording(tmp_path)
+    backend = ReplayBackend(rec_path, realtime=False)
+    backend.open()
+
+    logger = Logger("integration", directory=str(tmp_path / "logs"))
+    sock_path = str(tmp_path / "test.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    time.sleep(0.1)
+
+    # send a command
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.connect(sock_path)
+    req = json.dumps({"cmd": "send", "data": "ls"}) + "\n"
+    s.sendall(req.encode())
+    s.shutdown(socket.SHUT_WR)
+
+    resp_data = b""
+    while True:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        resp_data += chunk
+    s.close()
+
+    resp = json.loads(resp_data)
+    assert resp["status"] == "ok"
+    assert backend.sent_data == b"ls\r\n"
+
+    srv.stop()
+    logger.close()
+
+
+def test_socket_send_wait(tmp_path):
+    # 创建一个带延迟的录制，模拟命令响应
+    rec_file = tmp_path / "session2.rec"
+    events = [
+        {"t": 0.0, "dir": "rx", "hex": b"# ".hex()},
+        {"t": 0.2, "dir": "rx", "hex": b"output line\r\n".hex()},
+        {"t": 0.3, "dir": "rx", "hex": b"# ".hex()},
+    ]
+    with open(rec_file, "w") as f:
+        for e in events:
+            f.write(json.dumps(e) + "\n")
+
+    backend = ReplayBackend(str(rec_file), realtime=True)
+    backend.open()
+
+    logger = Logger("integration2", directory=str(tmp_path / "logs2"))
+    sock_path = str(tmp_path / "test2.sock")
+    srv = SocketServer(backend, logger, sock_path, "# ")
+    srv.start()
+
+    time.sleep(0.2)
+
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.connect(sock_path)
+    req = json.dumps({"cmd": "send_wait", "data": "ls", "prompt": "# ", "timeout": 3}) + "\n"
+    s.sendall(req.encode())
+    s.shutdown(socket.SHUT_WR)
+
+    resp_data = b""
+    while True:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        resp_data += chunk
+    s.close()
+
+    resp = json.loads(resp_data)
+    assert resp["status"] == "ok"
+    assert "output" in resp
+
+    srv.stop()
+    logger.close()
+
+
+def test_logger_captures_replay_output(tmp_path):
+    rec_path = _create_recording(tmp_path)
+    backend = ReplayBackend(rec_path, realtime=False)
+
+    logger = Logger("capture_test", directory=str(tmp_path / "logs3"))
+    backend.open()
+
+    time.sleep(0.2)
+    while True:
+        data = backend.read()
+        if not data:
+            break
+        logger.write(data)
+
+    logger.close()
+
+    log_files = list((tmp_path / "logs3" / "capture_test").glob("*.log"))
+    assert len(log_files) == 1
+    content = log_files[0].read_text()
+    assert "root@board" in content
+    assert "file1" in content

ttypal_ai-0.1.0/tests/test_logger.py

@@ -0,0 +1,51 @@
+import tempfile
+from pathlib import Path
+
+from ttypal.logger import Logger
+
+
+def test_logger_creates_file(tmp_path):
+    logger = Logger("testboard", directory=str(tmp_path), rotate_size_kb=1)
+    logger.write(b"hello world\n")
+    logger.close()
+
+    log_files = list((tmp_path / "testboard").glob("*.log"))
+    assert len(log_files) == 1
+    content = log_files[0].read_text()
+    assert "hello world" in content
+
+
+def test_logger_adds_timestamp(tmp_path):
+    logger = Logger("testboard", directory=str(tmp_path),
+                    timestamp_format="%H:%M:%S")
+    logger.write(b"line1\n")
+    logger.close()
+
+    content = (tmp_path / "testboard").glob("*.log").__next__().read_text()
+    # timestamp format: [HH:MM:SS]
+    assert content.startswith("[")
+    assert "] line1\n" in content
+
+
+def test_logger_rotation(tmp_path):
+    logger = Logger("testboard", directory=str(tmp_path), rotate_size_kb=1)
+    # Write more than 1KB to trigger rotation
+    for i in range(200):
+        logger.write(f"{'x' * 100}\n".encode())
+    logger.close()
+
+    log_files = list((tmp_path / "testboard").glob("*.log"))
+    assert len(log_files) > 1
+
+
+def test_logger_multiline(tmp_path):
+    logger = Logger("testboard", directory=str(tmp_path),
+                    timestamp_format="%S")
+    logger.write(b"a\nb\nc\n")
+    logger.close()
+
+    content = (tmp_path / "testboard").glob("*.log").__next__().read_text()
+    lines = content.strip().split("\n")
+    assert len(lines) == 3
+    for line in lines:
+        assert line.startswith("[")

ttypal_ai-0.1.0/tests/test_recorder.py

@@ -0,0 +1,53 @@
+import json
+import tempfile
+from pathlib import Path
+
+from ttypal.recorder import Recorder
+
+
+def test_record_and_load(tmp_path):
+    rec_file = tmp_path / "test.rec"
+    recorder = Recorder(output_path=str(rec_file))
+
+    recorder.record_rx(b"hello")
+    recorder.record_tx(b"world")
+    recorder.close()
+
+    events = Recorder.load(str(rec_file))
+    assert len(events) == 2
+    assert events[0]["dir"] == "rx"
+    assert events[0]["hex"] == b"hello".hex()
+    assert events[1]["dir"] == "tx"
+    assert events[1]["hex"] == b"world".hex()
+    assert events[1]["t"] >= events[0]["t"]
+
+
+def test_ring_buffer(tmp_path):
+    recorder = Recorder(ring_size=5)
+    for i in range(10):
+        recorder.record_rx(bytes([i]))
+    ring = recorder.get_ring()
+    assert len(ring) == 5
+    assert ring[0]["hex"] == bytes([5]).hex()
+    assert ring[-1]["hex"] == bytes([9]).hex()
+
+
+def test_empty_data_ignored(tmp_path):
+    rec_file = tmp_path / "test.rec"
+    recorder = Recorder(output_path=str(rec_file))
+    recorder.record_rx(b"")
+    recorder.record_tx(b"")
+    recorder.close()
+
+    events = Recorder.load(str(rec_file))
+    assert len(events) == 0
+
+
+def test_record_tx_string(tmp_path):
+    rec_file = tmp_path / "test.rec"
+    recorder = Recorder(output_path=str(rec_file))
+    recorder.record_tx("ls\r\n")
+    recorder.close()
+
+    events = Recorder.load(str(rec_file))
+    assert events[0]["hex"] == b"ls\r\n".hex()