RoboticServices

Overview

The RoboticServices class serves as the main orchestrator for the Trash Classification AI System’s robotic arm operations. It manages multiple subsystems including sensors, perception, mapping, control, and safety, coordinating their interactions through a state machine architecture. Source: ~/workspace/source/arm_controller/src/main.py:294

Constructor

`init()`

Initializes all robotic subsystems and service state variables.

robot = RoboticServices()

Initialized Modules:

sensor_module: SensorModule instance for hardware sensors
perception_module: PerceptionModule for object detection
mapping_module: MappingModule for spatial mapping
control_module: ControlModule for motor control
safety_module: SafetyModule for safety checks
communication: CommunicationManager for serial communication

Internal State Variables:

Show Check Service State

check_mode_active (bool): Indicates if hardware check is active

Show Safety Service State

safety_mode_active (bool): Safety sequence activation flag
safety_shoulder (bool): Shoulder safety check completion status
safety_gripper (bool): Gripper safety check completion status
safety_service_loop (bool): Controls safety sequence loop

Show Scan Service State

scan_mode_active (bool): Scan operation activation flag
scan_start_time (float): Timestamp when scan began
scan_timeout (int): Maximum scan duration (30 seconds)
accumulated_rotation (float): Total rotation in degrees
last_angle (float): Previous angle measurement
scan_start (bool): Scan initialization flag
scan_update (bool): Scan update loop flag
scan_complete (bool): Scan completion status
scan_error (bool): Scan error status

Hardware Check Methods

`check_service()`

Verifies that all motors and sensors are properly installed and operational.

is_ready = robot.check_service()

return

bool

Returns True if all hardware components are installed and functional, False otherwise

Behavior:

Sets LED to green (READY) on success
Sets LED to red (ERROR) on failure
Checks both sensors and motors through safety module

Source: main.py:330

Safety Methods

Safety methods control critical hardware operations. Improper use can cause physical damage to the robotic arm or surrounding environment.

`safety_state_service()`

Executes a sequential safety verification process for shoulder and gripper mechanisms.

safety_complete = robot.safety_state_service()

return

bool

Returns True when the entire safety sequence (shoulder → gripper) completes successfully

Sequence:

Shoulder Safety Check
- Monitors bumper sensor
- Stops all motors if bumper pressed
- Reverses shoulder motor briefly
- Sets LED to ERROR (red) or WARNING (orange)
Gripper Safety Check (after shoulder completes)
- Monitors gripper motor current
- Activates gripper at 20 RPM
- Stops when current exceeds 0.3A
- Indicates object grip or mechanical limit
Completion
- Sets LED to READY (green)
- Updates internal state flags

Source: main.py:339

`reset_safety_sequence()`

Resets all safety sequence state variables to initial values.

robot.reset_safety_sequence()

Reset Variables:

safety_mode_active: False
safety_shoulder: False
safety_gripper: False
safety_service_loop: True

Source: main.py:363

Scanning Methods

`scan_service()`

Executes a complete 360° environmental scan to detect and map objects.

scan_done = robot.scan_service()

return

bool

Returns True when scan completes (360° rotation or timeout)

Process:

Calls start_scan_service() to initialize
Repeatedly calls update_scan_service() in loop
Continues until rotation reaches 360° or 30-second timeout
Returns mapped objects data

Source: main.py:374

`start_scan_service()`

Initializes the scanning operation.

started = robot.start_scan_service()

return

bool

Returns True if scan initialization succeeds, False if already complete

Actions:

Records start timestamp
Captures initial angle from inertial sensor
Activates base motor at 20 RPM
Sets LED to RUNNING (blue)
Updates scan_mode_active to True

Source: main.py:391

`update_scan_service()`

Processes sensor data during active scan operation.

is_complete = robot.update_scan_service()

return

bool

Returns True when scan is complete (360° or timeout), False to continue scanning

Operations:

Rotation Tracking
- Reads current angle from inertial sensor
- Calculates angular delta with wraparound handling
- Accumulates total rotation
Object Detection
- Processes distance and size sensor data
- Updates object detection state
- Changes LED color when objects detected (cyan)
Mapping
- Records object positions and dimensions
- Tracks object start/end angles
- Builds spatial map
Completion Check
- Stops motors when 360° reached or timeout
- Returns completion status

