{"id":30632815,"url":"https://github.com/hakoniwalab/hakoniwa-pdu-python","last_synced_at":"2025-08-30T21:10:13.732Z","repository":{"id":302019622,"uuid":"1010945571","full_name":"hakoniwalab/hakoniwa-pdu-python","owner":"hakoniwalab","description":"Hakoniwa PDU Python API: A ROS-inspired communication library providing pub/sub and RPC over SharedMemory or WebSocket","archived":false,"fork":false,"pushed_at":"2025-08-27T06:09:34.000Z","size":367,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T07:17:03.497Z","etag":null,"topics":["hakoniwa","ros","shared-memory","simulation","websocket"],"latest_commit_sha":null,"homepage":"https://hakoniwa-lab.net/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hakoniwalab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T04:38:20.000Z","updated_at":"2025-08-27T06:09:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"13c28110-0b77-48ea-b263-47d2b3729e47","html_url":"https://github.com/hakoniwalab/hakoniwa-pdu-python","commit_stats":null,"previous_names":["hakoniwalab/hakoniwa-pdu-python"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hakoniwalab/hakoniwa-pdu-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakoniwalab%2Fhakoniwa-pdu-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakoniwalab%2Fhakoniwa-pdu-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakoniwalab%2Fhakoniwa-pdu-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakoniwalab%2Fhakoniwa-pdu-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hakoniwalab","download_url":"https://codeload.github.com/hakoniwalab/hakoniwa-pdu-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakoniwalab%2Fhakoniwa-pdu-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272642542,"owners_count":24968908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hakoniwa","ros","shared-memory","simulation","websocket"],"created_at":"2025-08-30T21:05:00.291Z","updated_at":"2025-08-30T21:10:13.715Z","avatar_url":"https://github.com/hakoniwalab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hakoniwa-pdu-python\n\n[![tests](https://github.com/hakoniwalab/hakoniwa-pdu-python/actions/workflows/tests.yml/badge.svg)](https://github.com/hakoniwalab/hakoniwa-pdu-python/actions/workflows/tests.yml)\n\n**Python PDU communication library for the Hakoniwa simulator.**\nProvides a unified transport layer where **RPC** and **Pub/Sub (topics)** run seamlessly over WebSocket.\nFor high-speed use cases, a **Shared Memory (SHM)** backend is also available.\nThe architecture is extensible to **Zenoh**, enabling scalable and distributed systems.\nBinary ⇔ JSON ⇔ Python type conversion is built-in, reducing boilerplate to a minimum.\n\n---\n\n## ✨ Features\n\n* **Unified layer**: RPC and Pub/Sub integrated on top of WebSocket\n* **Automatic type conversion**: safely convert between binary, JSON, and Python types with offset definitions\n* **Transport flexibility**: choose between **WebSocket**, **Shared Memory (SHM)**, and extensible backends such as **Zenoh**\n* **Explicit \u0026 secure connections**: WebSocket URIs (`ws://...`) clearly define communication scope\n* **Event-driven \u0026 polling support**: register handlers or poll buffers as needed\n* **Ready-to-run samples**: minimal examples for `Twist` (topic) and `AddTwoInts` (RPC) included\n\n---\n\n## 📦 Installation\n\n```bash\npip install hakoniwa-pdu\npip show hakoniwa-pdu   # check version\n```\n\n### Environment Variables\n\nSpecify the directory containing `.offset` files for PDU conversion:\n\n```bash\nexport HAKO_BINARY_PATH=/your/path/to/offset\n```\n\nDefault path if unset:\n\n```\n/usr/local/lib/hakoniwa/hako_binary/offset\n```\n\n---\n\n## 🚀 Quick Start (3 commands)\n\n\u003e Example 1: **WebSocket Topic** (`geometry_msgs/Twist` publish → subscribe)\n\n1. **Publisher (server)**\n\n```bash\npython examples/topic/websocket/remote_publisher.py \\\n  --uri ws://localhost:8080 \\\n  --pdu-config examples/pdu_config.json \\\n  --service-config examples/service.json\n```\n\n2. **Subscriber (client)**\n\n```bash\npython examples/topic/websocket/remote_subscriber.py \\\n  --uri ws://localhost:8080 \\\n  --pdu-config examples/pdu_config.json \\\n  --service-config examples/service.json\n```\n\n3. **Output**\n\n```\n[INFO] Received Twist: linear.x=0 angular.z=0\n[INFO] Received Twist: linear.x=1 angular.z=1\n```\n\n---\n\n\u003e Example 2: **WebSocket RPC** (`AddTwoInts` service)\n\n1. **RPC Server**\n\n```bash\npython examples/rpc/websocket/remote_rpc_server.py \\\n  --uri ws://localhost:8080 \\\n  --pdu-config examples/pdu_config.json \\\n  --service-config examples/service.json\n```\n\n2. **RPC Client**\n\n```bash\npython examples/rpc/websocket/remote_rpc_client.py \\\n  --uri ws://localhost:8080 \\\n  --pdu-config examples/pdu_config.json \\\n  --service-config examples/service.json\n```\n\n3. **Output**\n\n```\nResponse: 3\n```\n\n---\n\n## 📡 Event-Driven PDU Handling\n\nServer:\n\n```python\nserver_manager.register_handler_pdu_data(on_pdu)\n\ndef on_pdu(client_id, packet):\n    ...\n```\n\nClient:\n\n```python\nclient_manager.register_handler_pdu_data(on_pdu)\n\ndef on_pdu(packet):\n    ...\n```\n\nPolling via `contains_buffer()` / `get_buffer()` is also available.\n\n---\n\n## 📁 Project Structure\n\n```\nhakoniwa_pdu/\n├── pdu_manager.py\n├── impl/\n│   ├── icommunication_service.py\n│   ├── websocket_communication_service.py\n│   ├── websocket_server_communication_service.py\n│   ├── shm_communication_service.py\n│   ├── pdu_convertor.py\n│   └── hako_binary/\n├── rpc/\n│   ├── ipdu_service_manager.py\n│   ├── protocol_client.py\n│   ├── protocol_server.py\n│   ├── auto_wire.py\n│   ├── remote/\n│   └── shm/\n├── resources/\n│   └── offset/\n└── examples/\n```\n\n---\n\n## 🧭 Class Overview\n\n### PduManager\n\n* Orchestrates PDU buffers and delegates to a transport (`ICommunicationService`).\n* Direct I/O: `declare_pdu_for_read/write` → `flush_pdu_raw_data()` / `read_pdu_raw_data()`.\n* For RPC: extended via `rpc.IPduServiceManager` (handles `register_client`, `start_rpc_service`, etc.).\n\n### Transport Implementations (`impl/`)\n\n* `ICommunicationService` defines the transport API.\n* `WebSocketCommunicationService` / `WebSocketServerCommunicationService`: WebSocket backend (explicit URI-based connection, simple \u0026 secure).\n* `ShmCommunicationService`: high-speed shared memory backend.\n* **Pluggable design**: additional transports (e.g., **Zenoh**) can be integrated without changing application code.\n\n### RPC Layer (`rpc/`)\n\n* `IPduServiceManager` family provides RPC APIs (client/server).\n* `protocol_client.py` / `protocol_server.py`: user-friendly helpers.\n* `auto_wire.py`: auto-loads generated converters.\n* `remote/`: WebSocket managers.\n* `shm/`: SHM managers.\n\n---\n\n## 🧩 Class Diagram (Mermaid)\n\n```mermaid\nclassDiagram\n    class PduManager\n    PduManager --\u003e ICommunicationService : uses\n    PduManager --\u003e CommunicationBuffer\n    PduManager --\u003e PduConvertor\n    PduManager --\u003e PduChannelConfig\n\n    class ICommunicationService {\n        \u003c\u003cinterface\u003e\u003e\n    }\n    class WebSocketCommunicationService\n    class WebSocketServerCommunicationService\n    class ShmCommunicationService\n    ICommunicationService \u003c|.. WebSocketCommunicationService\n    ICommunicationService \u003c|.. WebSocketServerCommunicationService\n    ICommunicationService \u003c|.. ShmCommunicationService\n\n    class IPduServiceManager {\n        \u003c\u003cabstract\u003e\u003e\n    }\n    PduManager \u003c|-- IPduServiceManager\n    class IPduServiceClientManager\n    class IPduServiceServerManager\n    IPduServiceManager \u003c|-- IPduServiceClientManager\n    IPduServiceManager \u003c|-- IPduServiceServerManager\n\n    class RemotePduServiceBaseManager\n    RemotePduServiceBaseManager \u003c|-- RemotePduServiceClientManager\n    RemotePduServiceBaseManager \u003c|-- RemotePduServiceServerManager\n    IPduServiceManager \u003c|-- RemotePduServiceBaseManager\n\n    class ShmPduServiceBaseManager\n    ShmPduServiceBaseManager \u003c|-- ShmPduServiceClientManager\n    ShmPduServiceBaseManager \u003c|-- ShmPduServiceServerManager\n    IPduServiceManager \u003c|-- ShmPduServiceBaseManager\n```\n\n---\n\n## 🔗 Links\n\n* 📘 GitHub: [https://github.com/hakoniwalab/hakoniwa-pdu-python](https://github.com/hakoniwalab/hakoniwa-pdu-python)\n* 🌐 Hakoniwa Lab: [https://hakoniwa-lab.net](https://hakoniwa-lab.net)\n\n---\n\n## 📚 Documentation\n\nFor detailed API usage:\n➡️ [API Reference (api-doc.md)](./api-doc.md)\n\n---\n\n## 📜 License\n\nMIT License — see [LICENSE](./LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakoniwalab%2Fhakoniwa-pdu-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhakoniwalab%2Fhakoniwa-pdu-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakoniwalab%2Fhakoniwa-pdu-python/lists"}