localty-system-protocol 0.1.0

Shared protocol definitions for the Localty system

localty-system-protocol

Localty システムにおけるロボット・GUI 間通信プロトコル仕様。

概要

localty-system-protocol は、Localty ロボット制御システムにおける GUI ↔ ロボット間の通信仕様を定義するプロトコルリポジトリです。

本リポジトリは以下を目的とします：

• 通信仕様の単一ソース化
• 実装と仕様の乖離防止
• デバッグおよび拡張時の設計基準の提供

本READMEは Localty 通信仕様の正規ドキュメントであり、実装は本仕様に従って構築される。

構成

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