limivia 0.1.0__py3-none-any.whl

limivia/__init__.py

@@ -0,0 +1,22 @@
+from ._client import AsyncLimivia as AsyncLimivia
+from ._client import Backend as Backend
+from ._client import Connection as Connection
+from ._client import Limivia as Limivia
+from ._connection import AsyncConnection as AsyncConnection
+from ._exceptions import (
+    DeviceConnectionError as DeviceConnectionError,
+)
+from ._exceptions import (
+    InvalidCommandError as InvalidCommandError,
+)
+from ._exceptions import (
+    LimiviaError as LimiviaError,
+)
+from ._exceptions import (
+    ProtocolError as ProtocolError,
+)
+from ._exceptions import (
+    QueueFullError as QueueFullError,
+)
+
+__version__ = "0.1.0"

limivia/_client.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import AbstractContextManager
+from functools import partial
+from typing import Protocol, Self
+
+from anyio.from_thread import BlockingPortal, start_blocking_portal
+
+from ._connection import AsyncConnection
+from ._exceptions import DeviceConnectionError
+from .resources import (
+    ADCResource,
+    GPIOResource,
+    OutputsResource,
+    PinResource,
+    PWMResource,
+    StateResource,
+    TimerResource,
+)
+from .transports import DeviceBackend, Transport
+from .types import ClientEvent, ClientEventParam, DeviceEvent, DeviceInfo, LinkKind
+
+
+class Backend(Protocol):
+    async def discover(self, kind: LinkKind) -> list[dict[str, str]]: ...
+    def transport(self, kind: LinkKind, target: str) -> Transport: ...
+
+
+class AsyncDevices:
+    def __init__(self, client: AsyncLimivia):
+        self._client = client
+
+    async def list(self, *, kind: LinkKind = "ble") -> list[DeviceInfo]:
+        client = self._client
+        client._check()
+        if kind not in ("ble", "usb"):
+            raise ValueError("kind 必须为 ble 或 usb。")
+        if client._active is not None or client._scanning:
+            raise DeviceConnectionError("正在连接设备或搜索设备，请先断开或等待搜索结束。")
+        client._scanning = asyncio.current_task()
+        try:
+            devices = await asyncio.wait_for(client._backend.discover(kind), timeout=12)
+            return [DeviceInfo.model_validate(device) for device in devices]
+        finally:
+            client._scanning = None
+
+    def connect(self, *, kind: LinkKind = "ble", target: str) -> AsyncConnectionManager:
+        return AsyncConnectionManager(self._client, kind, target)
+
+
+class AsyncConnectionManager:
+    def __init__(self, client: AsyncLimivia, kind: LinkKind, target: str):
+        self._client = client
+        self._kind = kind
+        self._target = target
+        self._connection: AsyncConnection | None = None
+        self._entered = False
+
+    async def __aenter__(self) -> AsyncConnection:
+        client = self._client
+        client._check()
+        if self._entered:
+            raise DeviceConnectionError("连接上下文不能重复使用。")
+        self._entered = True
+        if self._kind not in ("ble", "usb"):
+            raise ValueError("kind 必须为 ble 或 usb。")
+        if client._active is not None or client._scanning:
+            raise DeviceConnectionError("已有活动连接或正在扫描，请先结束当前会话。")
+        connection = AsyncConnection(
+            client._backend.transport(self._kind, self._target),
+            timeout=client.timeout,
+            connect_timeout=client.connect_timeout,
+            event_queue_size=client.event_queue_size,
+        )
+        self._connection = connection
+        client._active = connection
+        client._opening = asyncio.current_task()
+        try:
+            await connection._open()
+        except BaseException:
+            client._active = None
+            raise
+        finally:
+            client._opening = None
+        return connection
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        if self._connection is not None:
+            try:
+                await self._connection.close()
+            finally:
+                if self._client._active is self._connection:
+                    self._client._active = None
+
+
+class AsyncLimivia:
+    def __init__(
+        self,
+        *,
+        timeout: float = 6,
+        connect_timeout: float = 20,
+        event_queue_size: int = 256,
+        backend: Backend | None = None,
+    ):
+        if timeout <= 0 or connect_timeout <= 0 or event_queue_size < 1:
+            raise ValueError("超时和事件缓冲大小必须大于零。")
+        self.timeout = timeout
+        self.connect_timeout = connect_timeout
+        self.event_queue_size = event_queue_size
+        self._backend = backend if backend is not None else DeviceBackend()
+        self._active: AsyncConnection | None = None
+        self._scanning: asyncio.Task | None = None
+        self._opening: asyncio.Task | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._closed = False
+        self.devices = AsyncDevices(self)
+
+    def _check(self) -> None:
+        if self._closed:
+            raise DeviceConnectionError("客户端已关闭。")
+        loop = asyncio.get_running_loop()
+        if self._loop is not None and self._loop is not loop:
+            raise DeviceConnectionError("同一个 AsyncLimivia 必须始终在同一事件循环使用。")
+        self._loop = loop
+
+    async def __aenter__(self) -> Self:
+        self._check()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._check()
+        self._closed = True
+        if self._scanning and self._scanning is not asyncio.current_task():
+            self._scanning.cancel()
+            await asyncio.gather(self._scanning, return_exceptions=True)
+        if self._opening and self._opening is not asyncio.current_task():
+            self._opening.cancel()
+            await asyncio.gather(self._opening, return_exceptions=True)
+        if self._active:
+            await self._active.close()
+            self._active = None
+
+
+class Connection:
+    def __init__(self, connection: AsyncConnection, portal: BlockingPortal):
+        self._connection = connection
+        self._portal = portal
+        self.handshake_request_id = connection.handshake_request_id
+        self.state = StateResource(self.send)
+        self.gpio = GPIOResource(self.send)
+        self.pwm = PWMResource(self.send)
+        self.adc = ADCResource(self.send)
+        self.timer = TimerResource(self.send)
+        self.pin = PinResource(self.send)
+        self.outputs = OutputsResource(self.send)
+
+    def send(self, event: ClientEvent | ClientEventParam) -> int:
+        return self._portal.call(self._connection.send, event)
+
+    def hello(self) -> int:
+        return self._portal.call(self._connection.hello)
+
+    def recv(self) -> DeviceEvent:
+        try:
+            return self._portal.call(self._connection.recv)
+        except StopAsyncIteration:
+            raise StopIteration from None
+
+    def __iter__(self) -> Self:
+        return self
+
+    def __next__(self) -> DeviceEvent:
+        return self.recv()
+
+    def close(self) -> None:
+        self._portal.call(self._connection.close)
+
+
+class ConnectionManager:
+    def __init__(self, client: Limivia, kind: LinkKind, target: str):
+        self._client = client
+        self._kind = kind
+        self._target = target
+        self._manager: AsyncConnectionManager | None = None
+        self._entered = False
+
+    def __enter__(self) -> Connection:
+        if self._entered:
+            raise DeviceConnectionError("连接上下文不能重复使用。")
+        self._entered = True
+        portal, client = self._client._ensure()
+        self._manager = client.devices.connect(kind=self._kind, target=self._target)
+        return Connection(portal.call(self._manager.__aenter__), portal)
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._manager is not None and self._client._portal is not None:
+            self._client._portal.call(self._manager.__aexit__, exc_type, exc, tb)
+
+
+class Devices:
+    def __init__(self, client: Limivia):
+        self._client = client
+
+    def list(self, *, kind: LinkKind = "ble") -> list[DeviceInfo]:
+        portal, client = self._client._ensure()
+        return portal.call(partial(client.devices.list, kind=kind))
+
+    def connect(self, *, kind: LinkKind = "ble", target: str) -> ConnectionManager:
+        return ConnectionManager(self._client, kind, target)
+
+
+class Limivia:
+    """同步门面；后台 asyncio 循环在整个客户端生命周期内持续运行。"""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 6,
+        connect_timeout: float = 20,
+        event_queue_size: int = 256,
+        backend: Backend | None = None,
+    ):
+        self._factory = partial(
+            AsyncLimivia,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+            event_queue_size=event_queue_size,
+            backend=backend,
+        )
+        self._portal_context: AbstractContextManager[BlockingPortal] | None = None
+        self._portal: BlockingPortal | None = None
+        self._client: AsyncLimivia | None = None
+        self._closed = False
+        self.devices = Devices(self)
+
+    def _ensure(self) -> tuple[BlockingPortal, AsyncLimivia]:
+        if self._closed:
+            raise DeviceConnectionError("客户端已关闭。")
+        if self._portal is None:
+            self._portal_context = start_blocking_portal(backend="asyncio", name="limivia-sync")
+            self._portal = self._portal_context.__enter__()
+            try:
+                self._client = self._portal.call(self._factory)
+            except BaseException:
+                self._portal_context.__exit__(None, None, None)
+                self._portal = None
+                raise
+        assert self._client is not None
+        return self._portal, self._client
+
+    def __enter__(self) -> Self:
+        self._ensure()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._portal is not None:
+            try:
+                assert self._client is not None
+                self._portal.call(self._client.close)
+            finally:
+                assert self._portal_context is not None
+                self._portal_context.__exit__(None, None, None)
+                self._portal = None

