localty-system-protocol 0.1.0__py3-none-any.whl

localty_protocol/__init__.py

@@ -0,0 +1,47 @@
+from .command import (
+    # formats / sizes
+    HDR_FMT,
+    HDR_SIZE,
+    DRIVE_FMT,
+    DRIVE_SIZE,
+    CMD_DRIVE,
+    CMD_STOP,
+
+    # types
+    Header,
+
+    # functions
+    pack_drive,
+    pack_stop,
+    decode_packet,
+)
+from .telemetry import (
+    ANNOUNCE_PORT,
+    CONTROL_PORT,
+    TELEMETRY_CHANNELS,
+    TELEMETRY_FAST_PORT,
+    TELEMETRY_SLOW_PORT,
+    UDP_PORTS,
+    VIDEO_PORT,
+)
+
+__all__ = [
+    "HDR_FMT",
+    "HDR_SIZE",
+    "DRIVE_FMT",
+    "DRIVE_SIZE",
+    "CMD_DRIVE",
+    "CMD_STOP",
+    "Header",
+    "pack_drive",
+    "pack_stop",
+    "decode_packet",
+    "ANNOUNCE_PORT",
+    "CONTROL_PORT",
+    "TELEMETRY_CHANNELS",
+    "TELEMETRY_FAST_PORT",
+    "TELEMETRY_SLOW_PORT",
+    "UDP_PORTS",
+    "VIDEO_PORT",
+]
+

localty_protocol/command.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+from dataclasses import dataclass
+import struct
+import time
+
+# Header: seq, ts_ms, cmd_id, flags(reserved)
+HDR_FMT = "!IIHH"
+HDR_SIZE = struct.calcsize(HDR_FMT)
+
+DRIVE_FMT = "!ff"
+DRIVE_SIZE = struct.calcsize(DRIVE_FMT)
+
+# Command IDs
+CMD_DRIVE: int = 1
+CMD_STOP: int = 2  # 例
+
+
+def now_ms_u32() -> int:
+    # u32で回す（wrapするがOK）
+    return int(time.time() * 1000) & 0xFFFFFFFF
+
+
+@dataclass(frozen=True)
+class Header:
+    seq: int
+    ts_ms: int
+    cmd_id: int
+    flags: int = 0
+
+    def pack(self) -> bytes:
+        return struct.pack(HDR_FMT, self.seq, self.ts_ms, self.cmd_id, self.flags)
+
+    @staticmethod
+    def unpack(data: bytes) -> "Header":
+        seq, ts_ms, cmd_id, flags = struct.unpack(HDR_FMT, data[:HDR_SIZE])
+        return Header(seq=seq, ts_ms=ts_ms, cmd_id=cmd_id, flags=flags)
+
+
+def pack_drive(seq: int, vx: float, wz: float, ts_ms: int | None = None) -> bytes:
+    if ts_ms is None:
+        ts_ms = now_ms_u32()
+    hdr = Header(seq=seq, ts_ms=ts_ms, cmd_id=CMD_DRIVE, flags=0).pack()
+    body = struct.pack(DRIVE_FMT, float(vx), float(wz))
+    return hdr + body
+
+
+def pack_stop(seq: int, ts_ms: int | None = None) -> bytes:
+    if ts_ms is None:
+        ts_ms = now_ms_u32()
+    hdr = Header(seq=seq, ts_ms=ts_ms, cmd_id=CMD_STOP, flags=0).pack()
+    # stopはボディなしにしてもいい（拡張性のためflagsで表現してもいい）
+    return hdr
+
+
+def decode_packet(data: bytes) -> tuple[Header, bytes]:
+    """
+    戻り値: (Header, body_bytes)
+    """
+    if len(data) < HDR_SIZE:
+        raise ValueError(f"packet too short: {len(data)} < {HDR_SIZE}")
+    hdr = Header.unpack(data)
+    return hdr, data[HDR_SIZE:]

