Skip to main content

MicroPython API Reference

This reference is generated from the same documentation data used by the app.

Dotbot API Reference

This reference is generated from the same documentation data used by the app.

dotbot.arm

Arm control

dotbot.arm.setAngle(angle, speed = 1.0 - TODO, maxAcceleration = 10.0 - TODO)

Move the flipper/arm to a target angle.

Queues an asynchronous motion of the arm to the requested angle using the internal DC servo controller. The call returns immediately; it does not block until the arm reaches the target.

Parameters

  • angle: float - Target arm angle in degrees.
  • speed: float = 1.0 - TODO - Normalized speed factor for this move (1.0 = default).
  • maxAcceleration: float = 10.0 - TODO - Maximum acceleration for this move (implementation-defined units).

Returns

None - No return value.

Examples

Basic arm movement
dotbot.arm.setAngle(45)
Fast arm movement
dotbot.arm.setAngle(90, 2.0)
dotbot.arm.isCalibrated()

Check if the arm has been calibrated.

Returns True if the internal DC servo reports that the arm calibration procedure has been completed.

Returns

bool - True if the arm is calibrated, False otherwise.

Examples

Guard movement on calibration state
if not dotbot.arm.isCalibrated():
    dotbot.arm.calibrate()

# now safe to move
dotbot.arm.setAngle(30)
dotbot.arm.calibrate()

Start the arm calibration routine.

Triggers the DC servo calibration process. The call returns immediately; the calibration runs asynchronously.

Returns

None - No return value.

Examples

Simple calibration call
dotbot.arm.calibrate()
# wait a bit, then start moving the arm

dotbot.battery

Battery & power

dotbot.battery.getCharge()

Get the estimated battery state of charge in percent.

Returns the battery state of charge (SOC) as an integer percentage, 0–100, based on the charger/fuel-gauge readings.

Returns

int - Battery charge percentage from 0 to 100.

Examples

Show battery percentage
soc = dotbot.battery.getCharge()
print("Battery:", soc, "%")
dotbot.battery.getVoltage()

Get the current battery voltage in volts.

Reads the battery voltage from the charger in millivolts, converts it to volts, and returns it as a float.

Returns

float - Battery voltage in volts.

Examples

Log raw battery voltage
v = dotbot.battery.getVoltage()
print("Battery voltage:", v, "V")
dotbot.battery.isCharging()

Check if the robot is currently charging.

Returns True if the charger reports that the battery is being charged.

Returns

bool - True if the charger is actively charging the battery.

Examples

Avoid driving while charging
if dotbot.battery.isCharging():
    print("Unplug charger before driving!")
dotbot.battery.isLowBattery()

Check if the battery level is considered low.

Returns True if the charger/fuel-gauge indicates that the battery level is below the low-battery threshold.

Returns

bool - True if battery is low, False otherwise.

Examples

Warn the user on low battery
if dotbot.battery.isLowBattery():
    print("Warning: low battery, please charge soon.")

dotbot.colorSensor

Color sensor

dotbot.colorSensor.isPresent()

Check if the color sensor is present and responding.

Probes the color sensor over I2C and returns True if the device responds correctly.

Returns

bool - True if the color sensor is detected, False otherwise.

Examples

Ensure sensor is connected
if not dotbot.colorSensor.isPresent():
    print("Color sensor not detected!")
dotbot.colorSensor.getColor()

Read the current color as a 32-bit HEX value.

Reads the current color from the sensor and returns it as a 32-bit integer in HEX format, typically 0xRRGGBB or implementation-defined.

Returns

int - 32-bit color value (e.g. 0xRRGGBB).

Examples

Print color in hex
c = dotbot.colorSensor.getColor()
print("Color:", hex(c))
dotbot.colorSensor.getColorName()

Get a coarse color classification as an enum value.

Returns an implementation-defined integer enum representing the detected color class (e.g. black, white, red, green, blue). The exact mapping depends on firmware.

Returns

