{"id":50808409,"url":"https://github.com/libretap/mqtt-protocol","last_synced_at":"2026-06-13T03:01:54.050Z","repository":{"id":324120597,"uuid":"1094508369","full_name":"LibreTap/mqtt-protocol","owner":"LibreTap","description":"Official MQTT protocol specification for LibreTap ecosystem. Defines device-authoritative communication between FastAPI backend (TapService) and ESP32 NFC readers (TapReader). Includes schemas, flows, and implementation examples.","archived":false,"fork":false,"pushed_at":"2025-11-13T22:18:16.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-14T00:20:04.041Z","etag":null,"topics":["iot","mqtt","nfc","protocol","specification"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LibreTap.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T19:58:24.000Z","updated_at":"2025-11-13T22:18:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LibreTap/mqtt-protocol","commit_stats":null,"previous_names":["libretap/mqtt-protocol"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/LibreTap/mqtt-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LibreTap%2Fmqtt-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LibreTap%2Fmqtt-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LibreTap%2Fmqtt-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LibreTap%2Fmqtt-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LibreTap","download_url":"https://codeload.github.com/LibreTap/mqtt-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LibreTap%2Fmqtt-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34270417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"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":["iot","mqtt","nfc","protocol","specification"],"created_at":"2026-06-13T03:01:52.693Z","updated_at":"2026-06-13T03:01:54.044Z","avatar_url":"https://github.com/LibreTap.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# LibreTap MQTT Protocol Specification\n\n\u003e **Official communication contract between TapService (FastAPI backend) and TapReader (ESP32 NFC devices)**\n\n[![Protocol Version](https://img.shields.io/badge/version-0.1-blue.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/license-GPL-green.svg)](LICENSE)\n\n## Overview\n\nThis repository defines the MQTT-based protocol for the LibreTap NFC authentication system. It serves as the single source of truth for message formats, topic structures, and communication flows between:\n\n- **TapService**: FastAPI gateway exposing HTTP/WebSocket APIs\n- **TapReader**: ESP32-based NFC readers using PN532 modules\n\n### Key Features\n\n- 🔐 **Device-Authoritative**: Devices own state; service synchronizes\n- ⚡ **Asynchronous**: Non-blocking command/event pattern\n- 🔄 **Idempotent**: Request IDs for deduplication and tracing\n- 📊 **Reliable**: QoS 1 for critical messages, QoS 0 for telemetry\n- 🔒 **Secure**: TLS 1.3, ACLs, and payload validation\n\n## Quick Links\n\n- [📖 Full Specification](MQTT_PROTOCOL_SPEC.md)\n- [�️ Roadmap](ROADMAP.md) - Current v1.0 model \u0026 planned v2.0 challenge-response\n- [�📋 Documentation Index](PROTOCOL_INDEX.md) - Navigation guide\n- [📁 JSON Schemas](schemas/) - Message validation schemas\n- [💡 Examples](examples/) - Implementation examples and flow diagrams\n- [🔄 Changelog](CHANGELOG.md)\n- [💻 Python Implementation](https://github.com/LibreTap/TapService)\n- [🔌 ESP32 Implementation](https://github.com/LibreTap/TapReader)\n\n## Operations\n\n| Operation | Description | Two-Way Flow |\n|-----------|-------------|--------------|\n| **Registration** | Write user credentials to new NFC tag | ✓ |\n| **Authentication** | Verify tag and decrypt user data | ✓ (requires verify) |\n| **Read** | Read raw tag data | ✗ |\n| **Control** | Cancel operations or reset device | ✗ |\n\n## Versioning\n\nThis protocol follows semantic versioning:\n- **Major**: Breaking changes to message format or flow\n- **Minor**: Backward-compatible additions (new event types, fields)\n- **Patch**: Documentation clarifications, examples\n\nCurrent: **v0.1.0**\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibretap%2Fmqtt-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibretap%2Fmqtt-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibretap%2Fmqtt-protocol/lists"}