localty_protocol/telemetry.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+ENCODING = "utf-8"
+
+CONTROL_PORT = 5005
+ANNOUNCE_PORT = 5006
+VIDEO_PORT = 5000
+TELEMETRY_FAST_PORT = 5010
+TELEMETRY_SLOW_PORT = 5011
+
+TYPE_HEARTBEAT = "heartbeat"
+TYPE_DISTANCE = "distance"
+TYPE_IMU = "imu"
+TYPE_GPS = "gps"
+TYPE_BATTERY = "battery"
+
+KEY_TYPE = "type"
+KEY_TIMESTAMP = "timestamp"
+KEY_CM = "cm"
+KEY_AX = "ax"
+KEY_AY = "ay"
+KEY_AZ = "az"
+KEY_GX = "gx"
+KEY_GY = "gy"
+KEY_GZ = "gz"
+KEY_FIX = "fix"
+KEY_SAT = "sat"
+KEY_HDOP = "hdop"
+KEY_ALT_M = "alt_m"
+KEY_LAT = "lat"
+KEY_LON = "lon"
+KEY_SPEED = "speed"
+KEY_COURSE = "course"
+KEY_PERCENT = "percent"
+KEY_VOLTAGE = "voltage"
+KEY_DEVICE_ID = "device_id"
+
+
+@dataclass(frozen=True)
+class UdpPort:
+    name: str
+    port: int
+    direction: str
+
+
+@dataclass(frozen=True)
+class TelemetryChannel:
+    name: str
+    port: int
+    message_types: list[str]
+
+
+@dataclass(frozen=True)
+class TelemetryDistance:
+    type: str
+    cm: float
+    timestamp: float
+
+
+@dataclass(frozen=True)
+class TelemetryImu:
+    type: str
+    ax: float
+    ay: float
+    az: float
+    gx: float
+    gy: float
+    gz: float
+    timestamp: float
+
+
+@dataclass(frozen=True)
+class TelemetryGps:
+    type: str
+    fix: int
+    sat: int
+    hdop: float
+    alt_m: float | None
+    lat: float | None
+    lon: float | None
+    speed: float
+    course: float
+    timestamp: float
+
+
+@dataclass(frozen=True)
+class TelemetryBattery:
+    type: str
+    percent: float
+    voltage: float
+    timestamp: float
+    device_id: str
+
+
+UDP_PORTS: list[UdpPort] = [
+    UdpPort("control", CONTROL_PORT, "gui-to-robot"),
+    UdpPort("announce", ANNOUNCE_PORT, "robot-to-gui"),
+    UdpPort("video", VIDEO_PORT, "robot-to-gui"),
+    UdpPort("telemetry_fast", TELEMETRY_FAST_PORT, "robot-to-gui"),
+    UdpPort("telemetry_slow", TELEMETRY_SLOW_PORT, "robot-to-gui"),
+]
+
+TELEMETRY_CHANNELS: list[TelemetryChannel] = [
+    TelemetryChannel("fast", TELEMETRY_FAST_PORT, [TYPE_HEARTBEAT, TYPE_DISTANCE, TYPE_IMU]),
+    TelemetryChannel("slow", TELEMETRY_SLOW_PORT, [TYPE_GPS, TYPE_BATTERY]),
+]
+
+
+def udp_port(name: str) -> int:
+    for item in UDP_PORTS:
+        if item.name == name:
+            return item.port
+    raise KeyError(f"unknown UDP port: {name}")
+
+
+def telemetry_ports() -> list[int]:
+    return [channel.port for channel in TELEMETRY_CHANNELS]
+
+
+def telemetry_channel_for_type(message_type: str) -> TelemetryChannel | None:
+    for channel in TELEMETRY_CHANNELS:
+        if message_type in channel.message_types:
+            return channel
+    return None
+
+
+def telemetry_port_for_type(message_type: str) -> int | None:
+    channel = telemetry_channel_for_type(message_type)
+    return channel.port if channel else None
+
+
+def heartbeat_payload(timestamp: float) -> dict[str, Any]:
+    return {KEY_TYPE: TYPE_HEARTBEAT, KEY_TIMESTAMP: float(timestamp)}
+
+
+def distance_payload(cm: float, timestamp: float) -> dict[str, Any]:
+    return asdict(TelemetryDistance(TYPE_DISTANCE, float(cm), float(timestamp)))
+
+
+def imu_payload(
+    ax: float,
+    ay: float,
+    az: float,
+    gx: float,
+    gy: float,
+    gz: float,
+    timestamp: float,
+) -> dict[str, Any]:
+    return asdict(
+        TelemetryImu(
+            TYPE_IMU,
+            float(ax),
+            float(ay),
+            float(az),
+            float(gx),
+            float(gy),
+            float(gz),
+            float(timestamp),
+        )
+    )
+
+
+def gps_payload(
+    fix: int,
+    sat: int,
+    hdop: float,
+    alt_m: float | None,
+    lat: float | None,
+    lon: float | None,
+    speed: float,
+    course: float,
+    timestamp: float,
+) -> dict[str, Any]:
+    return asdict(
+        TelemetryGps(
+            TYPE_GPS,
+            int(fix),
+            int(sat),
+            float(hdop),
+            None if alt_m is None else float(alt_m),
+            None if lat is None else float(lat),
+            None if lon is None else float(lon),
+            float(speed),
+            float(course),
+            float(timestamp),
+        )
+    )
+
+
+def battery_payload(percent: float, voltage: float, timestamp: float, device_id: str) -> dict[str, Any]:
+    return asdict(
+        TelemetryBattery(TYPE_BATTERY, float(percent), float(voltage), float(timestamp), str(device_id))
+    )
+
+
+def encode_payload(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload).encode(ENCODING)
+
+
+def decode_payload(data: bytes) -> dict[str, Any] | None:
+    try:
+        text = data.decode(ENCODING).strip()
+        if not text:
+            return None
+        payload = json.loads(text)
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None