int - Integer enum value for the detected color class.

Examples

Use color enum
color_id = dotbot.colorSensor.getColorName()
print("Color ID:", color_id)
# Map IDs to names on the app/host side.
dotbot.colorSensor.sampleBlackCalibration()

Calibrate the sensor for a black reference surface.

Triggers a calibration step using the current reading as the 'black' reference. Returns 0 on success and -1 on failure.

Returns

int - 0 on success, -1 on failure.

Examples

Calibrate black
print("Place sensor over black surface...")
res = dotbot.colorSensor.sampleBlackCalibration()
print("Result:", res)
dotbot.colorSensor.sampleWhiteCalibration()

Calibrate the sensor for a white reference surface.

Triggers a calibration step using the current reading as the 'white' reference. Returns 0 on success and -1 on failure.

Returns

int - 0 on success, -1 on failure.

Examples

Calibrate white
print("Place sensor over white surface...")
res = dotbot.colorSensor.sampleWhiteCalibration()
print("Result:", res)
dotbot.colorSensor.setBacklight(level)

Set the sensor backlight brightness.

Controls the integrated backlight brightness of the color sensor. Level is given in percent from 0 to 100.

Parameters

  • level: int - Backlight level in percent (0–100).

Returns

None - No return value.

Examples

Dim and brighten backlight
dotbot.colorSensor.setBacklight(10)
# ... later ...
dotbot.colorSensor.setBacklight(80)

dotbot.drive

Drive & motion

dotbot.drive.forward(distance, speed = 5.0 - TODO, acceleration = 5.0 - TODO)

Drive the robot forward by a given distance.

Commands the chassis to drive forward by the specified distance in millimetres, using the low-level DC chassis controller. This call is non-blocking: it starts the movement and returns immediately.

Parameters

  • distance: float - Distance to travel forward in millimetres.
  • speed: float = 5.0 - TODO - Nominal drive speed in internal units (typically wheel revolutions per second).
  • acceleration: float = 5.0 - TODO - Maximum acceleration in internal units.

Returns

None - No return value.

Examples

Drive forward 200 mm
dotbot.drive.forward(200)
# start a 200 mm forward motion
Drive faster with custom speed
dotbot.drive.forward(500, speed=8.0, acceleration=6.0)
dotbot.drive.backward(distance, speed = 5.0 - TODO, acceleration = 5.0 - TODO)

Drive the robot backward by a given distance.

Commands the chassis to drive backward by the specified distance in millimetres. Internally this is implemented as a negative distance command to the chassis controller. Non-blocking: starts the motion and returns.

Parameters

  • distance: float - Distance to travel backward in millimetres.
  • speed: float = 5.0 - TODO - Nominal drive speed in internal units.
  • acceleration: float = 5.0 - TODO - Maximum acceleration in internal units.

Returns

None - No return value.

Examples

Back up a little
dotbot.drive.backward(100)
dotbot.drive.rotate(angle, speed = 5.0 - TODO, acceleration = 5.0 - TODO)

Rotate the robot in place by a given angle.

Commands the chassis to perform a rotation in place by the specified angle in degrees. Positive angles rotate one way and negative angles rotate the opposite way (exact convention depends on firmware/IMU configuration). Non-blocking.

Parameters

  • angle: float - Rotation angle in degrees (positive/negative for direction).
  • speed: float = 5.0 - TODO - Rotation speed in internal units.
  • acceleration: float = 5.0 - TODO - Maximum rotational acceleration in internal units.

Returns

None - No return value.

Examples

Turn 90 degrees
dotbot.drive.rotate(90)
Turn slowly
dotbot.drive.rotate(-45, speed=2.0)
dotbot.drive.stop()

Immediately stop all drive motors.

Stops the chassis motors using the low-level DC driver. This cancels any ongoing distance or rotation profile.

Returns

None - No return value.

Examples

Emergency stop
dotbot.drive.stop()
dotbot.drive.info()

Print low-level chassis debug information.

