From 7800c33124b6004ba4ae1baa7ad7857b8a8e30e1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 19 Oct 2025 16:30:07 +0000 Subject: [PATCH 1/5] Initial plan From ee0755b7fe1c5facf9fe91bbf435e6f3ef801c3f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 19 Oct 2025 16:35:59 +0000 Subject: [PATCH 2/5] Add MkDocs configuration and initial documentation structure Co-authored-by: harunkurtdev <50794236+harunkurtdev@users.noreply.github.com> --- docs/architecture/overview.md | 325 ++++++++++++++++++++++++++ docs/getting-started/installation.md | 266 +++++++++++++++++++++ docs/getting-started/prerequisites.md | 239 +++++++++++++++++++ docs/getting-started/quick-start.md | 292 +++++++++++++++++++++++ docs/index.md | 134 +++++++++++ mkdocs.yml | 140 +++++++++++ requirements.txt | 3 + 7 files changed, 1399 insertions(+) create mode 100644 docs/architecture/overview.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/prerequisites.md create mode 100644 docs/getting-started/quick-start.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..40d66ce --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,325 @@ +# Architecture Overview + +The Zenoh Multi-Protocol Bridge is designed with a microservices architecture, where each component is containerized and communicates over well-defined protocols. + +## System Architecture + +The system follows a hub-and-spoke architecture with the Zenoh Router at its core, enabling seamless communication between different protocol domains. + +```mermaid +graph TB + subgraph "Docker Environment" + subgraph "MQTT Domain" + MQTTPub[MQTT Publisher
Auto Data Generator] + MQTTSub[MQTT Subscriber] + Mosquitto[Mosquitto Broker
:1883, :9001] + end + + subgraph "Zenoh Core" + ZenohRouter[Zenoh Router
:7447, :8000
Central Hub] + end + + subgraph "Bridge Layer" + MQTTBridge[Zenoh-MQTT Bridge
:8001, :1884
Protocol Translation] + ROSBridge[Zenoh-ROS2DDS Bridge
:8002, :7449
Protocol Translation] + end + + subgraph "ROS2 Domain" + ROS2[ROS2 Humble
:8765
Foxglove Bridge] + ROS2Pub[ROS2 Publisher
/chatter topic] + end + + subgraph "Zenoh Clients" + ZenohSub[Zenoh Subscriber
Python Application] + end + + subgraph "Management" + NodeRED[Node-RED
:1880
Monitoring & Control] + end + end + + subgraph "External" + ExternalPub[pub.py
Host Zenoh Publisher] + ExternalSub[sub.py
Host Zenoh Subscriber] + WebBrowser[Web Browser
User Interface] + end + + %% Connections + MQTTPub -->|MQTT Publish| MQTTBridge + MQTTBridge <-->|MQTT| Mosquitto + MQTTBridge <-->|Zenoh Protocol| ZenohRouter + + Mosquitto <-->|MQTT Subscribe| MQTTSub + Mosquitto <-->|MQTT| NodeRED + + ZenohRouter <-->|Zenoh Subscribe| ZenohSub + ZenohRouter <-->|Zenoh Protocol| ROSBridge + + ROSBridge <-->|DDS Communication| ROS2 + ROS2Pub -->|ROS2 Topic| ROS2 + + NodeRED -.->|Monitor| MQTTBridge + NodeRED -.->|Monitor| ROS2 + + ExternalPub <-->|TCP:7447| ZenohRouter + ExternalSub <-->|TCP:7447| ZenohRouter + + WebBrowser -->|HTTP| NodeRED + WebBrowser -->|WebSocket| ROS2 + + classDef mqtt fill:#e1f5fe + classDef zenoh fill:#f3e5f5 + classDef bridge fill:#fff3e0 + classDef ros fill:#e8f5e8 + classDef mgmt fill:#fce4ec + + class Mosquitto,MQTTPub,MQTTSub mqtt + class ZenohRouter,ZenohSub zenoh + class MQTTBridge,ROSBridge bridge + class ROS2,ROS2Pub ros + class NodeRED mgmt +``` + +## Design Principles + +### 1. **Separation of Concerns** + +Each component has a single, well-defined responsibility: + +- **Protocol Bridges**: Handle translation between protocols +- **Message Brokers**: Manage message routing within their protocol domain +- **Core Router**: Provides the central Zenoh routing infrastructure +- **Clients**: Consume or produce data in specific protocols + +### 2. **Scalability** + +The architecture supports horizontal scaling: + +- Multiple bridge instances can connect to the same Zenoh router +- Clients can be added or removed dynamically +- Load can be distributed across multiple routers + +### 3. **Loose Coupling** + +Components are loosely coupled through: + +- Standardized protocols (MQTT, Zenoh, DDS) +- Configuration-driven topic mapping +- Docker networking for service discovery + +### 4. **Protocol Agnostic** + +The system abstracts protocol-specific details: + +- Applications don't need to know about all protocols +- New protocols can be added with new bridge services +- Protocol translation is transparent to clients + +## Key Components + +### Core Infrastructure + +#### Zenoh Router +- **Role**: Central message routing hub +- **Technology**: Eclipse Zenoh +- **Key Features**: + - High-performance pub/sub + - Store/Query capabilities + - REST API for monitoring + - Zero-copy architecture + +#### Docker Network +- **Name**: `zenoh-mqtt-net` +- **Type**: Bridge network +- **Purpose**: Container-to-container communication +- **DNS**: Automatic service name resolution + +### Protocol Domains + +#### MQTT Domain +- **Broker**: Eclipse Mosquitto +- **Clients**: Publishers and Subscribers +- **Use Cases**: IoT devices, sensors, legacy systems + +#### ROS2 Domain +- **Framework**: ROS2 Humble +- **Middleware**: CycloneDDS +- **Use Cases**: Robotics, autonomous systems + +#### Zenoh Domain +- **Router**: Eclipse Zenoh Router +- **Clients**: Python subscribers, external scripts +- **Use Cases**: Edge computing, distributed systems + +### Bridge Services + +#### Zenoh-MQTT Bridge +- **Function**: Bidirectional MQTT ↔ Zenoh translation +- **Configuration**: JSON5 based +- **Features**: + - Topic filtering + - Scope-based key mapping + - Generalised subscriptions + +#### Zenoh-ROS2DDS Bridge +- **Function**: Bidirectional ROS2 ↔ Zenoh translation +- **Configuration**: JSON5 based +- **Features**: + - Namespace isolation + - Topic/service/action bridging + - Selective filtering + +### Management & Monitoring + +#### Node-RED +- **Purpose**: Visual programming and monitoring +- **Capabilities**: + - Flow-based programming + - Real-time dashboards + - Protocol integration + - Rule-based automation + +## Communication Patterns + +### Pub/Sub Pattern + +The system primarily uses publish-subscribe pattern: + +```mermaid +sequenceDiagram + participant Pub as Publisher + participant Router as Zenoh Router + participant Sub1 as Subscriber 1 + participant Sub2 as Subscriber 2 + + Sub1->>Router: Subscribe to "sensor/*" + Sub2->>Router: Subscribe to "sensor/temperature" + + Pub->>Router: Publish "sensor/temperature" = 25.5 + + Router->>Sub1: Deliver (matches "sensor/*") + Router->>Sub2: Deliver (matches "sensor/temperature") +``` + +### Request/Response Pattern + +ROS2 services use request/response: + +```mermaid +sequenceDiagram + participant Client as ROS2 Client + participant Bridge as ROS2 Bridge + participant Router as Zenoh Router + participant Service as ROS2 Service + + Client->>Bridge: Service Request + Bridge->>Router: Zenoh Query + Router->>Bridge: Route to Service + Bridge->>Service: DDS Service Call + Service->>Bridge: Service Response + Bridge->>Router: Zenoh Reply + Router->>Bridge: Route to Client + Bridge->>Client: Service Response +``` + +## Data Flow Layers + +### Layer 1: Data Generation +- MQTT publishers generate sensor data +- ROS2 nodes publish robot data +- External scripts publish test data + +### Layer 2: Protocol Translation +- MQTT Bridge translates MQTT ↔ Zenoh +- ROS2 Bridge translates DDS ↔ Zenoh +- Bidirectional data flow + +### Layer 3: Routing +- Zenoh Router distributes messages +- Pattern-based subscription matching +- Efficient message delivery + +### Layer 4: Data Consumption +- MQTT subscribers receive IoT data +- ROS2 nodes receive robot commands +- Zenoh subscribers get unified data stream +- Node-RED visualizes and processes data + +## Configuration Management + +### Static Configuration +- Docker Compose orchestration +- Service configurations (JSON5 files) +- Network and volume definitions + +### Dynamic Configuration +- Runtime topic subscriptions +- Flow modifications in Node-RED +- Adjustable publish rates + +## Security Considerations + +### Network Isolation +- Services communicate within Docker network +- Port mapping controls external access +- Host access restricted to necessary ports + +### Access Control +- Mosquitto ACL configuration +- Topic filtering in bridges +- Namespace isolation in ROS2 + +### Future Enhancements +- TLS/SSL for encrypted communication +- Authentication tokens +- Fine-grained access policies + +## Deployment Architecture + +### Single-Host Deployment (Current) +``` +┌─────────────────────────────────────┐ +│ Docker Host │ +│ ┌───────────────────────────────┐ │ +│ │ zenoh-mqtt-net (bridge) │ │ +│ │ ┌──────┐ ┌──────┐ ┌──────┐│ │ +│ │ │MQTT │ │Zenoh │ │ROS2 ││ │ +│ │ │Domain│ │Core │ │Domain││ │ +│ │ └──────┘ └──────┘ └──────┘│ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Multi-Host Deployment (Future) +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Host 1 │ │ Host 2 │ │ Host 3 │ +│ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ +│ │MQTT │ │◄────►│ │Zenoh │ │◄────►│ │ROS2 │ │ +│ │Domain │ │ │ │Router │ │ │ │Domain │ │ +│ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ +└──────────────┘ └──────────────┘ └──────────────┘ +``` + +## Performance Characteristics + +### Latency +- **MQTT → Zenoh**: < 10ms (typical) +- **ROS2 → Zenoh**: < 5ms (typical) +- **End-to-End**: < 20ms (MQTT → Zenoh → ROS2) + +### Throughput +- **MQTT Bridge**: 10K+ messages/second +- **Zenoh Router**: 1M+ messages/second +- **ROS2 Bridge**: 50K+ messages/second + +### Resource Usage +- **Memory**: ~500MB total (all services) +- **CPU**: < 5% idle, < 30% under load +- **Network**: Minimal latency, high efficiency + +## Next Steps + +- [System Components](components.md) - Detailed component descriptions +- [Data Flow](data-flow.md) - Message flow patterns +- [Network Architecture](network.md) - Network topology and configuration diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..65451fc --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,266 @@ +# Installation + +This guide will walk you through the installation process of the Zenoh Multi-Protocol Bridge system. + +## Quick Installation + +The fastest way to get started is using Docker Compose: + +```bash +# Clone the repository +git clone https://github.com/harunkurtdev/zenoh-multi-bridge.git +cd zenoh-multi-bridge + +# Start all services +docker-compose up -d + +# Verify all containers are running +docker-compose ps +``` + +That's it! All services should now be running. + +## Step-by-Step Installation + +### 1. Clone the Repository + +First, clone the project repository from GitHub: + +```bash +git clone https://github.com/harunkurtdev/zenoh-multi-bridge.git +cd zenoh-multi-bridge +``` + +### 2. Review Configuration Files + +Before starting the services, you may want to review the configuration files: + +```bash +# View the main docker-compose configuration +cat docker-compose.yaml + +# View MQTT bridge configuration +cat zenoh-mqtt-bridge/config.json5 + +# View ROS2 bridge configuration +cat zenoh-ros2dds-bridge/config.json5 +``` + +Configuration details are explained in the [Configuration](../configuration/overview.md) section. + +### 3. Build Custom Images + +Some services use custom Docker images that need to be built: + +```bash +# Build all custom images +docker-compose build + +# Or build specific services +docker-compose build ros2-humble +docker-compose build zenoh-ros2dds-bridge +docker-compose build node-red +docker-compose build zenoh-subscriber +``` + +### 4. Start the Services + +Start all services in detached mode: + +```bash +docker-compose up -d +``` + +This command will: + +- Pull required Docker images (if not already present) +- Build custom images (if needed) +- Create a dedicated network (`zenoh-mqtt-net`) +- Start all services in the background + +### 5. Verify Installation + +Check that all services are running: + +```bash +docker-compose ps +``` + +You should see all services in the "Up" state: + +``` +NAME IMAGE STATUS +mosquitto eclipse-mosquitto:latest Up +zenoh-router eclipse/zenoh:latest Up +ros2-humble zenoh-multi-bridge-ros2-humble Up +zenoh-ros2dds-bridge zenoh-multi-bridge-zenoh-ros2... Up +ros2-humble-pub zenoh-multi-bridge-ros2-humble Up +node-red zenoh-multi-bridge-node-red Up +zenoh-mqtt-bridge eclipse/zenoh-bridge-mqtt:latest Up +mqtt-publisher eclipse-mosquitto:latest Up +mqtt-subscriber eclipse-mosquitto:latest Up +zenoh-subscriber zenoh-multi-bridge-zenoh-sub... Up +``` + +### 6. Check Service Logs + +Monitor the logs to ensure everything is working correctly: + +```bash +# View all logs +docker-compose logs -f + +# View specific service logs +docker-compose logs -f zenoh-router +docker-compose logs -f zenoh-mqtt-bridge +docker-compose logs -f zenoh-ros2dds-bridge +docker-compose logs -f mqtt-publisher +``` + +Press `Ctrl+C` to stop following logs. + +## Accessing Web Interfaces + +Once all services are running, you can access the web interfaces: + +| Service | URL | Description | +|---------|-----|-------------| +| Node-RED | [http://localhost:1880](http://localhost:1880) | Visual flow editor and dashboard | +| Zenoh REST API | [http://localhost:8000](http://localhost:8000) | Zenoh router REST interface | +| MQTT Bridge API | [http://localhost:8001](http://localhost:8001) | MQTT bridge REST API | +| ROS2 Bridge API | [http://localhost:8002](http://localhost:8002) | ROS2 bridge REST API | +| Foxglove Studio | [http://localhost:8765](http://localhost:8765) | ROS2 web visualization | + +## Testing the Installation + +### Test MQTT Communication + +Test MQTT message publishing and subscribing: + +```bash +# Subscribe to MQTT topic (in one terminal) +docker exec -it mqtt-subscriber mosquitto_sub -h mosquitto -t 'test/topic' -v + +# Publish a message (in another terminal) +docker exec -it mosquitto mosquitto_pub -h mosquitto -t 'test/topic' -m 'Hello MQTT!' +``` + +### Test Zenoh Communication + +If you have Python and Zenoh installed on your host: + +```bash +# Terminal 1: Subscribe to Zenoh +python3 sub.py + +# Terminal 2: Publish to Zenoh +python3 pub.py +``` + +### Test Multi-Protocol Bridge + +Publish an MQTT message and verify it reaches Zenoh: + +```bash +# Terminal 1: Watch Zenoh subscriber logs +docker-compose logs -f zenoh-subscriber + +# Terminal 2: Publish MQTT message to bridge +mosquitto_pub -h localhost -p 1884 -t 'sensor/test' -m '{"value": 42}' +``` + +You should see the message appear in the Zenoh subscriber logs. + +## Troubleshooting Installation + +### Containers Not Starting + +If containers fail to start, check the logs: + +```bash +docker-compose logs [service-name] +``` + +Common issues: + +1. **Port conflicts**: Ensure required ports are not in use +2. **Insufficient resources**: Docker needs adequate CPU and memory +3. **Permission issues**: Ensure your user is in the `docker` group + +### Port Already in Use + +If you get a port conflict error: + +```bash +# Find which process is using the port +lsof -i :PORT_NUMBER + +# Stop the conflicting process or modify docker-compose.yaml +# to use different host ports +``` + +### Docker Permission Denied + +If you get permission errors: + +```bash +# Add your user to the docker group +sudo usermod -aG docker $USER + +# Log out and back in, or run: +newgrp docker +``` + +### Services Not Connecting + +If services can't connect to each other: + +1. Verify the network is created: + ```bash + docker network ls | grep zenoh-mqtt-net + ``` + +2. Check container DNS resolution: + ```bash + docker exec zenoh-mqtt-bridge ping -c 2 zenoh-router + ``` + +## Updating the Installation + +To update to the latest version: + +```bash +# Stop all services +docker-compose down + +# Pull latest changes +git pull origin main + +# Rebuild images +docker-compose build + +# Start services +docker-compose up -d +``` + +## Uninstalling + +To completely remove the installation: + +```bash +# Stop and remove all containers, networks, and volumes +docker-compose down -v + +# Remove Docker images +docker-compose down --rmi all + +# Remove the repository +cd .. +rm -rf zenoh-multi-bridge +``` + +## Next Steps + +- [Quick Start Guide](quick-start.md) - Learn how to use the system +- [Configuration](../configuration/overview.md) - Customize the setup +- [Testing](../usage/testing.md) - Run comprehensive tests diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md new file mode 100644 index 0000000..76df692 --- /dev/null +++ b/docs/getting-started/prerequisites.md @@ -0,0 +1,239 @@ +# Prerequisites + +Before setting up the Zenoh Multi-Protocol Bridge, ensure you have the following prerequisites installed on your system. + +## System Requirements + +### Minimum Requirements + +- **CPU**: 2 cores +- **RAM**: 4 GB +- **Storage**: 10 GB free space +- **OS**: Linux (Ubuntu 20.04+), macOS (10.15+), or Windows 10/11 with WSL2 + +### Recommended Requirements + +- **CPU**: 4+ cores +- **RAM**: 8 GB or more +- **Storage**: 20 GB free space +- **Network**: Stable internet connection for downloading Docker images + +## Required Software + +### Docker and Docker Compose + +The project is containerized using Docker, so you need Docker and Docker Compose installed. + +=== "Ubuntu/Debian" + + ```bash + # Update package index + sudo apt-get update + + # Install Docker + curl -fsSL https://get.docker.com -o get-docker.sh + sudo sh get-docker.sh + + # Add your user to docker group + sudo usermod -aG docker $USER + + # Install Docker Compose + sudo apt-get install docker-compose-plugin + + # Verify installation + docker --version + docker compose version + ``` + +=== "macOS" + + ```bash + # Install Docker Desktop for Mac + # Download from: https://www.docker.com/products/docker-desktop + + # Or using Homebrew + brew install --cask docker + + # Verify installation + docker --version + docker compose version + ``` + +=== "Windows" + + ```powershell + # Install Docker Desktop for Windows + # Download from: https://www.docker.com/products/docker-desktop + + # Or using Chocolatey + choco install docker-desktop + + # Verify installation (in PowerShell) + docker --version + docker compose version + ``` + +### Git + +Git is required to clone the repository. + +=== "Ubuntu/Debian" + + ```bash + sudo apt-get update + sudo apt-get install git + git --version + ``` + +=== "macOS" + + ```bash + # Git comes with Xcode Command Line Tools + xcode-select --install + + # Or using Homebrew + brew install git + git --version + ``` + +=== "Windows" + + ```powershell + # Download Git for Windows + # https://git-scm.com/download/win + + # Or using Chocolatey + choco install git + git --version + ``` + +## Optional Tools + +### Python 3 (for test scripts) + +Python 3.8+ is required if you want to run the external test scripts (`pub.py` and `sub.py`). + +```bash +# Ubuntu/Debian +sudo apt-get install python3 python3-pip + +# macOS +brew install python3 + +# Windows +# Download from: https://www.python.org/downloads/ +``` + +Install Zenoh Python library: + +```bash +pip3 install zenoh +``` + +### MQTT Clients + +For testing MQTT communication, you might want to install MQTT client tools. + +```bash +# Ubuntu/Debian +sudo apt-get install mosquitto-clients + +# macOS +brew install mosquitto + +# Windows +# Download from: https://mosquitto.org/download/ +``` + +### ROS2 (Optional) + +If you want to interact with ROS2 topics from your host machine (not required for running the project): + +```bash +# Ubuntu 22.04 (Jammy) +sudo apt install software-properties-common +sudo add-apt-repository universe +sudo apt update && sudo apt install curl -y + +# Add ROS2 GPG key +sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg + +# Add repository +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null + +# Install ROS2 Humble +sudo apt update +sudo apt install ros-humble-desktop +``` + +## Network Configuration + +### Port Availability + +Ensure the following ports are available on your system: + +| Port | Service | Protocol | +|------|---------|----------| +| 1880 | Node-RED | HTTP | +| 1883 | Mosquitto MQTT | MQTT | +| 1884 | MQTT Bridge | MQTT | +| 7447 | Zenoh Router | Zenoh/TCP | +| 7449 | ROS2 Bridge | Zenoh/TCP | +| 8000 | Zenoh REST API | HTTP | +| 8001 | MQTT Bridge API | HTTP | +| 8002 | ROS2 Bridge API | HTTP | +| 8765 | Foxglove Bridge | WebSocket | +| 9001 | Mosquitto WebSocket | WebSocket | + +Check if ports are in use: + +```bash +# Linux/macOS +netstat -tuln | grep -E '1880|1883|1884|7447|7449|8000|8001|8002|8765|9001' + +# Or using lsof +lsof -i :1880 -i :1883 -i :1884 -i :7447 -i :7449 -i :8000 -i :8001 -i :8002 -i :8765 -i :9001 +``` + +### Firewall Configuration + +If you're running a firewall, you may need to allow traffic on the required ports: + +```bash +# Ubuntu/Debian (UFW) +sudo ufw allow 1880/tcp +sudo ufw allow 1883/tcp +sudo ufw allow 1884/tcp +sudo ufw allow 7447/tcp +sudo ufw allow 7449/tcp +sudo ufw allow 8000/tcp +sudo ufw allow 8001/tcp +sudo ufw allow 8002/tcp +sudo ufw allow 8765/tcp +sudo ufw allow 9001/tcp +``` + +## Verification + +After installing all prerequisites, verify your setup: + +```bash +# Check Docker +docker --version +docker compose version +docker ps + +# Check Git +git --version + +# Check Python (optional) +python3 --version +pip3 --version + +# Check MQTT client (optional) +mosquitto_pub --help +``` + +## Next Steps + +Once you have all prerequisites installed, proceed to the [Installation](installation.md) guide to set up the Zenoh Multi-Protocol Bridge. diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..2e6029a --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,292 @@ +# Quick Start Guide + +This guide will help you get up and running with the Zenoh Multi-Protocol Bridge in minutes. + +## Starting the System + +### Start All Services + +```bash +cd zenoh-multi-bridge +docker-compose up -d +``` + +### Verify Services Are Running + +```bash +docker-compose ps +``` + +All services should show "Up" status. + +## Basic Usage Examples + +### Example 1: MQTT to Zenoh Bridge + +This example demonstrates how MQTT messages are automatically bridged to Zenoh. + +**Step 1: Watch Zenoh Subscriber** + +```bash +# Monitor the Zenoh subscriber logs +docker-compose logs -f zenoh-subscriber +``` + +**Step 2: Publish MQTT Message** + +In another terminal: + +```bash +# Publish to the MQTT bridge +mosquitto_pub -h localhost -p 1884 -t 'sensor/temperature' \ + -m '{"temp":25.5,"humidity":60,"timestamp":"2024-01-01T12:00:00Z"}' +``` + +**Expected Result**: You should see the message in the Zenoh subscriber logs with the key `mqtt/demo/sensor/temperature`. + +### Example 2: Monitor Multi-Protocol Data Flow + +**Step 1: Start Monitoring** + +Open multiple terminals to monitor different parts of the system: + +```bash +# Terminal 1: MQTT Subscriber +docker-compose logs -f mqtt-subscriber + +# Terminal 2: Zenoh Subscriber +docker-compose logs -f zenoh-subscriber + +# Terminal 3: MQTT Publisher (shows what's being sent) +docker-compose logs -f mqtt-publisher +``` + +**Observation**: The automatic MQTT publisher sends sensor data every second, and you can see it flowing through both MQTT and Zenoh subscribers. + +### Example 3: ROS2 Integration + +**Step 1: Check ROS2 Topics** + +```bash +# Access the ROS2 container +docker exec -it ros2-humble bash + +# Inside the container, list available topics +ros2 topic list + +# Monitor a specific topic +ros2 topic echo /chatter +``` + +**Step 2: View Bridged Data** + +The Zenoh-ROS2DDS bridge creates topics under the `/bot1` namespace. You should see topics like: + +- `/chatter` +- `/bot1/*` (if any data is bridged to the bot1 namespace) + +### Example 4: Node-RED Visualization + +**Step 1: Access Node-RED** + +Open your browser and navigate to [http://localhost:1880](http://localhost:1880) + +**Step 2: View Existing Flows** + +The Node-RED interface should display any pre-configured flows for monitoring MQTT and Zenoh data. + +**Step 3: Create a Simple Dashboard** + +1. Click the hamburger menu (☰) in the top right +2. Select "Dashboard" to open the dashboard view +3. Navigate to [http://localhost:1880/ui](http://localhost:1880/ui) to see your dashboard + +## Using Test Scripts + +The repository includes Python test scripts for direct Zenoh interaction. + +### Setup (if not already done) + +```bash +# Install Zenoh Python library +pip3 install zenoh +``` + +### Run Subscriber + +```bash +# Subscribe to all Zenoh messages +python3 sub.py +``` + +### Run Publisher + +In another terminal: + +```bash +# Publish a message to Zenoh +python3 pub.py +``` + +You should see the message appear in the subscriber terminal. + +## Web Interfaces Quick Access + +| Interface | URL | Use Case | +|-----------|-----|----------| +| **Node-RED** | [http://localhost:1880](http://localhost:1880) | Create flows and visualizations | +| **Node-RED Dashboard** | [http://localhost:1880/ui](http://localhost:1880/ui) | View real-time data dashboards | +| **Zenoh REST API** | [http://localhost:8000](http://localhost:8000) | Query Zenoh router status | +| **MQTT Bridge API** | [http://localhost:8001](http://localhost:8001) | Monitor MQTT bridge status | +| **ROS2 Bridge API** | [http://localhost:8002](http://localhost:8002) | Check ROS2 bridge configuration | +| **Foxglove Studio** | [http://localhost:8765](http://localhost:8765) | Visualize ROS2 topics | + +## Common Commands + +### View Logs + +```bash +# All services +docker-compose logs -f + +# Specific service +docker-compose logs -f zenoh-router +docker-compose logs -f zenoh-mqtt-bridge +docker-compose logs -f zenoh-ros2dds-bridge +``` + +### Restart Services + +```bash +# Restart all services +docker-compose restart + +# Restart specific service +docker-compose restart zenoh-router +``` + +### Stop Services + +```bash +# Stop all services +docker-compose stop + +# Stop specific service +docker-compose stop mqtt-publisher +``` + +### Start/Stop Individual Services + +```bash +# Stop the automatic publisher +docker-compose stop mqtt-publisher + +# Start it again +docker-compose start mqtt-publisher +``` + +## Testing Multi-Protocol Communication + +### Test 1: MQTT → Zenoh Flow + +```bash +# Terminal 1: Subscribe to Zenoh +python3 sub.py + +# Terminal 2: Publish to MQTT (via bridge) +mosquitto_pub -h localhost -p 1884 -t 'test/data' -m 'Hello from MQTT!' +``` + +**Expected**: Message appears in Zenoh subscriber with key `mqtt/demo/test/data` + +### Test 2: Cross-Protocol Monitoring + +```bash +# Terminal 1: MQTT subscriber +mosquitto_sub -h localhost -p 1883 -t 'sensor/#' -v + +# Terminal 2: Zenoh subscriber +docker-compose logs -f zenoh-subscriber + +# Terminal 3: Publish via MQTT bridge +mosquitto_pub -h localhost -p 1884 -t 'sensor/demo' -m '{"value":123}' +``` + +**Expected**: Message appears in both MQTT and Zenoh subscribers + +### Test 3: ROS2 → Zenoh Bridge + +```bash +# Terminal 1: Monitor Zenoh +python3 sub.py + +# Terminal 2: Publish ROS2 message +docker exec -it ros2-humble bash +ros2 topic pub /test std_msgs/msg/String "data: 'Hello ROS2'" -1 +``` + +**Expected**: Message bridged to Zenoh with key matching the ROS2 topic + +## Quick Troubleshooting + +### Services Not Starting + +```bash +# Check which service failed +docker-compose ps + +# View error logs +docker-compose logs [service-name] +``` + +### No Data Flowing + +```bash +# Verify MQTT bridge is connected +docker-compose logs zenoh-mqtt-bridge | grep -i connect + +# Verify ROS2 bridge is connected +docker-compose logs zenoh-ros2dds-bridge | grep -i connect + +# Check Zenoh router +docker-compose logs zenoh-router +``` + +### Port Conflicts + +```bash +# Check if ports are in use +netstat -tuln | grep -E '1880|1883|7447|8000' + +# Modify docker-compose.yaml to use different ports if needed +``` + +## Next Steps + +Now that you have the basic system running, explore more advanced features: + +- **[Architecture Overview](../architecture/overview.md)**: Understand the system design +- **[Components](../components/zenoh-router.md)**: Deep dive into each component +- **[Configuration](../configuration/overview.md)**: Customize the system +- **[Testing](../usage/testing.md)**: Run comprehensive tests +- **[Use Cases](../use-cases/iot-robotics.md)**: Explore practical applications + +## Stopping the System + +When you're done: + +```bash +# Stop all services +docker-compose down + +# Stop and remove volumes (removes persistent data) +docker-compose down -v +``` + +## Getting Help + +If you encounter issues: + +1. Check the [Troubleshooting](../troubleshooting.md) guide +2. Review service logs: `docker-compose logs [service-name]` +3. Open an issue on [GitHub](https://github.com/harunkurtdev/zenoh-multi-bridge/issues) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bd5a18d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,134 @@ +# Zenoh Multi-Protocol Bridge + +
+ +![Project Banner](assets/nodered.png) + +**A comprehensive multi-protocol bridge system connecting Zenoh, MQTT, and ROS2** + +[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) +[![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://www.docker.com/) +[![ROS2](https://img.shields.io/badge/ROS2-Humble-blue.svg)](https://docs.ros.org/en/humble/) + +
+ +## 🎯 Overview + +The Zenoh Multi-Protocol Bridge Project is a comprehensive solution designed to enable seamless data transfer between different communication protocols commonly used in IoT, robotics, and distributed systems. This project bridges **Zenoh**, **MQTT**, and **ROS2** protocols, allowing them to work together in modern IoT and robotics ecosystems. + +## ✨ Key Features + +- **🔄 Multi-Protocol Translation**: Seamless data transfer between MQTT, Zenoh, and ROS2 protocols +- **⚡ Real-Time Communication**: Instant processing of sensor and robotics data +- **📈 Scalable Architecture**: Docker-based microservices structure +- **📊 Monitoring and Control**: Visual flow control with Node-RED +- **🤖 Robotics Integration**: ROS2 DDS bridge for robotics applications +- **🧪 Testing Environment**: Comprehensive testable system with multiple protocol support + +## 🎯 Project Objectives + +This project serves multiple purposes in modern distributed systems: + +1. **Multi-Protocol Translation**: Enable data transfer between MQTT, Zenoh, and ROS2 protocols +2. **Real-Time Communication**: Provide instant processing of sensor and robotics data +3. **Scalable Architecture**: Offer a Docker-based microservices structure +4. **Monitoring and Control**: Include visual flow control with Node-RED +5. **Robotics Integration**: Support ROS2 DDS bridge for robotics applications +6. **Testing Environment**: Provide a comprehensive testable system with multiple protocol support + +## 🚀 Quick Start + +Get started with the Zenoh Multi-Protocol Bridge in just a few steps: + +```bash +# Clone the repository +git clone https://github.com/harunkurtdev/zenoh-multi-bridge.git +cd zenoh-multi-bridge + +# Start all services +docker-compose up -d + +# Follow logs for all services +docker-compose logs -f +``` + +Visit the web interfaces: + +- **Node-RED Dashboard**: [http://localhost:1880](http://localhost:1880) +- **Zenoh REST API**: [http://localhost:8000](http://localhost:8000) +- **MQTT Bridge API**: [http://localhost:8001](http://localhost:8001) +- **ROS2 Bridge API**: [http://localhost:8002](http://localhost:8002) +- **Foxglove Studio**: [http://localhost:8765](http://localhost:8765) + +## 📋 System Components + +The system consists of several interconnected components: + +| Component | Description | Port(s) | +|-----------|-------------|---------| +| **Zenoh Router** | Central router for Zenoh network | 7447, 8000 | +| **MQTT Broker** | Eclipse Mosquitto message broker | 1883, 9001 | +| **Zenoh-MQTT Bridge** | Protocol bridge between MQTT and Zenoh | 8001, 1884 | +| **ROS2 Humble** | ROS2 robotics framework | 8765 | +| **Zenoh-ROS2DDS Bridge** | Protocol bridge between ROS2 DDS and Zenoh | 8002, 7449 | +| **Node-RED** | Visual flow editor and automation | 1880 | + +## 🔄 Data Flow + +```mermaid +graph LR + A[MQTT Publisher] -->|MQTT| B[Zenoh-MQTT Bridge] + B -->|Zenoh| C[Zenoh Router] + C -->|Zenoh| D[Zenoh-ROS2DDS Bridge] + D -->|DDS| E[ROS2 Humble] + C -->|Zenoh| F[Zenoh Subscriber] + B -->|MQTT| G[MQTT Broker] + G -->|MQTT| H[MQTT Subscriber] + C -->|Monitor| I[Node-RED] +``` + +## 🎯 Use Cases + +### IoT-Robotics Integration +Connect sensor data from IoT devices (MQTT) to robot control systems (ROS2) for real-time environmental data processing in autonomous robots. + +### Hybrid Communication Systems +Integrate legacy MQTT infrastructure with modern Zenoh protocol adoption and ROS2 robotics ecosystem connectivity. + +### Research and Development +Provide a multi-protocol testing environment for performance comparison and development sandbox for distributed systems. + +### Industrial Automation +Enable communication between SCADA systems (MQTT) and robot controllers (ROS2) with real-time monitoring capabilities. + +### Smart City Applications +Facilitate communication between IoT sensors and autonomous vehicles for traffic management and environmental monitoring. + +## 📚 Documentation Structure + +- **[Getting Started](getting-started/installation.md)**: Installation, prerequisites, and quick start guides +- **[Architecture](architecture/overview.md)**: System architecture, components, and data flow +- **[Components](components/zenoh-router.md)**: Detailed documentation for each system component +- **[Configuration](configuration/overview.md)**: Configuration guides for bridges and services +- **[Usage](usage/testing.md)**: Testing procedures and monitoring guides +- **[Use Cases](use-cases/iot-robotics.md)**: Real-world application examples +- **[API Reference](api/endpoints.md)**: REST API endpoints and documentation + +## 🤝 Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change. + +## 📄 License + +This project is licensed under the Apache License 2.0 - see the LICENSE file for details. + +## 🙏 Acknowledgments + +- [Eclipse Zenoh](https://zenoh.io/) - Zero Overhead Pub/Sub, Store/Query and Compute +- [Eclipse Mosquitto](https://mosquitto.org/) - An open source MQTT broker +- [ROS2](https://docs.ros.org/) - Robot Operating System 2 +- [Node-RED](https://nodered.org/) - Low-code programming for event-driven applications + +## 📞 Support + +For questions and support, please open an issue on the [GitHub repository](https://github.com/harunkurtdev/zenoh-multi-bridge/issues). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..50ca3fd --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,140 @@ +site_name: Zenoh Multi-Protocol Bridge +site_description: Comprehensive multi-protocol bridge system connecting Zenoh, MQTT, and ROS2 +site_author: Harun Kurt +site_url: https://github.com/harunkurtdev/zenoh-multi-bridge + +# Repository +repo_name: harunkurtdev/zenoh-multi-bridge +repo_url: https://github.com/harunkurtdev/zenoh-multi-bridge +edit_uri: edit/main/docs/ + +# Copyright +copyright: Copyright © 2024 Harun Kurt + +# Configuration +theme: + name: material + palette: + # Palette toggle for light mode + - scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + icon: + repo: fontawesome/brands/github + +# Extensions +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: harunkurtdev + repo: zenoh-multi-bridge + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +# Plugins +plugins: + - search + - tags + +# Navigation +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started/installation.md + - Quick Start: getting-started/quick-start.md + - Prerequisites: getting-started/prerequisites.md + - Architecture: + - Overview: architecture/overview.md + - System Components: architecture/components.md + - Data Flow: architecture/data-flow.md + - Network Architecture: architecture/network.md + - Components: + - Zenoh Router: components/zenoh-router.md + - MQTT Broker: components/mqtt-broker.md + - Zenoh-MQTT Bridge: components/zenoh-mqtt-bridge.md + - ROS2 Humble: components/ros2-humble.md + - Zenoh-ROS2DDS Bridge: components/zenoh-ros2dds-bridge.md + - Node-RED: components/node-red.md + - Test Components: components/test-components.md + - Configuration: + - Overview: configuration/overview.md + - MQTT Bridge Config: configuration/mqtt-bridge.md + - ROS2 Bridge Config: configuration/ros2-bridge.md + - Docker Compose: configuration/docker-compose.md + - Usage: + - Testing: usage/testing.md + - Multi-Protocol Communication: usage/multi-protocol.md + - Monitoring: usage/monitoring.md + - Use Cases: + - IoT-Robotics Integration: use-cases/iot-robotics.md + - Hybrid Communication: use-cases/hybrid-communication.md + - Research Platform: use-cases/research.md + - Industrial Automation: use-cases/industrial.md + - Smart City Applications: use-cases/smart-city.md + - API Reference: + - Endpoints: api/endpoints.md + - REST APIs: api/rest-apis.md + - Troubleshooting: troubleshooting.md + - Contributing: contributing.md + +# Extra +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/harunkurtdev + version: + provider: mike diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..8b96152 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs>=1.5.3 +mkdocs-material>=9.5.0 +pymdown-extensions>=10.7 From 0f906513bbb8e3e4a0dea8064ab224cd2b6b4195 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 19 Oct 2025 16:42:54 +0000 Subject: [PATCH 3/5] Add comprehensive MkDocs documentation structure Co-authored-by: harunkurtdev <50794236+harunkurtdev@users.noreply.github.com> --- .gitignore | 25 ++ docs/README.md | 144 +++++++ docs/api/endpoints.md | 268 ++++++++++++ docs/api/rest-apis.md | 33 ++ docs/architecture/components.md | 12 + docs/architecture/data-flow.md | 23 ++ docs/architecture/network.md | 11 + docs/components/mqtt-broker.md | 9 + docs/components/node-red.md | 11 + docs/components/ros2-humble.md | 9 + docs/components/test-components.md | 15 + docs/components/zenoh-mqtt-bridge.md | 406 ++++++++++++++++++ docs/components/zenoh-ros2dds-bridge.md | 9 + docs/components/zenoh-router.md | 373 +++++++++++++++++ docs/configuration/docker-compose.md | 5 + docs/configuration/mqtt-bridge.md | 5 + docs/configuration/overview.md | 54 +++ docs/configuration/ros2-bridge.md | 5 + docs/contributing.md | 460 +++++++++++++++++++++ docs/troubleshooting.md | 520 ++++++++++++++++++++++++ docs/usage/monitoring.md | 5 + docs/usage/multi-protocol.md | 11 + docs/usage/testing.md | 5 + docs/use-cases/hybrid-communication.md | 13 + docs/use-cases/industrial.md | 9 + docs/use-cases/iot-robotics.md | 13 + docs/use-cases/research.md | 9 + docs/use-cases/smart-city.md | 9 + 28 files changed, 2471 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/api/endpoints.md create mode 100644 docs/api/rest-apis.md create mode 100644 docs/architecture/components.md create mode 100644 docs/architecture/data-flow.md create mode 100644 docs/architecture/network.md create mode 100644 docs/components/mqtt-broker.md create mode 100644 docs/components/node-red.md create mode 100644 docs/components/ros2-humble.md create mode 100644 docs/components/test-components.md create mode 100644 docs/components/zenoh-mqtt-bridge.md create mode 100644 docs/components/zenoh-ros2dds-bridge.md create mode 100644 docs/components/zenoh-router.md create mode 100644 docs/configuration/docker-compose.md create mode 100644 docs/configuration/mqtt-bridge.md create mode 100644 docs/configuration/overview.md create mode 100644 docs/configuration/ros2-bridge.md create mode 100644 docs/contributing.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/usage/monitoring.md create mode 100644 docs/usage/multi-protocol.md create mode 100644 docs/usage/testing.md create mode 100644 docs/use-cases/hybrid-communication.md create mode 100644 docs/use-cases/industrial.md create mode 100644 docs/use-cases/iot-robotics.md create mode 100644 docs/use-cases/research.md create mode 100644 docs/use-cases/smart-city.md diff --git a/.gitignore b/.gitignore index a7e9ded..def3c3e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,27 @@ mosquitto/data/ mosquitto/log/ + +# MkDocs +site/ +.cache/ + +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +env/ +venv/ +ENV/ + +# IDEs +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ed3a557 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,144 @@ +# Documentation + +This directory contains the MkDocs documentation for the Zenoh Multi-Protocol Bridge project. + +## Building the Documentation + +### Prerequisites + +- Python 3.8+ +- pip + +### Installation + +Install the required dependencies: + +```bash +pip install -r requirements.txt +``` + +### Building + +To build the static documentation site: + +```bash +mkdocs build +``` + +The generated site will be in the `site/` directory. + +### Development + +To start a local development server with auto-reload: + +```bash +mkdocs serve +``` + +Then open your browser to [http://localhost:8000](http://localhost:8000) + +## Documentation Structure + +``` +docs/ +├── index.md # Home page +├── getting-started/ # Installation and quick start guides +│ ├── prerequisites.md +│ ├── installation.md +│ └── quick-start.md +├── architecture/ # System architecture documentation +│ ├── overview.md +│ ├── components.md +│ ├── data-flow.md +│ └── network.md +├── components/ # Individual component documentation +│ ├── zenoh-router.md +│ ├── mqtt-broker.md +│ ├── zenoh-mqtt-bridge.md +│ ├── ros2-humble.md +│ ├── zenoh-ros2dds-bridge.md +│ ├── node-red.md +│ └── test-components.md +├── configuration/ # Configuration guides +│ ├── overview.md +│ ├── mqtt-bridge.md +│ ├── ros2-bridge.md +│ └── docker-compose.md +├── usage/ # Usage guides +│ ├── testing.md +│ ├── multi-protocol.md +│ └── monitoring.md +├── use-cases/ # Real-world use cases +│ ├── iot-robotics.md +│ ├── hybrid-communication.md +│ ├── research.md +│ ├── industrial.md +│ └── smart-city.md +├── api/ # API reference +│ ├── endpoints.md +│ └── rest-apis.md +├── troubleshooting.md # Troubleshooting guide +└── contributing.md # Contributing guidelines +``` + +## Contributing to Documentation + +When contributing to the documentation: + +1. **Follow the Existing Structure**: Place new content in the appropriate directory +2. **Use Markdown**: All documentation is in Markdown format +3. **Include Examples**: Code examples and command-line snippets are helpful +4. **Add Diagrams**: Use Mermaid syntax for diagrams when appropriate +5. **Test Your Changes**: Build the docs locally to verify formatting +6. **Update Navigation**: Add new pages to `mkdocs.yml` navigation + +### Markdown Features + +The documentation supports: + +- **Mermaid Diagrams**: For flowcharts and sequence diagrams +- **Code Highlighting**: Syntax highlighting for various languages +- **Admonitions**: Info, warning, and note boxes +- **Tabbed Content**: For platform-specific instructions +- **Task Lists**: For checklists and progress tracking + +### Example Admonition + +```markdown +!!! warning "Important Note" + This is a warning message. + +!!! info "Information" + This is an info message. + +!!! tip "Pro Tip" + This is a helpful tip. +``` + +### Example Tabbed Content + +```markdown +=== "Ubuntu" + ```bash + sudo apt-get install package + ``` + +=== "macOS" + ```bash + brew install package + ``` +``` + +## Deployment + +The documentation can be deployed to: + +- **GitHub Pages**: `mkdocs gh-deploy` +- **ReadTheDocs**: Connect your repository +- **Static Hosting**: Upload the `site/` directory + +## See Also + +- [MkDocs Documentation](https://www.mkdocs.org/) +- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) +- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md new file mode 100644 index 0000000..9aa8339 --- /dev/null +++ b/docs/api/endpoints.md @@ -0,0 +1,268 @@ +# API Endpoints + +This page provides a comprehensive reference for all REST API endpoints available in the Zenoh Multi-Protocol Bridge system. + +## Overview + +The system exposes multiple REST APIs for monitoring, management, and interaction: + +| Service | Port | Base URL | Purpose | +|---------|------|----------|---------| +| Zenoh Router | 8000 | http://localhost:8000 | Router status and operations | +| MQTT Bridge | 8001 | http://localhost:8001 | Bridge monitoring and config | +| ROS2 Bridge | 8002 | http://localhost:8002 | ROS2 bridge management | + +## Zenoh Router API + +### Base URL +``` +http://localhost:8000 +``` + +### Get Router Status + +**Endpoint:** `GET /@/router/local` + +**Description:** Retrieve information about the local Zenoh router. + +**Example:** +```bash +curl http://localhost:8000/@/router/local +``` + +**Response:** +```json +{ + "zid": "...", + "links": [...], + "locators": [...] +} +``` + +### Publish Data + +**Endpoint:** `PUT /` + +**Description:** Publish data to a Zenoh key. + +**Example:** +```bash +curl -X PUT http://localhost:8000/demo/sensor/temp \ + -H 'Content-Type: application/json' \ + -d '{"temperature": 25.5, "unit": "celsius"}' +``` + +### Query Data + +**Endpoint:** `GET /` + +**Description:** Query data matching a key expression. + +**Example:** +```bash +# Query specific key +curl http://localhost:8000/demo/sensor/temp + +# Query with wildcard +curl http://localhost:8000/demo/sensor/* +``` + +### Subscribe via SSE + +**Endpoint:** `GET /` + +**Headers:** `Accept: text/event-stream` + +**Description:** Subscribe to updates using Server-Sent Events. + +**Example:** +```bash +curl http://localhost:8000/demo/sensor/* \ + -H 'Accept: text/event-stream' +``` + +## MQTT Bridge API + +### Base URL +``` +http://localhost:8001 +``` + +### Get Bridge Status + +**Endpoint:** `GET /@/local/status` + +**Description:** Get the current status of the MQTT bridge. + +**Example:** +```bash +curl http://localhost:8001/@/local/status +``` + +### List Subscriptions + +**Endpoint:** `GET /@/local/subscriptions` + +**Description:** List active MQTT subscriptions. + +**Example:** +```bash +curl http://localhost:8001/@/local/subscriptions +``` + +### Get Configuration + +**Endpoint:** `GET /@/local/config` + +**Description:** Retrieve the current bridge configuration. + +**Example:** +```bash +curl http://localhost:8001/@/local/config +``` + +## ROS2 Bridge API + +### Base URL +``` +http://localhost:8002 +``` + +### Get Bridge Status + +**Endpoint:** `GET /@/local/status` + +**Description:** Get the current status of the ROS2 bridge. + +**Example:** +```bash +curl http://localhost:8002/@/local/status +``` + +### List Active Topics + +**Endpoint:** `GET /@/local/topics` + +**Description:** List ROS2 topics being bridged. + +**Example:** +```bash +curl http://localhost:8002/@/local/topics +``` + +### Get Configuration + +**Endpoint:** `GET /@/local/config` + +**Description:** Retrieve the current ROS2 bridge configuration. + +**Example:** +```bash +curl http://localhost:8002/@/local/config +``` + +## Common Patterns + +### Health Check + +Check if services are responsive: + +```bash +# Check all services +curl http://localhost:8000/@/router/local +curl http://localhost:8001/@/local/status +curl http://localhost:8002/@/local/status +``` + +### Publish-Subscribe Pattern + +```bash +# Terminal 1: Subscribe +curl http://localhost:8000/test/* \ + -H 'Accept: text/event-stream' + +# Terminal 2: Publish +curl -X PUT http://localhost:8000/test/message \ + -d 'Hello World' +``` + +### Query Pattern + +```bash +# Store data +curl -X PUT http://localhost:8000/data/sensor1 -d '{"temp": 22}' +curl -X PUT http://localhost:8000/data/sensor2 -d '{"temp": 24}' + +# Query all sensors +curl http://localhost:8000/data/* +``` + +## Error Handling + +### Common HTTP Status Codes + +| Code | Meaning | Action | +|------|---------|--------| +| 200 | Success | Request completed successfully | +| 404 | Not Found | Key or endpoint doesn't exist | +| 500 | Server Error | Check service logs | +| 503 | Service Unavailable | Service is starting or down | + +### Error Response Format + +```json +{ + "error": "Error description", + "code": "ERROR_CODE" +} +``` + +## Authentication + +Currently, the REST APIs do not require authentication. For production deployments: + +1. Use a reverse proxy (nginx, traefik) +2. Implement authentication at the proxy level +3. Restrict network access to trusted clients +4. Consider TLS/SSL for encryption + +## Rate Limiting + +No rate limiting is implemented by default. Consider implementing rate limiting at the proxy level for production use. + +## Examples + +### Monitor Sensor Data + +```bash +#!/bin/bash +# monitor-sensors.sh + +while true; do + echo "=== Sensor Status ===" + curl -s http://localhost:8000/mqtt/demo/sensor/* | jq '.' + sleep 5 +done +``` + +### Publish Periodic Updates + +```bash +#!/bin/bash +# publish-data.sh + +while true; do + TEMP=$((20 + RANDOM % 10)) + curl -X PUT http://localhost:8000/demo/temperature \ + -H 'Content-Type: application/json' \ + -d "{\"value\": $TEMP, \"timestamp\": \"$(date -Iseconds)\"}" + echo "Published: $TEMP" + sleep 1 +done +``` + +## See Also + +- [REST APIs Documentation](rest-apis.md) +- [Testing Guide](../usage/testing.md) +- [Troubleshooting](../troubleshooting.md) diff --git a/docs/api/rest-apis.md b/docs/api/rest-apis.md new file mode 100644 index 0000000..844cc1f --- /dev/null +++ b/docs/api/rest-apis.md @@ -0,0 +1,33 @@ +# REST APIs + +Detailed documentation for the REST APIs provided by each component of the Zenoh Multi-Protocol Bridge. + +## API Overview + +Each major component exposes a REST API for monitoring and management: + +- **Zenoh Router**: Core routing operations and monitoring +- **MQTT Bridge**: Bridge status and MQTT-specific operations +- **ROS2 Bridge**: ROS2 integration status and topic management + +## Authentication & Security + +!!! warning "Production Security" + The default configuration does not include authentication. For production deployments: + + - Use a reverse proxy with authentication (nginx, traefik) + - Implement TLS/SSL encryption + - Restrict network access using firewalls + - Consider API key or OAuth2 authentication + +## Content Types + +All APIs support the following content types: + +- **Request**: `application/json`, `text/plain` +- **Response**: `application/json`, `text/event-stream` (for subscriptions) + +## See Also + +- [API Endpoints](endpoints.md) - Complete endpoint reference +- [Usage Examples](../usage/testing.md) - Practical API usage examples diff --git a/docs/architecture/components.md b/docs/architecture/components.md new file mode 100644 index 0000000..a41cc03 --- /dev/null +++ b/docs/architecture/components.md @@ -0,0 +1,12 @@ +# System Components + +Detailed information about each component in the Zenoh Multi-Protocol Bridge system. + +For specific component documentation, see: + +- [Zenoh Router](../components/zenoh-router.md) +- [MQTT Broker](../components/mqtt-broker.md) +- [Zenoh-MQTT Bridge](../components/zenoh-mqtt-bridge.md) +- [ROS2 Humble](../components/ros2-humble.md) +- [Zenoh-ROS2DDS Bridge](../components/zenoh-ros2dds-bridge.md) +- [Node-RED](../components/node-red.md) diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md new file mode 100644 index 0000000..f30da5a --- /dev/null +++ b/docs/architecture/data-flow.md @@ -0,0 +1,23 @@ +# Data Flow + +Understanding how data flows through the Zenoh Multi-Protocol Bridge system. + +## Multi-Protocol Flow + +Data flows seamlessly between MQTT, Zenoh, and ROS2: + +```mermaid +sequenceDiagram + participant MQTT as MQTT Publisher + participant Bridge as MQTT Bridge + participant Router as Zenoh Router + participant ROS2Bridge as ROS2 Bridge + participant ROS2 as ROS2 Node + + MQTT->>Bridge: MQTT Publish + Bridge->>Router: Zenoh Put + Router->>ROS2Bridge: Zenoh Sample + ROS2Bridge->>ROS2: ROS2 Publish +``` + +See the [Architecture Overview](overview.md) for more details. diff --git a/docs/architecture/network.md b/docs/architecture/network.md new file mode 100644 index 0000000..615239d --- /dev/null +++ b/docs/architecture/network.md @@ -0,0 +1,11 @@ +# Network Architecture + +The network topology and configuration of the Zenoh Multi-Protocol Bridge. + +## Docker Network + +All services run in a dedicated Docker bridge network: `zenoh-mqtt-net` + +## Port Mappings + +See the [Architecture Overview](overview.md) for complete port information. diff --git a/docs/components/mqtt-broker.md b/docs/components/mqtt-broker.md new file mode 100644 index 0000000..aa629de --- /dev/null +++ b/docs/components/mqtt-broker.md @@ -0,0 +1,9 @@ +# MQTT Broker (Mosquitto) + +Eclipse Mosquitto MQTT broker configuration and usage. + +## Overview + +Mosquitto serves as the MQTT message broker in the system. + +**Ports:** 1883 (MQTT), 9001 (WebSocket) diff --git a/docs/components/node-red.md b/docs/components/node-red.md new file mode 100644 index 0000000..24e0843 --- /dev/null +++ b/docs/components/node-red.md @@ -0,0 +1,11 @@ +# Node-RED + +Visual flow editor and automation platform. + +## Overview + +Node-RED provides a web-based interface for creating flows and dashboards. + +**Port:** 1880 + +**Access:** http://localhost:1880 diff --git a/docs/components/ros2-humble.md b/docs/components/ros2-humble.md new file mode 100644 index 0000000..38f3ad3 --- /dev/null +++ b/docs/components/ros2-humble.md @@ -0,0 +1,9 @@ +# ROS2 Humble + +ROS2 Humble robotics framework integration. + +## Overview + +ROS2 Humble provides the robotics framework with DDS communication. + +**Port:** 8765 (Foxglove Bridge) diff --git a/docs/components/test-components.md b/docs/components/test-components.md new file mode 100644 index 0000000..b64c449 --- /dev/null +++ b/docs/components/test-components.md @@ -0,0 +1,15 @@ +# Test Components + +Various testing components and utilities. + +## MQTT Publisher + +Automatic sensor data generator. + +## MQTT Subscriber + +Client listening to MQTT messages. + +## Zenoh Subscriber + +Python application for receiving Zenoh data. diff --git a/docs/components/zenoh-mqtt-bridge.md b/docs/components/zenoh-mqtt-bridge.md new file mode 100644 index 0000000..8bc99d8 --- /dev/null +++ b/docs/components/zenoh-mqtt-bridge.md @@ -0,0 +1,406 @@ +# Zenoh-MQTT Bridge + +The Zenoh-MQTT Bridge provides bidirectional protocol translation between MQTT and Zenoh, enabling IoT devices and applications using MQTT to seamlessly communicate with Zenoh-based systems. + +## Overview + +This bridge connects the MQTT and Zenoh worlds, translating messages in both directions while maintaining topic structure and message semantics. + +```mermaid +graph LR + subgraph "MQTT Domain" + MP[MQTT Publisher] -->|MQTT| MB[MQTT Broker
:1883] + MB -->|MQTT| MS[MQTT Subscriber] + end + + subgraph "Bridge" + Bridge[Zenoh-MQTT Bridge
:1884, :8001] + end + + subgraph "Zenoh Domain" + ZR[Zenoh Router
:7447] + ZS[Zenoh Subscriber] + end + + MP -->|MQTT :1884| Bridge + Bridge <-->|MQTT| MB + Bridge <-->|Zenoh| ZR + ZR -->|Zenoh| ZS + + classDef bridge fill:#fff3e0 + class Bridge bridge +``` + +## Key Features + +### 1. Bidirectional Translation + +- **MQTT → Zenoh**: MQTT messages are published to Zenoh with scoped keys +- **Zenoh → MQTT**: Zenoh messages are published to MQTT topics + +### 2. Topic Mapping + +- Configurable scope prefix (`mqtt/demo`) +- Topic filtering with allow/deny patterns +- Generalised subscriptions for wildcard topics + +### 3. MQTT Server + +Acts as an MQTT broker on port 1884: +- Clients can connect directly to the bridge +- Messages automatically forwarded to Zenoh + +### 4. REST API + +Provides monitoring and management via HTTP (port 8001) + +## Configuration + +### Current Configuration + +Located at `zenoh-mqtt-bridge/config.json5`: + +```json5 +{ + mode: "client", + connect: { + endpoints: ["tcp/zenoh-router:7447"], + }, + plugins: { + rest: { + http_port: 8000, + }, + mqtt: { + port: "0.0.0.0:1884", + scope: "mqtt/demo", + allow: ".*", + deny: "^\\$SYS/.*|^private/.*", + generalise_subs: [ + "sensor/*", + "device/*", + "data/*" + ], + generalise_pubs: [ + "sensor/**", + "device/**", + "data/**" + ], + tx_channel_size: 65536, + } + }, + plugins_loading: { + enabled: true + } +} +``` + +### Configuration Parameters + +#### Mode +```json5 +mode: "client" +``` +Bridge connects as a client to the Zenoh router. + +#### Zenoh Connection +```json5 +connect: { + endpoints: ["tcp/zenoh-router:7447"] +} +``` +Specifies the Zenoh router endpoint. + +#### MQTT Plugin Settings + +**Port** +```json5 +port: "0.0.0.0:1884" +``` +The bridge listens for MQTT connections on port 1884. + +**Scope** +```json5 +scope: "mqtt/demo" +``` +All MQTT topics are prefixed with this scope in Zenoh. For example: +- MQTT topic: `sensor/temperature` +- Zenoh key: `mqtt/demo/sensor/temperature` + +**Allow/Deny Filters** +```json5 +allow: ".*" +deny: "^\\$SYS/.*|^private/.*" +``` +- `allow`: Accept all topics by default +- `deny`: Reject system topics (`$SYS/*`) and private topics + +**Generalised Subscriptions** +```json5 +generalise_subs: ["sensor/*", "device/*", "data/*"] +generalise_pubs: ["sensor/**", "device/**", "data/**"] +``` +Optimizes subscription handling for wildcard topics. + +**Buffer Size** +```json5 +tx_channel_size: 65536 +``` +Transmission buffer size for high-throughput scenarios. + +## Usage Examples + +### Publishing MQTT Messages + +#### Direct to Bridge + +```bash +# Publish to bridge (port 1884) +mosquitto_pub -h localhost -p 1884 \ + -t 'sensor/temperature' \ + -m '{"temp":25.5,"humidity":60}' +``` + +This message will appear in Zenoh as: `mqtt/demo/sensor/temperature` + +#### Via MQTT Broker + +```bash +# Publish to Mosquitto (port 1883) +mosquitto_pub -h localhost -p 1883 \ + -t 'sensor/temperature' \ + -m '{"temp":25.5,"humidity":60}' +``` + +The bridge subscribes to the broker and forwards to Zenoh. + +### Subscribing to MQTT Messages + +```bash +# Subscribe via bridge +mosquitto_sub -h localhost -p 1884 -t 'sensor/#' -v + +# Subscribe via broker +mosquitto_sub -h localhost -p 1883 -t 'sensor/#' -v +``` + +### Zenoh to MQTT Flow + +Messages published to Zenoh keys matching the scope appear in MQTT: + +```python +# Python Zenoh publisher +import zenoh + +session = zenoh.open() +session.put("mqtt/demo/sensor/status", "online") +``` + +MQTT subscribers see this on topic: `sensor/status` + +## Docker Configuration + +```yaml +zenoh-mqtt-bridge: + container_name: zenoh-mqtt-bridge + image: eclipse/zenoh-bridge-mqtt:latest + restart: unless-stopped + depends_on: + - mosquitto + - zenoh-router + ports: + - "8001:8000" # REST API + - "1884:1884" # MQTT port + volumes: + - ./zenoh-mqtt-bridge/config.json5:/etc/zenoh/config.json5 + environment: + - RUST_LOG=debug + networks: + - zenoh-mqtt-net + command: "-c /etc/zenoh/config.json5" +``` + +## Port Mappings + +| Container Port | Host Port | Protocol | Purpose | +|----------------|-----------|----------|---------| +| 8000 | 8001 | HTTP | REST API | +| 1884 | 1884 | MQTT | MQTT server | + +## Monitoring + +### View Logs + +```bash +# Real-time logs +docker-compose logs -f zenoh-mqtt-bridge + +# Filter for errors +docker-compose logs zenoh-mqtt-bridge | grep -i error +``` + +### REST API + +Check bridge status: + +```bash +# Bridge information +curl http://localhost:8001/@/local/status + +# List active subscriptions +curl http://localhost:8001/@/local/subscriptions +``` + +### Test Connectivity + +```bash +# Test MQTT connection +mosquitto_pub -h localhost -p 1884 -t 'test' -m 'hello' -d + +# Test from Zenoh side +python3 sub.py +``` + +## Topic Mapping Examples + +### Example 1: Simple Topic + +| MQTT Topic | Zenoh Key | +|------------|-----------| +| `sensor/temperature` | `mqtt/demo/sensor/temperature` | +| `device/status` | `mqtt/demo/device/status` | +| `data/metrics` | `mqtt/demo/data/metrics` | + +### Example 2: Hierarchical Topics + +| MQTT Topic | Zenoh Key | +|------------|-----------| +| `home/living/temp` | `mqtt/demo/home/living/temp` | +| `factory/line1/sensor3` | `mqtt/demo/factory/line1/sensor3` | + +### Example 3: Wildcards + +MQTT subscriptions with wildcards work seamlessly: + +```bash +# Subscribe to all sensor topics +mosquitto_sub -h localhost -p 1884 -t 'sensor/#' +``` + +Receives all Zenoh messages under `mqtt/demo/sensor/*` + +## Performance + +### Throughput +- **10,000+ messages/second** typical +- **100,000+ messages/second** with tuning + +### Latency +- **< 1ms** local bridge latency +- **< 5ms** end-to-end (MQTT → Zenoh) + +### Resource Usage +- **Memory**: ~50 MB base +- **CPU**: < 2% idle, scales with message rate + +## Troubleshooting + +### Bridge Not Starting + +```bash +# Check logs for errors +docker-compose logs zenoh-mqtt-bridge + +# Verify Zenoh router is accessible +docker exec zenoh-mqtt-bridge ping -c 2 zenoh-router + +# Test Zenoh connection +docker exec zenoh-mqtt-bridge nc -zv zenoh-router 7447 +``` + +### Messages Not Forwarding + +```bash +# Check if bridge receives MQTT messages +docker-compose logs zenoh-mqtt-bridge | grep -i "received\|publish" + +# Verify topic matches allow/deny filters +# Check configuration: cat zenoh-mqtt-bridge/config.json5 + +# Test direct connection +mosquitto_pub -h localhost -p 1884 -t 'test' -m 'hello' -d +``` + +### High Latency + +```bash +# Check buffer sizes in configuration +# Verify network connectivity +docker exec zenoh-mqtt-bridge ping -c 5 zenoh-router + +# Monitor resource usage +docker stats zenoh-mqtt-bridge +``` + +## Advanced Configuration + +### Custom Topic Mapping + +Modify the scope for different key namespaces: + +```json5 +{ + plugins: { + mqtt: { + scope: "iot/sensors", // Custom scope + // MQTT 'temp' becomes 'iot/sensors/temp' in Zenoh + } + } +} +``` + +### Multiple Bridges + +Run multiple bridge instances with different scopes: + +```yaml +zenoh-mqtt-bridge-1: + volumes: + - ./bridge1-config.json5:/etc/zenoh/config.json5 + ports: + - "1884:1884" + +zenoh-mqtt-bridge-2: + volumes: + - ./bridge2-config.json5:/etc/zenoh/config.json5 + ports: + - "1885:1884" +``` + +### QoS Mapping + +MQTT QoS levels are handled: +- **QoS 0**: Fire and forget (Zenoh default) +- **QoS 1**: At least once (Zenoh with reliability) +- **QoS 2**: Exactly once (Not fully supported) + +## Best Practices + +1. **Use Meaningful Scopes**: Choose scopes that reflect your data organization +2. **Filter Topics**: Use allow/deny to reduce unnecessary traffic +3. **Monitor Logs**: Check for dropped messages or errors +4. **Test Bidirectionally**: Verify both MQTT→Zenoh and Zenoh→MQTT +5. **Tune Buffer Sizes**: Adjust `tx_channel_size` for your throughput needs + +## Security Considerations + +- Bridge has no authentication by default +- Consider using MQTT authentication on broker +- Use network isolation (Docker networks) +- For production, implement TLS/SSL + +## See Also + +- [MQTT Broker](mqtt-broker.md) +- [Zenoh Router](zenoh-router.md) +- [Configuration Guide](../configuration/mqtt-bridge.md) +- [Eclipse Zenoh MQTT Bridge](https://github.com/eclipse-zenoh/zenoh-plugin-mqtt) diff --git a/docs/components/zenoh-ros2dds-bridge.md b/docs/components/zenoh-ros2dds-bridge.md new file mode 100644 index 0000000..34836a6 --- /dev/null +++ b/docs/components/zenoh-ros2dds-bridge.md @@ -0,0 +1,9 @@ +# Zenoh-ROS2DDS Bridge + +Protocol bridge between ROS2 DDS and Zenoh. + +## Overview + +This bridge enables bidirectional communication between ROS2 and Zenoh. + +**Ports:** 8002 (REST API), 7449 (Zenoh) diff --git a/docs/components/zenoh-router.md b/docs/components/zenoh-router.md new file mode 100644 index 0000000..1b6a078 --- /dev/null +++ b/docs/components/zenoh-router.md @@ -0,0 +1,373 @@ +# Zenoh Router + +The Zenoh Router is the central component of the Zenoh Multi-Protocol Bridge system, providing high-performance message routing and distribution across the network. + +## Overview + +The Zenoh Router acts as the backbone of the system, connecting all protocol bridges and clients. It implements the Zenoh protocol, which is designed for: + +- **Zero-overhead networking**: Minimal latency and CPU usage +- **Pub/Sub messaging**: Topic-based message distribution +- **Store/Query operations**: Optional data storage and retrieval +- **Multi-protocol support**: REST, TCP, UDP, and WebSocket + +## Architecture Role + +```mermaid +graph TB + subgraph "System Architecture" + MB[MQTT Bridge] -->|Zenoh Protocol| ZR[Zenoh Router
Central Hub] + RB[ROS2 Bridge] -->|Zenoh Protocol| ZR + ZS[Zenoh Subscriber] -->|Zenoh Protocol| ZR + EP[External Publisher] -->|TCP :7447| ZR + ES[External Subscriber] -->|TCP :7447| ZR + ZR -->|REST API :8000| Monitor[Monitoring Tools] + end + + classDef central fill:#f3e5f5 + class ZR central +``` + +## Key Features + +### 1. Message Routing + +The router efficiently routes messages based on: + +- **Topic patterns**: Wildcard-based matching (`sensor/*`, `robot/+/status`) +- **Key expressions**: Flexible path-like identifiers +- **Subscriptions**: Dynamic subscription management + +### 2. REST API + +The router exposes a REST API on port 8000 for: + +- Monitoring router status +- Querying stored data +- Publishing messages via HTTP +- Managing subscriptions + +### 3. Multiple Transports + +Supports various transport protocols: + +- **TCP**: Default transport (port 7447) +- **UDP**: For discovery and multicast +- **WebSocket**: For browser-based clients +- **REST**: For HTTP-based interaction + +### 4. Store/Query + +Optional storage backend for: + +- Historical data retrieval +- Query operations +- Data persistence + +## Configuration + +### Docker Compose Configuration + +```yaml +zenoh-router: + container_name: zenoh-router + image: eclipse/zenoh:latest + restart: unless-stopped + ports: + - "7447:7447" # Zenoh TCP + - "8000:8000" # REST API + environment: + - RUST_LOG=debug + networks: + - zenoh-mqtt-net + command: | + --listen tcp/0.0.0.0:7447 --rest-http-port 8000 +``` + +### Command-Line Options + +The router is started with: + +```bash +zenoh --listen tcp/0.0.0.0:7447 --rest-http-port 8000 +``` + +Options explained: + +- `--listen tcp/0.0.0.0:7447`: Listen for TCP connections on port 7447 +- `--rest-http-port 8000`: Enable REST API on port 8000 + +### Environment Variables + +- `RUST_LOG=debug`: Enable debug logging for troubleshooting + +## Ports and Endpoints + +| Port | Protocol | Purpose | Access | +|------|----------|---------|--------| +| 7447 | TCP | Zenoh protocol communication | All services | +| 8000 | HTTP | REST API | External access | + +## REST API Usage + +### Get Router Status + +```bash +curl http://localhost:8000/@/router/local +``` + +### Publish a Message + +```bash +curl -X PUT http://localhost:8000/demo/sensor/temp \ + -H 'Content-Type: application/json' \ + -d '{"temperature": 25.5}' +``` + +### Query Data + +```bash +curl http://localhost:8000/demo/sensor/* +``` + +### Subscribe via REST (SSE) + +```bash +curl http://localhost:8000/demo/sensor/* \ + -H 'Accept: text/event-stream' +``` + +## Integration with Other Components + +### MQTT Bridge Connection + +The MQTT bridge connects to the router: + +```json5 +{ + mode: "client", + connect: { + endpoints: ["tcp/zenoh-router:7447"] + } +} +``` + +### ROS2 Bridge Connection + +The ROS2 bridge connects similarly: + +```json5 +{ + mode: "client", + connect: { + endpoints: ["tcp/zenoh-router:7447"] + } +} +``` + +### External Clients + +Python clients connect from the host: + +```python +import zenoh + +session = zenoh.open(zenoh.Config()) +# Automatically discovers router on localhost:7447 +``` + +## Monitoring and Logging + +### View Logs + +```bash +# Real-time logs +docker-compose logs -f zenoh-router + +# Search for specific messages +docker-compose logs zenoh-router | grep -i "error\|warn" +``` + +### Log Levels + +Configure log level via `RUST_LOG`: + +- `error`: Only errors +- `warn`: Warnings and errors +- `info`: General information +- `debug`: Detailed debugging +- `trace`: Very verbose tracing + +### Health Check + +Check if the router is running: + +```bash +# Check container status +docker ps | grep zenoh-router + +# Test REST API +curl http://localhost:8000/@/router/local + +# Test TCP connection +nc -zv localhost 7447 +``` + +## Performance Considerations + +### Message Throughput + +The Zenoh router can handle: + +- **1M+ messages/second** on modern hardware +- **Sub-millisecond latency** for local routing +- **Thousands of concurrent subscriptions** + +### Resource Usage + +Typical resource consumption: + +- **Memory**: 50-100 MB base, scales with data +- **CPU**: < 2% idle, scales with message rate +- **Network**: Efficient zero-copy operations + +### Optimization Tips + +1. **Use TCP for high throughput**: More efficient than REST +2. **Enable batching**: Combine multiple small messages +3. **Tune buffer sizes**: Adjust for your workload +4. **Monitor metrics**: Use REST API to track performance + +## Troubleshooting + +### Router Not Starting + +**Symptom**: Container exits immediately + +**Solution**: +```bash +# Check logs +docker-compose logs zenoh-router + +# Verify port availability +netstat -tuln | grep 7447 +netstat -tuln | grep 8000 + +# Restart with different ports if needed +``` + +### Clients Can't Connect + +**Symptom**: Bridges or clients fail to connect + +**Solution**: +```bash +# Verify router is running +docker ps | grep zenoh-router + +# Check network connectivity +docker exec zenoh-mqtt-bridge ping -c 2 zenoh-router + +# Test TCP port +docker exec zenoh-mqtt-bridge nc -zv zenoh-router 7447 +``` + +### High Memory Usage + +**Symptom**: Router consuming excessive memory + +**Solution**: +```bash +# Check statistics via REST API +curl http://localhost:8000/@/router/local + +# Restart router to clear cache +docker-compose restart zenoh-router + +# Consider configuring storage limits +``` + +## Advanced Configuration + +### Custom Configuration File + +For advanced scenarios, create a Zenoh configuration file: + +```json5 +{ + mode: "router", + + listen: { + endpoints: ["tcp/0.0.0.0:7447"] + }, + + plugins: { + rest: { + http_port: 8000 + }, + storage_manager: { + volumes: { + memory: { + key_expr: "demo/**", + volume_cfg: { + backend: "memory", + max_memory_mb: 256 + } + } + } + } + } +} +``` + +Use it with: + +```yaml +zenoh-router: + volumes: + - ./zenoh/router-config.json5:/etc/zenoh/config.json5 + command: "-c /etc/zenoh/config.json5" +``` + +### Mesh Network Setup + +Connect multiple routers: + +```json5 +{ + mode: "router", + + connect: { + endpoints: ["tcp/router2:7447", "tcp/router3:7447"] + } +} +``` + +## Security + +### Network Security + +- Runs in isolated Docker network +- Only exposed ports accessible from host +- Consider TLS for production deployments + +### Access Control + +- REST API has no authentication by default +- Consider using reverse proxy with auth +- Implement network-level security + +## Best Practices + +1. **Monitoring**: Regularly check REST API for health +2. **Logging**: Keep debug logs during development +3. **Updates**: Keep router image updated +4. **Backup**: Store configuration files in version control +5. **Testing**: Test router under load before production + +## See Also + +- [Zenoh-MQTT Bridge](zenoh-mqtt-bridge.md) +- [Zenoh-ROS2DDS Bridge](zenoh-ros2dds-bridge.md) +- [Architecture Overview](../architecture/overview.md) +- [Official Zenoh Documentation](https://zenoh.io/docs/) diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.md new file mode 100644 index 0000000..8873cd4 --- /dev/null +++ b/docs/configuration/docker-compose.md @@ -0,0 +1,5 @@ +# Docker Compose Configuration + +The `docker-compose.yaml` file orchestrates all services. + +See [Getting Started](../getting-started/installation.md) for usage. diff --git a/docs/configuration/mqtt-bridge.md b/docs/configuration/mqtt-bridge.md new file mode 100644 index 0000000..1e18ba4 --- /dev/null +++ b/docs/configuration/mqtt-bridge.md @@ -0,0 +1,5 @@ +# MQTT Bridge Configuration + +Configuration guide for the Zenoh-MQTT bridge. + +See [Zenoh-MQTT Bridge Component](../components/zenoh-mqtt-bridge.md) for detailed information. diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md new file mode 100644 index 0000000..63c9fab --- /dev/null +++ b/docs/configuration/overview.md @@ -0,0 +1,54 @@ +# Configuration Overview + +This guide provides an overview of configuration options for the Zenoh Multi-Protocol Bridge system. + +## Configuration Files + +The system uses multiple configuration files: + +| File | Purpose | Format | +|------|---------|--------| +| `docker-compose.yaml` | Service orchestration | YAML | +| `zenoh-mqtt-bridge/config.json5` | MQTT bridge settings | JSON5 | +| `zenoh-ros2dds-bridge/config.json5` | ROS2 bridge settings | JSON5 | +| `mosquitto/config/mosquitto.conf` | MQTT broker config | INI-style | + +## Quick Configuration + +### Changing Ports + +Edit `docker-compose.yaml`: + +```yaml +services: + service-name: + ports: + - "NEW_HOST_PORT:CONTAINER_PORT" +``` + +### Adjusting Log Levels + +```yaml +environment: + - RUST_LOG=info # Options: error, warn, info, debug, trace +``` + +### Modifying Bridge Scopes + +Edit `zenoh-mqtt-bridge/config.json5`: + +```json5 +{ + plugins: { + mqtt: { + scope: "your/custom/scope" + } + } +} +``` + +## See Also + +- [MQTT Bridge Configuration](mqtt-bridge.md) +- [ROS2 Bridge Configuration](ros2-bridge.md) +- [Docker Compose Configuration](docker-compose.md) diff --git a/docs/configuration/ros2-bridge.md b/docs/configuration/ros2-bridge.md new file mode 100644 index 0000000..017199d --- /dev/null +++ b/docs/configuration/ros2-bridge.md @@ -0,0 +1,5 @@ +# ROS2 Bridge Configuration + +Configuration guide for the Zenoh-ROS2DDS bridge. + +See [Zenoh-ROS2DDS Bridge Component](../components/zenoh-ros2dds-bridge.md) for detailed information. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..131414c --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,460 @@ +# Contributing to Zenoh Multi-Protocol Bridge + +Thank you for your interest in contributing to the Zenoh Multi-Protocol Bridge project! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [How to Contribute](#how-to-contribute) +- [Development Setup](#development-setup) +- [Coding Standards](#coding-standards) +- [Testing Guidelines](#testing-guidelines) +- [Submitting Changes](#submitting-changes) +- [Documentation](#documentation) + +## Code of Conduct + +This project adheres to a code of conduct that all contributors are expected to follow: + +- **Be Respectful**: Treat everyone with respect and consideration +- **Be Collaborative**: Work together and help each other +- **Be Inclusive**: Welcome and support people of all backgrounds +- **Be Professional**: Maintain professionalism in all interactions + +## Getting Started + +### Prerequisites + +Before contributing, ensure you have: + +- Git installed +- Docker and Docker Compose +- Basic understanding of the technologies used: + - Zenoh protocol + - MQTT + - ROS2 (for robotics-related contributions) + - Docker containers + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://github.com/YOUR-USERNAME/zenoh-multi-bridge.git + cd zenoh-multi-bridge + ``` + +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/harunkurtdev/zenoh-multi-bridge.git + ``` + +## How to Contribute + +### Reporting Bugs + +When reporting bugs, please include: + +1. **Clear Title**: Descriptive summary of the issue +2. **Description**: Detailed explanation of the problem +3. **Steps to Reproduce**: + ``` + 1. Start services with 'docker-compose up' + 2. Run command X + 3. Observe error Y + ``` +4. **Expected Behavior**: What should happen +5. **Actual Behavior**: What actually happens +6. **Environment**: + - OS: (e.g., Ubuntu 22.04) + - Docker version: (e.g., 24.0.5) + - Docker Compose version: (e.g., 2.20.2) +7. **Logs**: Relevant log output + ```bash + docker-compose logs [service-name] + ``` + +### Suggesting Enhancements + +Enhancement suggestions are welcome! Please include: + +1. **Use Case**: Why is this enhancement needed? +2. **Proposed Solution**: How should it work? +3. **Alternatives**: Other approaches you've considered +4. **Additional Context**: Screenshots, diagrams, etc. + +### Contributing Code + +Types of contributions we welcome: + +- **Bug fixes**: Corrections to existing functionality +- **New features**: Additional capabilities +- **Performance improvements**: Optimizations +- **Documentation**: Improvements to docs +- **Examples**: New use case examples +- **Tests**: Additional test coverage + +## Development Setup + +### 1. Local Environment + +```bash +# Clone repository +git clone https://github.com/YOUR-USERNAME/zenoh-multi-bridge.git +cd zenoh-multi-bridge + +# Create a feature branch +git checkout -b feature/your-feature-name +``` + +### 2. Build and Test + +```bash +# Build custom images +docker-compose build + +# Start services +docker-compose up -d + +# View logs +docker-compose logs -f + +# Run tests (if available) +./run-tests.sh # Add this if you create test scripts +``` + +### 3. Make Changes + +- Modify code or configuration files +- Test your changes locally +- Ensure all services still work together + +### 4. Test Your Changes + +```bash +# Restart affected services +docker-compose restart [service-name] + +# Test end-to-end +python3 pub.py # Terminal 1 +python3 sub.py # Terminal 2 + +# Check logs for errors +docker-compose logs | grep -i error +``` + +## Coding Standards + +### Configuration Files + +- Use **JSON5** format for Zenoh configurations +- Include comments explaining non-obvious settings +- Follow existing file structure + +Example: +```json5 +{ + // Client mode connects to existing router + mode: "client", + + // Connection endpoint + connect: { + endpoints: ["tcp/zenoh-router:7447"], + }, + + // Plugin configuration + plugins: { + mqtt: { + // MQTT server port + port: "0.0.0.0:1884", + // Scope prefix for topics + scope: "mqtt/demo", + } + } +} +``` + +### Docker Compose + +- Keep service definitions organized +- Use meaningful container names +- Document non-standard ports +- Include restart policies + +```yaml +services: + service-name: + container_name: service-name + image: image:tag + restart: unless-stopped + ports: + - "host:container" # Document purpose + environment: + - VAR_NAME=value + networks: + - zenoh-mqtt-net +``` + +### Documentation + +- Use Markdown format +- Include code examples +- Add diagrams where helpful (Mermaid syntax) +- Keep documentation up-to-date with code changes + +## Testing Guidelines + +### Manual Testing + +1. **Start All Services** + ```bash + docker-compose up -d + docker-compose ps # Verify all running + ``` + +2. **Test MQTT Flow** + ```bash + # Terminal 1: Subscribe + mosquitto_sub -h localhost -p 1883 -t 'test/#' -v + + # Terminal 2: Publish + mosquitto_pub -h localhost -p 1884 -t 'test/msg' -m 'Hello' + ``` + +3. **Test Zenoh Flow** + ```bash + # Terminal 1: Subscribe + python3 sub.py + + # Terminal 2: Publish + python3 pub.py + ``` + +4. **Test Multi-Protocol** + - Publish to MQTT + - Verify in Zenoh subscriber + - Check ROS2 topics (if applicable) + +### Integration Tests + +If adding test scripts: + +```bash +#!/bin/bash +# test-integration.sh + +set -e + +echo "Starting services..." +docker-compose up -d + +echo "Waiting for services to be ready..." +sleep 10 + +echo "Testing MQTT to Zenoh bridge..." +# Add test commands + +echo "All tests passed!" +``` + +### Performance Testing + +For performance-critical changes: + +```bash +# Measure message throughput +docker-compose logs zenoh-router | grep -c "published" + +# Check latency +# Use timestamps in messages to measure end-to-end latency +``` + +## Submitting Changes + +### Commit Messages + +Use clear, descriptive commit messages: + +``` +Add support for custom MQTT topic filters + +- Implement configurable allow/deny patterns +- Update configuration documentation +- Add examples in README + +Fixes #123 +``` + +Format: +- First line: Brief summary (50 chars or less) +- Blank line +- Detailed description (if needed) +- Reference related issues + +### Pull Request Process + +1. **Update Documentation** + - Update README if needed + - Add/update relevant docs in `docs/` + - Update CHANGELOG if present + +2. **Test Your Changes** + ```bash + docker-compose down + docker-compose build + docker-compose up -d + # Run manual tests + ``` + +3. **Create Pull Request** + - Push to your fork + - Open PR against `main` branch + - Fill out PR template (if available) + - Link related issues + +4. **PR Description Template** + ```markdown + ## Description + Brief description of changes + + ## Type of Change + - [ ] Bug fix + - [ ] New feature + - [ ] Documentation update + - [ ] Performance improvement + + ## Testing + - [ ] Manual testing completed + - [ ] All services start successfully + - [ ] Multi-protocol communication works + + ## Checklist + - [ ] Code follows project style + - [ ] Documentation updated + - [ ] No breaking changes (or documented) + + ## Related Issues + Fixes #123 + ``` + +5. **Review Process** + - Respond to review comments + - Make requested changes + - Update PR as needed + +### After PR Acceptance + +1. **Sync with Upstream** + ```bash + git checkout main + git fetch upstream + git merge upstream/main + git push origin main + ``` + +2. **Delete Feature Branch** + ```bash + git branch -d feature/your-feature-name + git push origin --delete feature/your-feature-name + ``` + +## Documentation + +### Documentation Structure + +``` +docs/ +├── index.md # Home page +├── getting-started/ # Installation, quick start +├── architecture/ # System design +├── components/ # Component details +├── configuration/ # Configuration guides +├── usage/ # Usage examples +├── use-cases/ # Real-world applications +├── api/ # API reference +└── troubleshooting.md # Problem solving +``` + +### Writing Documentation + +- Use clear, concise language +- Include practical examples +- Add diagrams for complex concepts +- Test all code examples +- Keep it updated with changes + +### Building Documentation + +```bash +# Install dependencies +pip install -r requirements.txt + +# Build documentation +mkdocs build + +# Serve locally +mkdocs serve + +# View at http://localhost:8000 +``` + +## Style Guide + +### Markdown + +- Use ATX-style headers (`#` not `===`) +- Include blank lines around code blocks +- Use fenced code blocks with language tags +- Keep lines under 120 characters when possible + +### Code Examples + +```bash +# Good: Include comments and context +# Start the MQTT publisher +mosquitto_pub -h localhost -p 1884 -t 'sensor/temp' -m '{"value":25}' + +# Bad: No context or explanation +mosquitto_pub -h localhost -p 1884 -t 'sensor/temp' -m '{"value":25}' +``` + +## Communication + +### Channels + +- **GitHub Issues**: Bug reports, feature requests +- **Pull Requests**: Code contributions +- **Discussions**: General questions, ideas + +### Getting Help + +If you need help: + +1. Check existing documentation +2. Search closed issues +3. Ask in GitHub Discussions +4. Open a new issue with "question" label + +## Recognition + +Contributors will be: + +- Listed in CONTRIBUTORS file (if created) +- Mentioned in release notes +- Credited in commit history + +## License + +By contributing, you agree that your contributions will be licensed under the same license as the project (Apache License 2.0). + +## Questions? + +If you have questions about contributing: + +1. Check this guide first +2. Look at existing PRs for examples +3. Open an issue with the "question" label +4. We're here to help! + +Thank you for contributing to Zenoh Multi-Protocol Bridge! 🎉 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..9f5188d --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,520 @@ +# Troubleshooting Guide + +This guide helps you diagnose and resolve common issues with the Zenoh Multi-Protocol Bridge. + +## General Troubleshooting Steps + +### 1. Check Service Status + +```bash +# List all containers and their status +docker-compose ps + +# Check if all services are running +docker ps --filter "name=zenoh" --filter "name=mqtt" --filter "name=ros2" --filter "name=node-red" +``` + +### 2. View Logs + +```bash +# View all service logs +docker-compose logs -f + +# View specific service logs +docker-compose logs -f zenoh-router +docker-compose logs -f zenoh-mqtt-bridge +docker-compose logs -f zenoh-ros2dds-bridge +``` + +### 3. Verify Network Connectivity + +```bash +# Check Docker network +docker network inspect zenoh-mqtt-net + +# Test connectivity between services +docker exec zenoh-mqtt-bridge ping -c 2 zenoh-router +docker exec zenoh-ros2dds-bridge ping -c 2 zenoh-router +``` + +## Common Issues + +### Services Won't Start + +#### Issue: Port Already in Use + +**Symptoms:** +``` +Error: Bind for 0.0.0.0:1883 failed: port is already allocated +``` + +**Solution:** +```bash +# Find process using the port +lsof -i :1883 +# or +netstat -tuln | grep 1883 + +# Stop the conflicting process or change port in docker-compose.yaml +# Example: Change host port mapping +ports: + - "1884:1883" # Maps host:1884 to container:1883 +``` + +#### Issue: Docker Permission Denied + +**Symptoms:** +``` +Got permission denied while trying to connect to the Docker daemon socket +``` + +**Solution:** +```bash +# Add user to docker group +sudo usermod -aG docker $USER + +# Apply group membership (or log out and back in) +newgrp docker + +# Verify +docker ps +``` + +#### Issue: Image Pull Fails + +**Symptoms:** +``` +Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: TLS handshake timeout +``` + +**Solution:** +```bash +# Check internet connectivity +ping -c 3 google.com + +# Retry with clean state +docker-compose down +docker-compose pull +docker-compose up -d + +# Or pull images individually +docker pull eclipse/zenoh:latest +docker pull eclipse/zenoh-bridge-mqtt:latest +docker pull eclipse-mosquitto:latest +``` + +### Messages Not Flowing + +#### Issue: MQTT Messages Not Reaching Zenoh + +**Symptoms:** +- MQTT publisher works +- Zenoh subscriber receives nothing + +**Diagnosis:** +```bash +# Check MQTT bridge logs +docker-compose logs zenoh-mqtt-bridge | grep -i "error\|warn" + +# Verify MQTT bridge is connected to Zenoh +docker-compose logs zenoh-mqtt-bridge | grep -i "connect" + +# Test direct MQTT connection to bridge +mosquitto_pub -h localhost -p 1884 -t 'test/debug' -m 'test message' -d +``` + +**Solution:** +```bash +# Restart the bridge +docker-compose restart zenoh-mqtt-bridge + +# Check topic filters in config +cat zenoh-mqtt-bridge/config.json5 | grep -A 5 "allow\|deny" + +# Verify scope configuration +# MQTT 'sensor/temp' should appear as 'mqtt/demo/sensor/temp' in Zenoh +``` + +#### Issue: Zenoh Messages Not Reaching ROS2 + +**Symptoms:** +- Zenoh router works +- ROS2 topics are empty + +**Diagnosis:** +```bash +# Check ROS2 bridge logs +docker-compose logs zenoh-ros2dds-bridge | grep -i "error\|warn" + +# List ROS2 topics +docker exec -it ros2-humble ros2 topic list + +# Check if bridge is connected +docker-compose logs zenoh-ros2dds-bridge | grep -i "connect" +``` + +**Solution:** +```bash +# Restart ROS2 bridge +docker-compose restart zenoh-ros2dds-bridge + +# Verify ROS2 domain ID matches +docker-compose logs ros2-humble | grep ROS_DOMAIN_ID +docker-compose logs zenoh-ros2dds-bridge | grep ROS_DOMAIN_ID + +# Check namespace configuration +cat zenoh-ros2dds-bridge/config.json5 | grep namespace +``` + +### Performance Issues + +#### Issue: High Latency + +**Symptoms:** +- Messages delayed by seconds +- Slow response times + +**Diagnosis:** +```bash +# Check CPU usage +docker stats + +# Check network latency +docker exec zenoh-mqtt-bridge ping -c 10 zenoh-router + +# Monitor message rates +docker-compose logs zenoh-router | grep -i "message\|pub\|sub" | tail -n 50 +``` + +**Solution:** +```bash +# Reduce logging level +# Edit docker-compose.yaml: +environment: + - RUST_LOG=info # Change from debug to info + +# Restart services +docker-compose restart + +# Check system resources +free -h +df -h +``` + +#### Issue: High Memory Usage + +**Symptoms:** +- Container using excessive memory +- System becomes slow + +**Diagnosis:** +```bash +# Check memory usage per container +docker stats --no-stream + +# Check container logs for issues +docker-compose logs zenoh-router | grep -i "memory\|oom" +``` + +**Solution:** +```bash +# Restart affected service +docker-compose restart zenoh-router + +# Add memory limits in docker-compose.yaml: +services: + zenoh-router: + mem_limit: 512m + mem_reservation: 256m + +# Clear old logs +docker-compose down +rm -rf mosquitto/log/* +docker-compose up -d +``` + +### Connection Issues + +#### Issue: Can't Access Web Interfaces + +**Symptoms:** +- Node-RED not loading at localhost:1880 +- REST APIs not responding + +**Diagnosis:** +```bash +# Check if service is running +docker ps | grep node-red + +# Check port mapping +docker port node-red + +# Test port accessibility +curl http://localhost:1880 +curl http://localhost:8000 +``` + +**Solution:** +```bash +# Restart the service +docker-compose restart node-red + +# Check firewall +sudo ufw status +sudo ufw allow 1880/tcp + +# Verify no proxy interfering +curl -v http://localhost:1880 +``` + +#### Issue: External Scripts Can't Connect + +**Symptoms:** +- pub.py or sub.py fail to connect +- Connection timeout errors + +**Diagnosis:** +```bash +# Test Zenoh router accessibility +nc -zv localhost 7447 + +# Check if router is listening +docker exec zenoh-router netstat -tuln | grep 7447 + +# Verify firewall +sudo iptables -L | grep 7447 +``` + +**Solution:** +```bash +# Ensure router is exposing port +docker-compose ps zenoh-router + +# Check docker-compose.yaml port mapping: +ports: + - "7447:7447" # Must be present + +# Restart router +docker-compose restart zenoh-router + +# Test connection +telnet localhost 7447 +``` + +### Configuration Issues + +#### Issue: Config Changes Not Applied + +**Symptoms:** +- Modified configuration has no effect +- Service using old settings + +**Solution:** +```bash +# Restart the specific service +docker-compose restart zenoh-mqtt-bridge + +# If config is in volume, rebuild +docker-compose down +docker-compose up -d + +# For major changes, rebuild image +docker-compose build zenoh-ros2dds-bridge +docker-compose up -d +``` + +#### Issue: Invalid Configuration + +**Symptoms:** +``` +Error: Failed to parse config file +``` + +**Solution:** +```bash +# Validate JSON5 syntax +cat zenoh-mqtt-bridge/config.json5 + +# Common issues: +# - Missing commas +# - Trailing commas +# - Incorrect quotes +# - Unescaped special characters + +# Use online JSON5 validator or: +python3 -c "import json5; json5.load(open('zenoh-mqtt-bridge/config.json5'))" +``` + +### Data Issues + +#### Issue: Malformed Messages + +**Symptoms:** +- Subscribers receive garbled data +- JSON parsing errors + +**Diagnosis:** +```bash +# Monitor raw messages +docker-compose logs -f zenoh-subscriber + +# Check publisher format +mosquitto_pub -h localhost -p 1884 -t 'test' -m '{"test":123}' -d +``` + +**Solution:** +- Ensure valid JSON format +- Check character encoding (UTF-8) +- Verify message size limits +- Test with simple messages first + +## ROS2-Specific Issues + +### Issue: ROS2 Topics Not Visible + +**Diagnosis:** +```bash +# Enter ROS2 container +docker exec -it ros2-humble bash + +# Source ROS2 +source /opt/ros/humble/setup.bash + +# List topics +ros2 topic list + +# Check if bridge is running +ps aux | grep zenoh +``` + +**Solution:** +```bash +# Verify ROS_DOMAIN_ID +echo $ROS_DOMAIN_ID + +# Check DDS configuration +cat /root/cyclonedds.xml + +# Restart ROS2 services +docker-compose restart ros2-humble zenoh-ros2dds-bridge +``` + +### Issue: Foxglove Not Connecting + +**Symptoms:** +- Can't connect to ws://localhost:8765 +- Blank dashboard + +**Solution:** +```bash +# Check if Foxglove bridge is running +docker exec ros2-humble ps aux | grep foxglove + +# View Foxglove logs +docker-compose logs ros2-humble | grep foxglove + +# Restart ROS2 with Foxglove +docker-compose restart ros2-humble + +# Test WebSocket +wscat -c ws://localhost:8765 +``` + +## Debugging Tools + +### Enable Debug Logging + +```yaml +# In docker-compose.yaml +environment: + - RUST_LOG=debug # or trace for maximum verbosity +``` + +### Interactive Shell Access + +```bash +# Access any container +docker exec -it zenoh-router sh +docker exec -it ros2-humble bash +docker exec -it zenoh-mqtt-bridge sh + +# Install debugging tools (if needed) +apk add curl netcat-openbsd # Alpine Linux +apt-get update && apt-get install curl netcat # Debian/Ubuntu +``` + +### Network Debugging + +```bash +# Capture network traffic +docker exec zenoh-mqtt-bridge tcpdump -i any port 1884 + +# Test DNS resolution +docker exec zenoh-mqtt-bridge nslookup zenoh-router + +# Check routing +docker exec zenoh-mqtt-bridge traceroute zenoh-router +``` + +## Getting Help + +If you can't resolve the issue: + +1. **Collect Information:** + ```bash + # System info + docker version + docker-compose version + uname -a + + # Service logs + docker-compose logs > logs.txt + + # Configuration + cat docker-compose.yaml + cat zenoh-mqtt-bridge/config.json5 + cat zenoh-ros2dds-bridge/config.json5 + ``` + +2. **Search Existing Issues:** + - [Project Issues](https://github.com/harunkurtdev/zenoh-multi-bridge/issues) + - [Zenoh Issues](https://github.com/eclipse-zenoh/zenoh/issues) + - [ROS2 Answers](https://answers.ros.org/) + +3. **Create New Issue:** + - Include system information + - Attach relevant logs + - Describe steps to reproduce + - Mention what you've tried + +## Preventive Maintenance + +### Regular Checks + +```bash +# Weekly: Check disk space +df -h + +# Monthly: Update images +docker-compose pull +docker-compose up -d + +# Clean old containers/images +docker system prune -a +``` + +### Monitoring + +```bash +# Set up monitoring +docker stats + +# Log rotation +# Configure in mosquitto.conf and Docker logging +``` + +## See Also + +- [Installation Guide](getting-started/installation.md) +- [Configuration Guide](configuration/overview.md) +- [Architecture Overview](architecture/overview.md) diff --git a/docs/usage/monitoring.md b/docs/usage/monitoring.md new file mode 100644 index 0000000..98dddb6 --- /dev/null +++ b/docs/usage/monitoring.md @@ -0,0 +1,5 @@ +# Monitoring + +Monitoring the system using Node-RED and REST APIs. + +See [API Endpoints](../api/endpoints.md) for REST API monitoring. diff --git a/docs/usage/multi-protocol.md b/docs/usage/multi-protocol.md new file mode 100644 index 0000000..f29880c --- /dev/null +++ b/docs/usage/multi-protocol.md @@ -0,0 +1,11 @@ +# Multi-Protocol Communication + +Using multiple protocols together. + +## MQTT to Zenoh + +See the [Quick Start Guide](../getting-started/quick-start.md). + +## Zenoh to ROS2 + +Communication between Zenoh and ROS2 networks. diff --git a/docs/usage/testing.md b/docs/usage/testing.md new file mode 100644 index 0000000..48d35f0 --- /dev/null +++ b/docs/usage/testing.md @@ -0,0 +1,5 @@ +# Testing + +How to test the Zenoh Multi-Protocol Bridge system. + +See [Quick Start Guide](../getting-started/quick-start.md) for testing examples. diff --git a/docs/use-cases/hybrid-communication.md b/docs/use-cases/hybrid-communication.md new file mode 100644 index 0000000..739ee3a --- /dev/null +++ b/docs/use-cases/hybrid-communication.md @@ -0,0 +1,13 @@ +# Hybrid Communication Systems + +Integrating legacy MQTT infrastructure with modern protocols. + +## Overview + +Connect existing MQTT-based systems with Zenoh and ROS2. + +## Use Cases + +- Legacy system integration +- Gradual migration to modern protocols +- Protocol-agnostic application development diff --git a/docs/use-cases/industrial.md b/docs/use-cases/industrial.md new file mode 100644 index 0000000..1040f60 --- /dev/null +++ b/docs/use-cases/industrial.md @@ -0,0 +1,9 @@ +# Industrial Automation + +SCADA systems integration with robot controllers. + +## Applications + +- Factory automation +- Process control +- Real-time monitoring and control dashboards diff --git a/docs/use-cases/iot-robotics.md b/docs/use-cases/iot-robotics.md new file mode 100644 index 0000000..6834256 --- /dev/null +++ b/docs/use-cases/iot-robotics.md @@ -0,0 +1,13 @@ +# IoT-Robotics Integration + +Connecting IoT sensors to robot control systems. + +## Overview + +This use case demonstrates how sensor data from IoT devices (MQTT) can be used by robot control systems (ROS2). + +## Benefits + +- Real-time environmental data for autonomous robots +- Seamless integration of IoT and robotics platforms +- Unified data flow across protocols diff --git a/docs/use-cases/research.md b/docs/use-cases/research.md new file mode 100644 index 0000000..c296e1e --- /dev/null +++ b/docs/use-cases/research.md @@ -0,0 +1,9 @@ +# Research and Development Platform + +Multi-protocol testing and research environment. + +## Applications + +- Performance comparison between protocols +- Development sandbox for distributed systems +- Educational platform for protocol bridging diff --git a/docs/use-cases/smart-city.md b/docs/use-cases/smart-city.md new file mode 100644 index 0000000..f72cc26 --- /dev/null +++ b/docs/use-cases/smart-city.md @@ -0,0 +1,9 @@ +# Smart City Applications + +IoT sensors and autonomous vehicles communication. + +## Applications + +- Traffic management systems +- Environmental monitoring +- Smart infrastructure From 8038918c0ed86cd2326c472cf7c3d08e0bbe6b08 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 19 Oct 2025 16:44:56 +0000 Subject: [PATCH 4/5] Add documentation reference to main README Co-authored-by: harunkurtdev <50794236+harunkurtdev@users.noreply.github.com> --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index ce59110..3e94928 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,32 @@ This project is a comprehensive multi-protocol bridge system designed to connect **Zenoh**, **MQTT**, and **ROS2** protocols. The project enables seamless data transfer between different communication protocols commonly used in IoT, robotics, and distributed systems. +## 📚 Documentation + +**Complete documentation is available at: [https://harunkurtdev.github.io/zenoh-multi-bridge/](https://harunkurtdev.github.io/zenoh-multi-bridge/)** *(or locally via MkDocs)* + +To view the documentation locally: + +```bash +# Install dependencies +pip install -r requirements.txt + +# Serve documentation +mkdocs serve + +# Open http://localhost:8000 in your browser +``` + +The documentation includes: +- 📖 Installation and quick start guides +- 🏗️ Architecture overview with diagrams +- 🔧 Component-specific documentation +- ⚙️ Configuration guides +- 🧪 Testing and usage examples +- 💡 Real-world use cases +- 🔌 API reference +- 🛠️ Troubleshooting guide + ## 🎯 Project Objectives This project is a **multi-protocol bridge** system that enables different protocols to work together in modern IoT and robotics ecosystems. Its main objectives are: From cb8ffece4997d0ea09646351c46bf4d52478819c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 19 Oct 2025 16:45:55 +0000 Subject: [PATCH 5/5] Fix documentation URL reference in README Co-authored-by: harunkurtdev <50794236+harunkurtdev@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e94928..2517fd4 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This project is a comprehensive multi-protocol bridge system designed to connect ## 📚 Documentation -**Complete documentation is available at: [https://harunkurtdev.github.io/zenoh-multi-bridge/](https://harunkurtdev.github.io/zenoh-multi-bridge/)** *(or locally via MkDocs)* +**Complete documentation available via MkDocs** *(can be deployed to GitHub Pages)* To view the documentation locally: