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 を最上位の仕様書とする