localty_protocol/version.py

@@ -0,0 +1 @@
+PROTOCOL_VERSION = "0.1.0"

localty_protocol/video.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import struct
+from typing import Dict, List, Optional, Tuple
+
+# header: frame_id(uint32), chunk_idx(uint16), total_chunks(uint16), payload_len(uint16)
+HDR_FMT: str = "!IHHH"
+HDR_SIZE: int = struct.calcsize(HDR_FMT)
+
+# UDPではMTU超えしないよう余裕を見る（LANでも安全側）
+DEFAULT_MTU_SAFE: int = 1200
+DEFAULT_CHUNK_PAYLOAD: int = DEFAULT_MTU_SAFE - HDR_SIZE
+
+
+@dataclass(frozen=True)
+class VideoChunk:
+    frame_id: int
+    chunk_idx: int
+    total_chunks: int
+    payload: bytes
+
+    def encode(self) -> bytes:
+        plen = len(self.payload)
+        header = struct.pack(HDR_FMT, self.frame_id & 0xFFFFFFFF,
+                             self.chunk_idx & 0xFFFF,
+                             self.total_chunks & 0xFFFF,
+                             plen & 0xFFFF)
+        return header + self.payload
+
+    @classmethod
+    def decode(cls, data: bytes) -> "VideoChunk":
+        if len(data) < HDR_SIZE:
+            raise ValueError("VideoChunk too short for header")
+        frame_id, idx, total, plen = struct.unpack(HDR_FMT, data[:HDR_SIZE])
+        payload = data[HDR_SIZE:HDR_SIZE + plen]
+        if len(payload) != plen:
+            raise ValueError("VideoChunk payload length mismatch")
+        return cls(frame_id=frame_id, chunk_idx=idx, total_chunks=total, payload=payload)
+
+
+def split_frame(frame_id: int, frame_bytes: bytes, chunk_payload: int = DEFAULT_CHUNK_PAYLOAD) -> List[VideoChunk]:
+    if chunk_payload <= 0:
+        raise ValueError("chunk_payload must be > 0")
+
+    total = (len(frame_bytes) + chunk_payload - 1) // chunk_payload
+    total = max(1, total)
+
+    chunks: List[VideoChunk] = []
+    for idx in range(total):
+        start = idx * chunk_payload
+        end = min(len(frame_bytes), (idx + 1) * chunk_payload)
+        chunks.append(VideoChunk(frame_id=frame_id, chunk_idx=idx, total_chunks=total, payload=frame_bytes[start:end]))
+    return chunks
+
+
+class FrameReassembler:
+    """Collect VideoChunk and reconstruct a complete frame.
+    Incomplete frames can be dropped by caller based on timeout.
+    """
+    def __init__(self):
+        self._frame_id: Optional[int] = None
+        self._total: int = 0
+        self._chunks: Dict[int, bytes] = {}
+
+    def reset(self) -> None:
+        self._frame_id = None
+        self._total = 0
+        self._chunks = {}
+
+    def push(self, chunk: VideoChunk) -> Tuple[Optional[int], Optional[bytes]]:
+        """Returns (frame_id, frame_bytes) when complete, else (None, None)."""
+        if self._frame_id is None or chunk.frame_id != self._frame_id:
+            # new frame -> reset buffer
+            self._frame_id = chunk.frame_id
+            self._total = chunk.total_chunks
+            self._chunks = {}
+
+        if chunk.total_chunks != self._total:
+            return (None, None)
+
+        self._chunks[chunk.chunk_idx] = chunk.payload
+
+        if len(self._chunks) == self._total:
+            # ensure order
+            payload = b"".join(self._chunks[i] for i in range(self._total) if i in self._chunks)
+            fid = self._frame_id
+            self.reset()
+            return (fid, payload)
+
+        return (None, None)

