client/python/examples/README.md

LeRobot Arena Examples

This directory contains example scripts demonstrating various aspects of the LeRobot Arena robotics system.

Prerequisites

Before running these examples, ensure you have:

1. Server running: Start the LeRobot Arena server

   # From the server directory
   uvicorn src.api.main:app --reload
   

2. Dependencies installed: Install the Python client

   # From client/python directory
   pip install -e .
   

Examples Overview

1. basic_producer.py

Basic Producer Usage

Demonstrates core producer functionality:

• Creating a room
• Connecting as a producer
• Sending joint updates
• Sending state synchronization
• Basic error handling

python examples/basic_producer.py

2. basic_consumer.py

Basic Consumer Usage

Shows how to connect as a consumer and receive data:

• Connecting to an existing room
• Setting up event callbacks
• Receiving joint updates and state sync
• Getting current room state

python examples/basic_consumer.py
# You'll need to enter a room ID from a running producer

3. room_management.py

Room Management Operations

Demonstrates REST API operations:

• Listing all rooms
• Creating rooms (auto-generated and custom IDs)
• Getting room information and state
• Deleting rooms

python examples/room_management.py

4. producer_consumer_demo.py

Complete Producer-Consumer Demo

Comprehensive demonstration featuring:

• Producer and multiple consumers working together
• Realistic robot movement simulation
• Emergency stop functionality
• State synchronization
• Connection management and cleanup

python examples/producer_consumer_demo.py

5. context_manager_example.py

Context Managers and Advanced Patterns

Shows advanced usage patterns:

• Using clients as context managers for automatic cleanup
• Exception handling with proper resource management
• Factory functions for quick client setup
• Managing multiple clients

python examples/context_manager_example.py

Running Examples

Quick Start (All-in-One Demo)

For a complete demonstration, run:

python examples/producer_consumer_demo.py

Step-by-Step Testing

1. Start with room management:

   python examples/room_management.py
   

2. Run producer in one terminal:

   python examples/basic_producer.py
   

3. Run consumer in another terminal:

   python examples/basic_consumer.py
   # Use the room ID from the producer
   

Advanced Examples

For more sophisticated patterns:

python examples/context_manager_example.py

Key Concepts Demonstrated

Producer Capabilities

• Room Creation: Creating and managing robotics rooms
• Joint Control: Sending individual joint position updates
• State Synchronization: Sending complete robot state
• Emergency Stop: Triggering safety stops
• Error Handling: Managing connection and communication errors

Consumer Capabilities

• Real-time Updates: Receiving joint position updates
• State Monitoring: Getting current robot state
• Event Callbacks: Responding to various message types
• Multiple Consumers: Supporting multiple clients per room

Connection Management

• WebSocket Communication: Real-time bidirectional communication
• Auto-reconnection: Handling connection failures
• Resource Cleanup: Proper disconnection and cleanup
• Context Managers: Automatic resource management

Error Handling

• Connection Failures: Graceful handling of network issues
• Invalid Operations: Handling invalid commands or states
• Emergency Scenarios: Safety system demonstrations
• Resource Management: Proper cleanup in error conditions

Example Output

When running the examples, you'll see detailed logging output showing:

• Connection status and events
• Data being sent and received
• Error conditions and handling
• Resource cleanup operations

Example log output:

INFO:__main__:Created room: abc123-def456-ghi789
INFO:__main__:[Producer] Connected!
INFO:__main__:[visualizer] Joint update #1: 4 joints
INFO:__main__:[logger] Joint update #1: 4 joints
INFO:__main__:🚨 [Producer] Sending emergency stop!
INFO:__main__:[safety-monitor] ERROR: Emergency stop: Demo emergency stop

Troubleshooting

Common Issues

1. Connection Failed: Ensure the server is running on http://localhost:8000
2. Import Errors: Make sure you've installed the client package (pip install -e .)
3. Room Not Found: Check that the room ID exists (run room_management.py to see active rooms)
4. Permission Denied: Only one producer per room is allowed

Debug Mode

Enable debug logging for more detailed output:

logging.basicConfig(level=logging.DEBUG)

Next Steps

After running these examples, you can:

• Integrate the client into your own robotics applications
• Modify the examples for your specific robot hardware
• Build custom visualizers or control interfaces
• Implement safety monitoring systems
• Create automated testing scenarios