⚠️ Beta Software

This is beta software under active development. Expect bugs, quirks, and occasional unexpected behavior.

Have feedback, found an issue, or want to suggest improvements? Join the discussion in our Discord channel!

A modern, web-based control system for the PAROL6 6-axis robotic arm featuring real-time 3D visualization, timeline-based motion programming, and advanced kinematics.

• Real-time 3D Visualization - Interactive 3D robot model with live hardware tracking
• Dual Control Modes - Joint space and Cartesian space motion control
• Timeline Editor - Visual programming with keyframe-based motion sequences and loop variables
• Live Control - Real-time hardware following with trajectory preview
• Advanced Kinematics - Frontend IK solver with numerical stability and singularity handling
• J2 Backlash Compensation - Automatic compensation for mechanical backlash in J2 joint
• Tool Management - Configurable end-effectors with TCP offset and gripper support
• Interactive Help - Built-in help annotations highlighting key UI elements
• Debug Mode - Optional debug logging for troubleshooting
• WebSocket Streaming - High-frequency robot status updates (1-50Hz)
• Camera Integration - Optional camera feed with MJPEG streaming
• Saved Positions - Store and recall common robot configurations
• Comprehensive API - RESTful API for all robot operations

graph LR
    A[Frontend<br/>Next.js<br/>Port 3000] <-->|HTTP/WebSocket| B[API Server<br/>FastAPI<br/>Port 3001]
    B <-->|UDP 5001/5002| C[Commander<br/>Python<br/>Control Loop]
    C <-->|Serial USB| D[Robot<br/>Hardware]

• Robot: PAROL6 6-axis robotic arm
• Computer: Raspberry Pi 4/5 or Linux PC recommended
• Connection: USB serial connection to robot controller
• Optional: USB camera for vision integration

• Python: 3.9 or higher
• Node.js: 18.x or higher
• npm: 9.x or higher
• PM2: Process manager (install globally: npm install -g pm2)

See requirements.txt for complete list. Key dependencies:

• FastAPI (web framework)
• uvicorn (ASGI server)
• pyserial (robot communication)
• numpy (numerical computing)
• opencv-python (camera support)

Managed automatically via package.json:

• next (React framework)
• react, react-dom (UI library)
• three, @react-three/fiber (3D rendering)
• zustand (state management)
• tailwindcss (styling)

git clone <repository-url>
cd parol6
git submodule update --init --recursive

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Note: The rtb-reference/ directory contains the Robotics Toolbox library required for IK solving. Ensure it's present (not in .gitignore for fresh installs).

cd frontend
npm install
cd ..

npm install -g pm2

Edit config.yaml for your environment:

robot:
  com_port: /dev/ttyACM0  # Serial port for robot
  baud_rate: 3000000      # Communication speed

api:
  host: 0.0.0.0
  port: 3001

For production deployment, pre-built Docker images are available. This is the recommended method for production environments.

• Docker and Docker Compose installed (Install Docker)
• Access to robot's serial port (usually /dev/ttyACM0)

Step 1: Clone the repository

git clone https://github.com/jointAxis77/parol6-webcommander.git
cd parol6-webcommander

Step 2: Configure serial port (if needed)

The default config.yaml should work out of the box. If your robot uses a different serial port, edit it:

nano config.yaml

robot:
  com_port: /dev/ttyACM0    # Change if your port is different

Step 3: Check serial port

# Find your robot's serial port
ls -l /dev/ttyACM* /dev/ttyUSB*

# If your port is different, edit docker-compose.yml:
# Change the device mapping under 'commander' service

Step 4: Pull Docker images

docker-compose pull

Step 5: Start the system

# Start all services (frontend, API, commander)
docker-compose up -d

# Verify containers are running
docker-compose ps

Step 6: Access the interface

• Open browser to: http://localhost:3000
• API documentation: http://localhost:3001/docs

Useful commands:

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f frontend
docker-compose logs -f api
docker-compose logs -f commander

# Restart services
docker-compose restart

# Stop everything
docker-compose down

Pre-built images are automatically published for both amd64 and arm64 architectures:

• ghcr.io/jointaxis77/parol6-webcommander/frontend:latest
• ghcr.io/jointaxis77/parol6-webcommander/api:latest
• ghcr.io/jointaxis77/parol6-webcommander/commander:latest

If your robot uses a different serial port, update docker-compose.yml:

commander:
  devices:
    - "/dev/ttyUSB0:/dev/ttyUSB0"  # Change to your port