localty_system_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: localty-system-protocol
+Version: 0.1.0
+Summary: Shared protocol definitions for the Localty system
+Author: Localty Project
+License-Expression: MIT
+Project-URL: Repository, https://github.com/inabako/localty-system-protocol
+Project-URL: Issues, https://github.com/inabako/localty-system-protocol/issues
+Keywords: localty,robotics,protocol,udp,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# localty-system-protocol
+
+Localty システムにおけるロボット・GUI 間通信プロトコル仕様。
+
+
+
+## 概要
+
+`localty-system-protocol` は、Localty ロボット制御システムにおける
+GUI ↔ ロボット間の通信仕様を定義するプロトコルリポジトリです。
+
+本リポジトリは以下を目的とします：
+
+- 通信仕様の単一ソース化
+- 実装と仕様の乖離防止
+- デバッグおよび拡張時の設計基準の提供
+
+
+
+本READMEは Localty 通信仕様の正規ドキュメントであり、実装は本仕様に従って構築される。
+
+
+
+## 構成
+
+```text
+localty_protocol/
+├─ command.py
+├─ telemetry.py
+├─ video.py
+└─ version.py
+
+```
+
+`localty_protocol.telemetry` は、UDPポートとTelemetry JSONの共通定義を管理する。
+
+- `UDP_PORTS`: control / announce / video / telemetry_fast / telemetry_slow の一覧
+- `TELEMETRY_CHANNELS`: FAST / SLOW channelと対応message typeの一覧
+- `*_payload()`: Robot / Simulator が送信する既存JSON形状の生成
+- `encode_payload()` / `decode_payload()`: JSON over UDP の共通encode/decode
+
+## UDPポート
+
+UDPポートの正規定義は `localty_protocol.telemetry.UDP_PORTS` です。
+README、各repoのdocs、Docker設定はこの一覧に合わせます。
+
+| name | direction | port |
+| --- | --- | ---: |
+| `control` | GUI -> robot/simulator | `5005/udp` |
+| `announce` | robot/simulator -> GUI | `5006/udp` |
+| `video` | robot/simulator -> GUI | `5000/udp` |
+| `telemetry_fast` | robot/simulator -> GUI | `5010/udp` |
+| `telemetry_slow` | robot/simulator -> GUI | `5011/udp` |
+
+Telemetry channelの正規定義は `localty_protocol.telemetry.TELEMETRY_CHANNELS` です。
+
+| channel | port | message types |
+| --- | ---: | --- |
+| `fast` | `5010/udp` | `heartbeat`, `distance`, `imu` |
+| `slow` | `5011/udp` | `gps`, `battery` |
+
+SimulatorのFault API `8080/tcp` は、シミュレーター管理用であり共通UDP protocolには含めません。
+
+
+
+## 通信モデル
+
+```
+GUI  ⇄  UDP/TCP  ⇄  Robot
+
+
+```
+
+- GUI: 操作・可視化
+- Robot: 実機制御・センサ管理
+- Protocol: データ構造・コマンド定義
+
+
+
+## パケット構造
+
+| フィールド | 型     | 説明         |
+| ---------- | ------ | ------------ |
+| header     | uint8  | パケット種別 |
+| length     | uint16 | データ長     |
+| payload    | bytes  | 本体データ   |
+| checksum   | uint16 | 整合性検証   |
+
+
+
+
+
+## コマンド一覧
+
+
+
+### Drive Commands
+
+| コマンド | 説明     |
+| -------- | -------- |
+| MOVE     | 移動制御 |
+| STOP     | 停止     |
+| TURN     | 旋回     |
+|          |          |
+
+
+
+### Camera Commands
+
+| コマンド | 説明     |
+| -------- | -------- |
+| START    | 映像開始 |
+| STOP     | 映像停止 |
+|          |          |
+
+
+
+
+
+
+
+
+## バージョニング方針
+
+プロトコルは後方互換性を重視して管理する。
+
+- Major: 非互換変更
+
+- Minor: 互換追加
+
+- Patch: バグ修正
+
+
+
+
+## 開発ポリシー
+
+- 実装と仕様は常に一致させる
+- 仕様変更は必ず Issue / PR で管理
+
+- README を最上位の仕様書とする