Source: main.py:404

`reset_scan_sequence()`

Resets all scan sequence state variables to initial values.

robot.reset_scan_sequence()

Reset Variables:

scan_mode_active: False
scan_start_time: 0
scan_timeout: 30
accumulated_rotation: 0
last_angle: 0
scan_start: True
scan_update: False
scan_complete: False

Source: main.py:428

Communication Methods

`process_raspberry_message(message: dict)`

Processes incoming JSON messages from the Raspberry Pi controller.

robot.process_raspberry_message(message)

message

dict

required

JSON message dictionary from Raspberry Pi

Message Format:

{
  "type": "check_service" | "safety_service" | "scan_service",
  "data": {}
}

Supported Message Types:

check_service

object

Triggers hardware verification check

{"type": "check_service", "data": {}}

Response:

{"type": "check_service", "data": {"state": "approved"}}

{"type": "check_service", "data": {"error": "Sensors or motors not installed"}}

safety_service

object

Initiates safety sequence (shoulder and gripper checks)

{"type": "safety_service", "data": {}}

Response:

{"type": "safety_service", "data": {"state": "approved"}}

scan_service

object

Starts 360° environmental scan

{"type": "scan_service", "data": {}}

Response:

{
  "type": "scan_service",
  "data": {
    "state": "complete",
    "objects": [
      {
        "center_angle": 45.5,
        "width": 12.3,
        "distance": 150,
        "max_size": 85
      }
    ]
  }
}

Source: main.py:443

Main Execution

`run()`

Main execution loop that initializes communication and processes service requests.

robot.run()

Process:

Initializes serial communication
Enters infinite loop
Reads and processes incoming messages
Executes active services (check, safety, scan)
Sends response messages
Displays status on brain screen
Handles exceptions and emergency stops

Error Handling:

Catches all exceptions
Displays errors on screen (first 20 chars)
Executes emergency stop on all motors

Source: main.py:464

Service State Management

The RoboticServices class uses a flag-based state machine:

# Service activation pattern
if self.check_mode_active:
    result = self.check_service()
    # Send response
    self.check_mode_active = False

if self.safety_mode_active:
    result = self.safety_state_service()
    # Send response if complete
    
if self.scan_mode_active:
    result = self.scan_service()
    # Send response if complete

State Transitions:

Activated by incoming messages via process_raspberry_message()
Deactivated after service completion or error
Multiple services cannot run simultaneously
Each service has internal sub-states for step-by-step execution

Usage Example

from vex import *
import main

# Initialize robotic services
robot = main.RoboticServices()

# Start main execution loop
robot.run()

# System will now respond to messages from Raspberry Pi:
# - check_service: Verify hardware
# - safety_service: Run safety checks
# - scan_service: Perform environmental scan

SensorModule - Hardware sensor management
ControlModule - Motor control operations
CommunicationManager - Serial communication protocol

Core Classes

Segmentation

Drawing Components

Robotics

Overview

Constructor

`init()`

Hardware Check Methods

`check_service()`

Safety Methods

`safety_state_service()`

`reset_safety_sequence()`

Scanning Methods

`scan_service()`

`start_scan_service()`

`update_scan_service()`

`reset_scan_sequence()`

Communication Methods

`process_raspberry_message(message: dict)`

Main Execution

`run()`

Service State Management

Usage Example

Build docs developers (and LLMs) love

Core Classes

Segmentation

Drawing Components

Robotics

​Overview

​Constructor

​__init__()

​Hardware Check Methods

​check_service()

​Safety Methods

​safety_state_service()

​reset_safety_sequence()

​Scanning Methods

​scan_service()

​start_scan_service()

​update_scan_service()

​reset_scan_sequence()

​Communication Methods

​process_raspberry_message(message: dict)

​Main Execution

​run()

​Service State Management

​Usage Example

​Related Classes

Build docs developers (and LLMs) love

Overview

Constructor

`init()`

Hardware Check Methods

`check_service()`

Safety Methods

`safety_state_service()`

`reset_safety_sequence()`

Scanning Methods

`scan_service()`

`start_scan_service()`

`update_scan_service()`

`reset_scan_sequence()`

Communication Methods

`process_raspberry_message(message: dict)`

Main Execution

`run()`

Service State Management

Usage Example

Related Classes