Skip to main content

​
Overview

This tutorial will guide you through connecting to the robot, running the main menu, executing a scan operation, and performing your first pick and place operation.
Prerequisites: Make sure your VEX brain is connected to /dev/ttyACM1 and your camera is connected.

​
Complete Workflow

1

Initialize the Robot

Create a Robot instance and configure the connection parameters:
from arm_system.main import Robot
import logging as log

log.basicConfig(level=log.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

# Initialize robot with default settings
robot = Robot()
The robot automatically initializes:
  • Serial connection manager (115200 baud rate)
  • Scan result callbacks
  • Placement zones for different object types
The robot comes pre-configured with placement zones:
placement_zones = {
    'apple': {'angle': 90, 'distance': 200},
    'orange': {'angle': 180, 'distance': 200},
    'bottle': {'angle': 45, 'distance': 200},
    'default': {'angle': 270, 'distance': 200},
}
You can modify these zones when initializing your robot.
2

Connect to the Robot

Start the robot and connect to the VEX brain:
robot.run()
This will:
  1. Establish a serial connection to /dev/ttyACM1
  2. Start the message reading thread
  3. Launch the interactive main menu
Expected output:
2026-03-07 10:30:15 - INFO - connected to VEX brain

=== Main menu ===
 [c] check service
 [s] safety service
 [n] scan service
 [p] pick & place service
 [q] exit
input command:
3

Check System Status

Before operating the robot, verify all systems are operational:Press c to run the check service:
# Internally calls:
robot.serial_manager.send_message('check_service', {})
Expected output:
2026-03-07 10:30:20 - INFO - check_service status:
state: ready
If the state is not “ready”, troubleshoot the VEX brain connection before proceeding.
4

Execute a Scan Operation

Scan the environment to detect objects:Press n to start scanning:
# This triggers:
robot.handle_scan_command()
The scan process:
  1. Clears previous scan results
  2. Sends scan command with speed parameter (20)
  3. Waits for the robot to complete rotation
  4. Captures images at each detected position
  5. Runs object detection on each image
  6. Compiles results with placement zones
Expected output:
2026-03-07 10:30:25 - INFO - scanning in progress...
2026-03-07 10:30:28 - INFO - Scan Data - Object Detected: Angle: 45° Distance: 150mm
2026-03-07 10:30:28 - INFO - class: apple
2026-03-07 10:30:32 - INFO - Scan Data - Object Detected: Angle: 120° Distance: 180mm
2026-03-07 10:30:32 - INFO - class: orange
2026-03-07 10:30:45 - INFO - ¡scan completed!

=== objects scanned: (2) ===
Obj 1 -> angle: 45°, distance: 150mm, class: apple, conf: 0.89
Obj 2 -> angle: 120°, distance: 180mm, class: orange, conf: 0.92
5

Pick and Place an Object

Now select and move an object to its designated zone:Press p to start pick and place:
# This triggers:
robot.handle_pick_place_command()
Interactive selection:
=== OBJECTS DETECTED LIST ===
[1] angle=45° dist=150mm class=apple conf=0.89
[2] angle=120° dist=180mm class=orange conf=0.92
[0] cancelar

select the object you want to take: 1
After selecting object 1 (apple):Expected output:
2026-03-07 10:31:00 - INFO - init pick & place to object: 1:
2026-03-07 10:31:00 - INFO - angle: 45°
2026-03-07 10:31:00 - INFO - distance: 150 mm

2026-03-07 10:31:00 - INFO - execution movements:
2026-03-07 10:31:00 - INFO - movement: base
2026-03-07 10:31:02 - INFO - -> ¡Movement base completed!
2026-03-07 10:31:02 - INFO - movement: arm
2026-03-07 10:31:04 - INFO - -> ¡Movement arm completed!
2026-03-07 10:31:04 - INFO - movement: gripper
2026-03-07 10:31:05 - INFO - -> ¡Movement gripper completed!
2026-03-07 10:31:05 - INFO - movement: arm
2026-03-07 10:31:06 - INFO - -> ¡Movement arm completed!
2026-03-07 10:31:06 - INFO - ¡pick completed!

2026-03-07 10:31:06 - INFO - execution movements:
2026-03-07 10:31:06 - INFO - movement: base
2026-03-07 10:31:08 - INFO - -> ¡Movement base completed!
2026-03-07 10:31:08 - INFO - movement: arm
2026-03-07 10:31:10 - INFO - -> ¡Movement arm completed!
2026-03-07 10:31:10 - INFO - movement: gripper
2026-03-07 10:31:11 - INFO - -> ¡Movement gripper completed!
2026-03-07 10:31:11 - INFO - movement: arm
2026-03-07 10:31:12 - INFO - -> ¡Movement arm completed!
2026-03-07 10:31:12 - INFO - movement: base
2026-03-07 10:31:14 - INFO - -> ¡Movement base completed!
2026-03-07 10:31:14 - INFO - ¡pick and place completed!
The apple is now placed in its designated zone at 90° and 200mm distance.
6

Exit the System

When finished, gracefully shut down:Press q to exit:
# This closes the serial connection
robot.serial_manager.close()
Expected output:
2026-03-07 10:32:00 - INFO - closing serial connection.
2026-03-07 10:32:00 - INFO - Serial connection closed

​
Complete Script

Here’s the full script to get started:
main.py
from arm_system.main import Robot
import logging as log

log.basicConfig(level=log.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

if __name__ == '__main__':
    robot = Robot()
    robot.run()
Run it with: 
python main.py

​
Troubleshooting

Error: Error connecting to serial portSolutions:
  • Verify VEX brain is powered on
  • Check USB connection
  • Confirm port is /dev/ttyACM1 (may vary)
  • Check permissions: sudo chmod 666 /dev/ttyACM1
  • Try different USB port
Error: scanning timeoutSolutions:
  • Ensure the base motor is functioning
  • Check that scan speed is not too high (default: 20)
  • Verify encoder feedback from VEX brain
  • Increase timeout in code: wait(timeout=120)
Message: scanning completed without object detectionSolutions:
  • Check camera connection and focus
  • Ensure proper lighting conditions
  • Verify objects are in detection range (150-250mm)
  • Lower confidence threshold in ImageProcessor
  • Check if objects are in supported classes (apple, orange, bottle)
Error: error in movementSolutions:
  • Run safety service: press s in menu
  • Check joint limits and physical obstructions
  • Verify motor connections
  • Ensure gripper is functioning
  • Check power supply to VEX brain

​
Next Steps

Serial Communication

Learn how to customize serial messages and callbacks

Vision & Inference

Understand the object detection pipeline

Pick and Place

Deep dive into motion planning and execution

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us