localty_system_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+localty_protocol/__init__.py,sha256=WIdbuD-SUZRgBnjkUQsL-GxYUryN630Z0Uj-QxuMf90,736
+localty_protocol/command.py,sha256=RlEIaWpUE1Jnx3NgIrHplp9sFyN7JU-Ec9LddEoDI_o,1713
+localty_protocol/telemetry.py,sha256=c9q3LjJUN1fxDHDANio6uaw8Iizq1gQ-jOhmPFzSxx0,4664
+localty_protocol/version.py,sha256=FMnBSibErrspy-YtiLHU9pQM7UR929eGwEJBSbyt3HA,26
+localty_protocol/video.py,sha256=dPFTnK8Wfe9qXUnGROMp26wpHAiA1cdl-1uuAzA-UW8,3195
+localty_system_protocol-0.1.0.dist-info/licenses/LICENSE,sha256=Rv97knUyBkeGPp24B6hys-7brLIswb7-tY7OHy5rZOQ,1064
+localty_system_protocol-0.1.0.dist-info/METADATA,sha256=tHV-fAUwMxQDM8LwNyRFv21sYx0kY_cmBvL6bC-HF3w,4065
+localty_system_protocol-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+localty_system_protocol-0.1.0.dist-info/top_level.txt,sha256=VRVaYUnp64_MLkMQ2NeRpzJpBOFX3mqpGvlwEOxa7dY,17
+localty_system_protocol-0.1.0.dist-info/RECORD,,

localty_system_protocol-0.1.0.dist-info/WHEEL

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

localty_system_protocol-0.1.0.dist-info/licenses/LICENSE

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

localty_system_protocol-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+localty_protocol