Usage Guide

This guide shows how to configure MQTT, build a VirtualRobot, use motion control, read sensors, send communications, and control indicators.

Configure MQTT

from robot import MQTTSettings

MQTTSettings.server = "localhost"
MQTTSettings.port = 1883
MQTTSettings.user_name = ""
MQTTSettings.password = ""
MQTTSettings.channel = "v1"

Subclass VirtualRobot

from robot import VirtualRobot
from robot.interfaces import RobotState

class MyRobot(VirtualRobot):
    def loop(self):
        if self.state == RobotState.RUN:
            # read sensors, move, and communicate here
            self.delay(1000)

robot = MyRobot(1, 0, 0, 90)
robot.start()
robot.run()

Motion Control

Use MotionController directly or through a Robot via self.motion.

from robot import MotionController

motion = MotionController()  # standalone with a stub coordinate
motion.move(150, 150, duration=1000)   # forward 1 second
motion.rotate_degree(120, 90)          # rotate 90 degrees

In a robot loop:

self.motion.move(180, 180, duration=500)
self.motion.rotate_degree(160, -45)

Configure geometry and speeds via robot.configs.robot_settings.RobotSettings.

Sensors

Sensors are initialized in Robot.setup() and available on the robot instance.

Distance:

dist_cm = self.dist_sensor.get_distance()

Color:

rgb = self.color_sensor.get_color()  # RGBColorType
print(rgb.get_r(), rgb.get_g(), rgb.get_b())

Proximity (multi-angle):

# Optionally configure angles first
self.proximity_sensor.set_angles([0, 45, 90, 135, 180])
reading = self.proximity_sensor.get_proximity()
print(reading.distances())
for c in reading.colors():
    print(c.to_string_color())

Communications

Simple broadcast-like messages:

self.simple_comm.send_message("hello swarm")
self.simple_comm.send_message_with_distance("tag", distance=10)

Directed messages (to controller routing topic):

self.directed_comm.send_message("to leader")

Override communication_interrupt(self, msg: str) in your robot to handle inbound messages.

Indicators (NeoPixel)

self.neo_pixel.change_color(0, 128, 255)

Extensibility Guidelines

  • Subclass VirtualRobot to add behaviors; implement loop() and optionally sensor_interrupt/communication_interrupt.

  • New sensors/indicators: follow robot.sensors.abstract_sensor / robot.indicators.abstract_indicator. Subscribe to topics in __init__, implement handle_subscription, and publish using RobotMqttClient.

  • MQTT is namespaced by MQTTSettings.channel (e.g., v1/robot/create), mirroring the original Java design.