Dumps internal DC driver/chassis state to the log/console, useful for debugging motor control and odometry.

Returns

None - No return value.

Examples

Check drive status
dotbot.drive.info()
dotbot.drive.setSpeed(speedLeft, speedRight)

Set raw left and right wheel speeds.

Switches the DC driver into speed-control mode and sets target speeds for the left (A) and right (B) motors. This is a low-level command and does not enforce distance or heading.

Parameters

  • speedLeft: float - Target speed for the left wheel in internal units.
  • speedRight: float - Target speed for the right wheel in internal units.

Returns

None - No return value.

Examples

Drive forward slowly using raw speeds
dotbot.drive.setSpeed(0.5, 0.5)
Spin in place
dotbot.drive.setSpeed(1.0, -1.0)

dotbot.imu

IMU

dotbot.imu.getHeading()

Get the current robot heading in degrees.

Returns the current robot heading as reported by the IMU, in degrees. The range and wrapping are firmware-defined (typically 0–360° or −180–180°).

Returns

float - Heading angle in degrees.

Examples

Print heading
h = dotbot.imu.getHeading()
print("Heading:", h, "deg")
dotbot.imu.reset()

Zero the IMU heading at the current orientation.

Sets the current robot orientation as the new zero heading reference. After calling this, a subsequent getHeading() call will be close to 0°.

Returns

None - No return value.

Examples

Reset heading and read again
dotbot.imu.reset()
print(dotbot.imu.getHeading())  # should be near 0
dotbot.imu.calibrate()

Start IMU calibration.

Starts the IMU calibration routine. Depending on firmware, this may require keeping the robot still or moving it slowly according to instructions.

Returns

None - No return value.

Examples

Run calibration
print("Starting IMU calibration...")
dotbot.imu.calibrate()

dotbot.lcd

LCD display

dotbot.lcd.setBacklight(level)

Set the LCD backlight brightness.

Sets the backlight brightness of the LCD display. The level should be in percent, from 0 (off) to 100 (full brightness).

Parameters

  • level: int - Backlight level in percent (0–100).

Returns

None - No return value.

Examples

Dim the screen
dotbot.lcd.setBacklight(20)
Full brightness
dotbot.lcd.setBacklight(100)
dotbot.lcd.setImage(path)

Show an image file on the LCD.

Loads and displays an image file on the LCD from the given path in the robot's filesystem.

Parameters

  • path: str - Filesystem path to the image file (e.g. '/images/logo.bmp').

Returns

None - No return value.

Examples

Show logo
dotbot.lcd.setImage("/images/logo.bmp")
dotbot.lcd.setAnimation(path)

Play an animation file on the LCD.

Loads and starts playing an animation file on the LCD from the given path. The exact supported formats and looping behavior depend on the firmware implementation.

Parameters

  • path: str - Filesystem path to the animation file.

Returns

None - No return value.

Examples

Play idle animation
dotbot.lcd.setAnimation("/anim/idle.anim")
dotbot.lcd.setText(text)

Show a text string on the LCD.

Displays a text string on the LCD. The exact position, font and layout are defined by the firmware UI layer.

Parameters

  • text: str - Text to display on the LCD.

Returns

None - No return value.

Examples

Display hello message
dotbot.lcd.setText("Hello from DotBot!")
dotbot.lcd.setScreen(screen)

Switch to a different LCD screen.

Selects which pre-defined screen the LCD should show. The meaning of each screen index is defined by the firmware UI (e.g. home, debug, battery, custom game screens).

Parameters

  • screen: int - Screen index to activate.

Returns

None - No return value.

Examples

Switch to home screen
dotbot.lcd.setScreen(0)
dotbot.lcd.getScreen()

Get the currently active LCD screen index.

Returns the index of the currently active screen, as previously set by setScreen().

Returns

int - Current screen index.

Examples

Print current screen
print("Current screen:", dotbot.lcd.getScreen())

dotbot.leds