# Build all images
docker build -t parol6-frontend:local -f frontend/Dockerfile frontend/
docker build -t parol6-api:local -f Dockerfile.api .
docker build -t parol6-commander:local -f Dockerfile.commander .

# Update docker-compose.yml to use local images

# Start frontend, API, and commander
pm2 start ecosystem.config.js

# View logs
pm2 logs

# Stop all
pm2 stop all

Open your browser to:

• Frontend: http://localhost:3000
• API Docs: http://localhost:3001/docs

# Start only frontend (development mode)
cd frontend && npm run dev

# Start only API server
cd api && python3 fastapi_server.py

# Start only commander
python3 commander/commander.py

Ensure your user has permission to access the serial port:

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Log out and back in for changes to take effect

If using a USB camera:

camera:
  auto_start: true
  default_device: /dev/video0
  resolution:
    width: 640
    height: 480

To access from other devices on your network:

1. Find your server's IP address:

   hostname -I

2. Access from other devices: http://<your-ip>:3000

The frontend automatically detects the API at the same hostname on port 3001.

parol6/
├── api/                    # FastAPI backend
│   ├── fastapi_server.py   # Main API server
│   ├── robot_client.py     # UDP client to commander
│   └── websocket_manager.py
├── commander/              # Robot control
│   ├── commander.py        # Main control loop
│   └── commands.py         # Command processors
├── frontend/               # Next.js frontend
│   ├── app/
│   │   ├── page.tsx        # Main control interface
│   │   ├── components/     # React components
│   │   ├── hooks/          # Custom hooks
│   │   └── lib/            # Utilities & stores (includes IK solver)
│   └── public/
│       └── urdf/           # Robot URDF model & meshes
├── lib/                    # Shared Python libraries
│   ├── models/             # Data models
│   └── utils/              # Utilities
├── config.yaml             # System configuration
├── ecosystem.config.js     # PM2 process config
└── requirements.txt        # Python dependencies

Full API documentation available at http://localhost:3001/redoc

Robot Control:

• POST /api/robot/move/joints - Move robot to target joint angles
• POST /api/robot/execute/trajectory - Execute multi-waypoint trajectory
• POST /api/robot/home - Home the robot
• POST /api/robot/stop - Stop current motion
• POST /api/robot/clear-estop - Clear emergency stop

Gripper Control:

• POST /api/robot/gripper/electric - Control electric gripper

I/O Control:

• POST /api/robot/io/set - Set digital output state

Tool Management:

• GET /api/config/tools - List all tools
• POST /api/config/tools - Create new tool
• PATCH /api/config/tools/{tool_id} - Update tool
• DELETE /api/config/tools/{tool_id} - Delete tool
• POST /api/config/tools/{tool_id}/mount - Mount tool as active

Configuration:

• GET /api/config - Get system configuration
• PATCH /api/config - Update configuration

Camera:

• GET /api/camera/status - Camera status
• POST /api/camera/start - Start camera stream
• POST /api/camera/stop - Stop camera stream
• GET /api/camera/stream - MJPEG camera stream

Logs:

• GET /api/logs - Get system logs
• DELETE /api/logs - Clear logs

Connect to ws://localhost:3001/ws and subscribe to topics:

• status - Robot state (position, speed, I/O)
• logs - System logs
• camera - Camera feed (if enabled)

• Install all dependencies (Python, Node.js, PM2)
• Configure config.yaml (serial port, network IPs)
• Set frontend environment variables (frontend/.env.local)
• Test serial port access (ls -l /dev/ttyACM*)
• Build frontend (cd frontend && npm run build)
• Start PM2 processes (pm2 start ecosystem.config.js)
• Configure PM2 auto-start (pm2 startup && pm2 save)
• Test web interface access (http://localhost:3000)
• Test robot connection and basic movements
• Configure firewall rules (if needed)

IMPORTANT: This system controls a physical robot capable of causing injury.

• Always ensure emergency stop is accessible
• Keep workspace clear of people during operation
• Test new motions at low speed first
• Monitor robot during autonomous operation
• Respect joint limits and workspace boundaries
• Never bypass safety features

[Add your license here]

[Add support/contribution information]

Based on:

• PAROL6 Desktop Robot Arm by PCrnjak - Robot hardware design
• PAROL6 Python API by PCrnjak - Commander architecture and serial protocol
• PAROL6 Python API by Jepson2k - Extended functionality and improvements

Built with:

• FastAPI - API framework
• Next.js - Frontend framework
• React Three Fiber - 3D visualization