Robo2MQTT Specification Repository
A unified, robot-agnostic, extensible specification for controlling heterogeneous robots over MQTT, with autogenerated client SDKs using AsyncAPI.
⸻
- Purpose of This Repository
The goal of Robo2MQTT is to provide a single unified API for robot control across heterogeneous robotic platforms, such as: • Temi (Android-based) • Pepper (Android-based NAOqi version) • Pepper (Python 2.7 NAOqi) • Toyota HSR (ROS-based) • Furhat (Kotlin-based) • Future robots
Robo2MQTT defines robot capabilities (speech, movement, UI, apps, media, etc.) in a robot-agnostic way, using: • AsyncAPI 2.6.0 as a human-readable and tool-friendly IDL • Modular YAML capability schemas • Robot-specific extensions • Code generation templates (starting with Android/Kotlin)
This repository is the source of truth for the Robo2MQTT interface.
⸻
- Repository Structure
robot2MQTT-spec/ │ ├── core/ │ ├── asyncapi/ │ │ └── robot2mqtt-core.asyncapi.yaml # Main core IDL │ ├── schema/ │ │ ├── common.yaml # Shared definitions (status, battery, robotId) │ │ ├── speech.yaml │ │ ├── movement.yaml │ │ ├── ui.yaml │ │ ├── apps.yaml │ │ ├── media.yaml │ │ └── robot.yaml │ └── README.md # Core API documentation │ ├── generators/ │ ├── android/ │ │ ├── templates/ │ │ │ ├── Capability.kt.hbs │ │ │ ├── Event.kt.hbs │ │ │ ├── RobotClient.kt.hbs │ │ │ └── RobotMQTT.kt.hbs │ │ ├── package.json # AsyncAPI + Handlebars generator config │ │ ├── generator.js # The generator used for Android │ │ └── README.md # Usage instructions │ │ │ ├── ros/ # (future generator) │ ├── python/ # (future generator) │ ├── kotlin/ # (future platform-neutral generator) │ └── dotnet/ # (future generator) │ └── robots/ ├── temi/ │ └── temi2mqtt.asyncapi.yaml # Temi-specific API extension ├── pepper-android/ │ └── pepper-android.asyncapi.yaml ├── pepper-naoqi/ │ └── pepper-naoqi.asyncapi.yaml ├── hsr/ │ └── hsr.asyncapi.yaml └── furhat/ └── furhat.asyncapi.yaml
This structure is final and stable.
- Core API
The core layer defines:
✔ robot lifecycle
✔ speech
✔ movement
✔ UI
✔ app management
✔ media
✔ shared types (status, battery, robotId, etc.)
All capabilities are declared in individual YAML files under core/schema/.
The master API is:
core/asyncapi/robot2mqtt-core.asyncapi.yaml
This file references all capability schemas and defines the core MQTT namespace:
robo2mqtt/{robotId}/...
Robot-specific extensions inherit from it.
⸻
- Robot-Specific Extensions
Each robot extends the core API.
Example:
robots/temi/temi2mqtt.asyncapi.yaml
Temi adds: • Battery events • App launch Settings • (Soon) Temi-specific movement/telepresence events • (Soon) Temi-specific UI extensions • (Soon) Temi-specific WebRTC media extensions
Each extension uses:
extends: ../../core/asyncapi/robot2mqtt-core.asyncapi.yaml
(though Parser JS doesn’t yet support extends, so we currently duplicate core references manually inside components.) 5. Code Generators
Current working generator:
generators/android/
Uses: • NodeJS • @asyncapi/parser • YAML • fs-extra • Handlebars templates
The generator outputs Android Kotlin sources implementing the Robo2MQTT interface (capabilities, event wrappers, MQTT client, etc.)
Example command:
npm run generate -- ../../robots/temi/temi2mqtt.asyncapi.yaml ./output/ This produces a ready-to-import Kotlin module for Temi.
⸻
- Current Status
✔ Repository structure complete
✔ Core schemas mostly stable
✔ Temi extension defined
✔ Android generator installed
✔ Templates prepared
✔ Node environment fixed
✔ AsyncAPI parsing working (2.6.0)
❗ Still facing errors in robot-specific schema referencing: • BatteryStatusMessage resolved • LaunchSettingsCommand still unresolved • Cross-file $ref resolution still needs patching
⸻
- Next Steps
A. Fix YAML references
We need to: • Ensure all message names in components/messages exist across all schemas • Rename references consistently • Avoid referencing non-existent message names
B. Validate with AsyncAPI Playground
We can use: https://studio.asyncapi.com
Upload: • robot2mqtt-core.asyncapi.yaml • temi2mqtt.asyncapi.yaml
C. Add a CI step
Add GitHub Action to validate schemas on push.
D. Android code generation
Once schemas validate cleanly, generation will succeed.
⸻
- Contribution
Create PRs for: • New robot specs • New core capabilities • Generators for ROS / Python / Kotlin / .NET • Documentation improvements
⸻
- License
MIT (suggested)
⸻
- Contact
Maintainer: Mauro Dragone Project: Robo2MQTT Uses: OpenHAB / Home Assistant / Temi / HSR / Furhat / Pepper / ROS / AsyncAPI