Controls DotBot's RGB LEDs (top and bottom).

dotbot.leds.setState(enabled)

Enable or disable all LEDs.

Parameters

  • enabled: bool - True to turn LEDs on, False to turn them off.

Returns

None - No return value.

Examples

Disable all leds
dotbot.leds.setState(False)
dotbot.leds.setColor(color, transition_time)

Set color of all LEDs with an optional fade transition.

Parameters

  • color: int | tuple - LED color as 0xRRGGBB or (r, g, b) with each channel 0–255.
  • transition_time: float - Fade duration in seconds. 0 or omitted means a default short transition (~100 ms).

Returns

None - No return value.

Examples

solid red, short fade
dotbot.leds.setColor(0xFF0000)
green, 0.5 second fade
dotbot.leds.setColor((0, 255, 0), 0.5)
blue instantly
dotbot.leds.setColor(0x0000FF, 0)
dotbot.leds.setTopColor(color, transition_time)

Set color of the top LED ring/segment only.

Parameters

  • color: int | tuple - LED color as 0xRRGGBB or (r, g, b) with each channel 0–255.
  • transition_time: float - Fade duration in seconds. 0 or omitted means a default short transition (~100 ms).

Returns

None - No return value.

Examples

Set top led to blue color
dotbot.leds.setTopColor(0x0000FF)
Slowly fade out bottom leds
dotbot.leds.setTopColor((0, 0, 0), 0.2)
dotbot.leds.setBottomColor(color, transition_time)

Set color of the bottom LED ring/segment only.

Parameters

  • color: int | tuple - LED color as 0xRRGGBB or (r, g, b) with each channel 0–255.
  • transition_time: float - Fade duration in seconds. 0 or omitted means a default short transition (~100 ms).

Returns

None - No return value.

Examples

Set bottom led to blue color
dotbot.leds.setBottomColor(0x0000FF)
Slowly fade out bottom leds
dotbot.leds.setBottomColor((0, 0, 0), 0.2)

dotbot.speaker

Controls DotBot's speaker: play sounds, stop playback, and set volume.

dotbots.speaker.playSound(path)

Play a sound file from storage.

Parameters

  • path: str - Path to the audio file on the robot (e.g. '/storage/audio/bing.mp3').

Returns

int - Driver status code (0 on success, negative on error).

Examples

Play a beep
dotbot.speaker.playSound('/storage/audio/bing.mp3')
Play startup sound
dotbot.speaker.playSound('/storage/audio/boot.mp3')
dotbot.speaker.stop()

Stop any currently playing sound.

Returns

int - Driver status code (0 on success, negative on error).

Examples

Stop audio
dotbot.speaker.stop()
dotbot.speaker.setVolume(volume)

Set speaker volume.

Parameters

  • volume: int - Volume level. Recommended logical range 0–100 (0 = mute, 100 = max). Exact mapping depends on firmware.

Returns

int - Driver status code (0 on success, negative on error).

Examples

Medium volume
dotbot.speaker.setVolume(50)
dotbot.speaker.say(text)

Placeholder for future text-to-speech support.

Parameters

  • text: str - Text to speak (not yet implemented).

Returns

int - Currently always returns -1 (not implemented).

Examples

speak text
dotbot.speaker.say('Hello DotBot!')

dotbot.system

System-level functions for managing the DotBot runtime (reboot, memory, uptime).

dotbot.system.reboot()

Reboot the robot.

Returns

None - No return value. (Not implemented yet.)

Examples

reboot the robot
dotbot.system.reboot()
dotbot.system.meminfo()

Return remaining free heap memory.

Returns

int - Free heap size in bytes.

Examples

# -> 243512 (example output: bytes of free RAM)
dotbot.system.meminfo()
dotbot.system.uptime()

Return system uptime.

Returns

int - Uptime in microseconds since boot (ESP-IDF `esp_timer_get_time()`).

Examples

# -> 123456789 (µs since boot)
dotbot.system.uptime()