limivia/_connection.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections import deque
+from dataclasses import dataclass
+
+from anyio import CancelScope
+
+from ._exceptions import DeviceConnectionError, ProtocolError, QueueFullError
+from .protocol import LineReader, decode_message, encode_command, parse_command
+from .resources import (
+    ADCResource,
+    GPIOResource,
+    OutputsResource,
+    PinResource,
+    PWMResource,
+    StateResource,
+    TimerResource,
+)
+from .transports import Transport
+from .types import (
+    ClientEvent,
+    ClientEventParam,
+    CommandFailedEvent,
+    ConnectionClosedEvent,
+    DeviceError,
+    DeviceEvent,
+    HelloCommand,
+    HelloCompletedEvent,
+    ProtocolErrorEvent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _Request:
+    id: int
+    command: ClientEvent
+    data: bytes
+    done: asyncio.Event
+    sent: bool = False
+
+
+class AsyncConnection:
+    """一个读循环、一个写循环；事件消费不会负责推进命令或超时。"""
+
+    def __init__(
+        self, transport: Transport, *, timeout: float, connect_timeout: float, event_queue_size: int
+    ):
+        self._transport = transport
+        self._timeout = timeout
+        self._connect_timeout = connect_timeout
+        self._event_limit = event_queue_size
+        self._outgoing: asyncio.Queue[_Request] = asyncio.Queue(maxsize=8)
+        self._pending: dict[int, _Request] = {}
+        self._events: deque[DeviceEvent] = deque()
+        # 终态另存，缓冲溢出时也能交付已完成命令及至多九个待处理命令的失败。
+        self._terminal: deque[DeviceEvent] = deque()
+        self._wake = asyncio.Event()
+        self._receiving = False
+        self._opened = False
+        self._closed = False
+        self._sequence = 0
+        self._tasks: list[asyncio.Task[None]] = []
+        self._cleanup_task: asyncio.Task[None] | None = None
+        self._ready: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+        self.handshake_request_id = 0
+        self.state = StateResource(self.send)
+        self.gpio = GPIOResource(self.send)
+        self.pwm = PWMResource(self.send)
+        self.adc = ADCResource(self.send)
+        self.timer = TimerResource(self.send)
+        self.pin = PinResource(self.send)
+        self.outputs = OutputsResource(self.send)
+
+    async def _open(self) -> None:
+        try:
+            async with asyncio.timeout(self._connect_timeout):
+                await self._transport.open()
+                if self._closed:
+                    raise DeviceConnectionError("连接已关闭。")
+                self._opened = True
+                self._tasks = [
+                    asyncio.create_task(self._read(), name="limivia-reader"),
+                    asyncio.create_task(self._write(), name="limivia-writer"),
+                ]
+                self.handshake_request_id = await self.hello()
+                await self._ready
+                if self._closed:
+                    raise DeviceConnectionError("设备在握手结束时断开，请重新连接。")
+        except BaseException:
+            await self.close()
+            raise
+
+    async def hello(self) -> int:
+        return await self.send(HelloCommand())
+
+    async def send(self, event: ClientEvent | ClientEventParam) -> int:
+        """校验并原子入队后返回 ID；执行结果只通过事件流交付。"""
+        if not self._opened or self._closed:
+            raise DeviceConnectionError("设备连接已关闭，请重新连接。")
+        command = parse_command(event)
+        if self._sequence >= 2147483647:
+            raise DeviceConnectionError("请求 ID 已耗尽，请重新连接。")
+        request_id = self._sequence + 1
+        data = encode_command(command, request_id)
+        request = _Request(request_id, command, data, asyncio.Event())
+        try:
+            self._outgoing.put_nowait(request)
+        except asyncio.QueueFull as exc:
+            raise QueueFullError("已有八个等待命令，请消费结果后再发送。") from exc
+        # 此方法无挂起点；返回后桥接可在下次 await 前注册外部请求 ID。
+        self._sequence = request_id
+        self._pending[request_id] = request
+        return request_id
+
+    def __aiter__(self) -> AsyncConnection:
+        return self
+
+    async def __anext__(self) -> DeviceEvent:
+        return await self.recv()
+
+    async def recv(self) -> DeviceEvent:
+        """每个连接仅一个消费者；取消等待不会丢失事件。"""
+        if self._receiving:
+            raise RuntimeError("一个连接只能有一个事件消费者。")
+        self._receiving = True
+        try:
+            while True:
+                if self._events:
+                    return self._events.popleft()
+                if self._terminal:
+                    return self._terminal.popleft()
+                if self._closed:
+                    raise StopAsyncIteration
+                self._wake.clear()
+                await self._wake.wait()
+        finally:
+            self._receiving = False
+
+    def _publish(self, event: DeviceEvent) -> None:
+        if self._closed:
+            return
+        if len(self._events) >= self._event_limit:
+            # 当前已经完成的命令不能因溢出丢失。
+            if hasattr(event, "request_id"):
+                self._terminal.append(event)
+            self._terminate(
+                DeviceError(
+                    code="event_buffer_overflow",
+                    message="事件缓冲区已满，请重连后查询状态。",
+                    source="sdk",
+                )
+            )
+            return
+        self._events.append(event)
+        self._wake.set()
+
+    def _complete(self, request: _Request, event: DeviceEvent) -> None:
+        if self._pending.pop(request.id, None) is None:
+            return
+        request.done.set()
+        if request.id == self.handshake_request_id and not self._ready.done():
+            if isinstance(event, HelloCompletedEvent):
+                if event.result.protocol == 1 and event.result.board == "luatos-esp32c3-usb":
+                    self._ready.set_result(None)
+                else:
+                    event = self._failure(
+                        request,
+                        "incompatible_device",
+                        "设备固件或协议不兼容，请安装本工程专用固件。",
+                    )
+                    self._ready.set_exception(DeviceConnectionError(event.error.message))
+                    self._ready.exception()
+            else:
+                message = (
+                    event.error.message if isinstance(event, CommandFailedEvent) else "握手失败。"
+                )
+                self._ready.set_exception(DeviceConnectionError(message))
+                self._ready.exception()
+        self._publish(event)
+
+    @staticmethod
+    def _failure(request: _Request, code: str, message: str) -> CommandFailedEvent:
+        return CommandFailedEvent(
+            request_id=request.id,
+            op=request.command.type,
+            error=DeviceError(
+                code=code, message=message, source="sdk", may_have_executed=request.sent
+            ),
+        )
+
+    async def _write(self) -> None:
+        try:
+            while not self._closed:
+                request = await self._outgoing.get()
+                deadline = asyncio.get_running_loop().time() + self._timeout
+                request.sent = True
+                try:
+                    await asyncio.wait_for(
+                        self._transport.write(request.data), timeout=min(5, self._timeout)
+                    )
+                except TimeoutError:
+                    # 半帧写入不能继续复用通道，否则下一条命令会拼接到旧帧。
+                    self._terminate(
+                        DeviceError(
+                            code="write_timeout",
+                            message="设备写入超时；操作可能已执行，请重连查询状态。",
+                            source="sdk",
+                        )
+                    )
+                    return
+                try:
+                    remaining = max(0, deadline - asyncio.get_running_loop().time())
+                    await asyncio.wait_for(request.done.wait(), timeout=remaining)
+                except TimeoutError:
+                    # 超时不重试。后续 state 请求仍可用于恢复实际状态。
+                    self._complete(
+                        request,
+                        self._failure(
+                            request, "timeout", "设备响应超时；操作可能已执行，请查询状态。"
+                        ),
+                    )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning("设备通信中断: %s", exc, exc_info=True)
+            self._terminate(DeviceError(code="connection_lost", message=str(exc), source="sdk"))
+
+    async def _read(self) -> None:
+        reader = LineReader()
+        try:
+            while not self._closed:
+                data = await self._transport.read()
+                if not data:
+                    raise DeviceConnectionError("设备连接已断开，请重新连接。")
+                for line in reader.feed(data):
+                    if self._closed:
+                        break
+                    if isinstance(line, ProtocolError):
+                        self._publish(ProtocolErrorEvent(message=str(line)))
+                        continue
+                    try:
+                        message = json.loads(line)
+                    except (ValueError, RecursionError):
+                        # USB 上可能混有固件启动日志；看起来像 JSON 的坏帧显式报告。
+                        if line.lstrip().startswith(("{", "[")):
+                            self._publish(ProtocolErrorEvent(message="设备 JSON 帧无效。"))
+                        else:
+                            logger.debug("设备日志: %.240s", line)
+                        continue
+                    if not isinstance(message, dict):
+                        self._publish(ProtocolErrorEvent(message="设备帧必须为 JSON 对象。"))
+                        continue
+                    request = None
+                    if "event" not in message and type(message.get("id")) is int:
+                        request = self._pending.get(message["id"])
+                        if request is None or not request.sent:
+                            logger.debug("忽略迟到或未知响应: %s", message.get("id"))
+                            continue
+                    try:
+                        event = decode_message(message, request.command.type if request else None)
+                    except ProtocolError as exc:
+                        if request:
+                            self._complete(
+                                request, self._failure(request, "invalid_response", str(exc))
+                            )
+                        else:
+                            self._publish(ProtocolErrorEvent(message=str(exc)))
+                        continue
+                    if request:
+                        self._complete(request, event)
+                    else:
+                        self._publish(event)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning("设备通信中断: %s", exc, exc_info=True)
+            self._terminate(DeviceError(code="connection_lost", message=str(exc), source="sdk"))
+
+    def _terminate(self, error: DeviceError | None = None) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if not self._ready.done():
+            self._ready.set_exception(
+                DeviceConnectionError(error.message if error else "连接在握手完成前关闭。")
+            )
+            self._ready.exception()
+        for request in self._pending.values():
+            self._terminal.append(
+                self._failure(
+                    request,
+                    error.code if error else "cancelled",
+                    error.message if error else "连接已关闭，未完成命令已取消。",
+                )
+            )
+            request.done.set()
+        self._pending.clear()
+        self._terminal.append(ConnectionClosedEvent(error=error))
+        self._wake.set()
+        self._cleanup_task = asyncio.create_task(self._cleanup(), name="limivia-cleanup")
+
+    async def _cleanup(self) -> None:
+        for task in self._tasks:
+            task.cancel()
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+        try:
+            await asyncio.wait_for(self._transport.close(), timeout=5)
+        except Exception as exc:
+            logger.exception("设备资源释放失败")
+            for event in self._terminal:
+                if isinstance(event, ConnectionClosedEvent) and event.error is None:
+                    event.error = DeviceError(code="close_failed", message=str(exc), source="sdk")
+
+    async def close(self) -> None:
+        self._terminate()
+        assert self._cleanup_task is not None
+        with CancelScope(shield=True):
+            try:
+                await asyncio.shield(self._cleanup_task)
+            except asyncio.CancelledError:
+                await asyncio.shield(self._cleanup_task)
+                raise

limivia/_exceptions.py

@@ -0,0 +1,25 @@
+class LimiviaError(Exception):
+    """SDK 错误基类。"""
+
+
+class DeviceConnectionError(LimiviaError, ConnectionError):
+    """连接、握手或传输不可用。"""
+
+
+class ProtocolError(LimiviaError, ValueError):
+    """协议帧无效。"""
+
+
+class InvalidCommandError(LimiviaError, ValueError):
+    """命令尚未发送：参数或操作无效。"""
+
+    def __init__(
+        self, message: str, *, code: str = "invalid_argument", request_id: int | None = None
+    ):
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+
+
+class QueueFullError(LimiviaError):
+    """命令尚未入队；等待队列已满。"""

limivia/_models.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Model(BaseModel):
+    """协议数据模型；保留新固件附加的字段。"""
+
+    model_config = ConfigDict(extra="allow", strict=True)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")
+
+    def to_json(self) -> str:
+        return self.model_dump_json()

limivia/commands/__init__.py

@@ -0,0 +1 @@
+