API

A Python adapter module for Roomba Open Interface

This module is based on the document: iRobot® Roomba 500 Open Interface (OI) Specification - Link https://www.irobot.lv/uploaded_files/File/iRobot_Roomba_500_Open_Interface_Spec.pdf

class pyroombaadapter.PyRoombaAdapter(port, bau_rate=115200, time_out_sec=1.0, wheel_span_mm=235.0)

Adapter class for Roomba Open Interface

The constructor connects serial port and change the mode to safe mode

Parameters

• port (string) – Serial port path

• bau_rate (int) – bau rate of serial connection (default=115200)

• time_out_sec (float) – read time out of serial connection [sec] (default=1.0)

• wheel_span_mm (float) – wheel span of Roomba [mm] (default=235.0)

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)

__del__()

Destructor of PyRoombaAdapter class

The Destructor make Roomba move to passive mode and close serial connection

change_mode_to_full()

Change mode to full mode

Full mode turns off the cliff, wheel-drop and internal charger safety features. In Full mode, Roomba executes any command that you send it, even if the internal charger is plugged in, or command triggers a cliff or wheel drop condition.

• Available in modes: Passive, Safe, or Full

change_mode_to_passive()

Change mode to passive mode

Roomba beeps once to acknowledge it is starting from “off” mode.

• Available in modes: Passive, Safe, or Full

change_mode_to_safe()

Change mode to safe mode

Safe mode turns off all LEDs. If a safety condition occurs, Roomba reverts automatically to Passive mode.

• Available in modes: Passive, Safe, or Full

data_stream_read()

reads data stream

Reads stream of sensor data packets from Roomba.

Returns

list with sensors values or empty list on error

Examples:

>>> adapter = PyRoombaAdapter("/dev/ttyUSB0")
>>> adapter.start_data_stream(["Charging State", "Voltage", "Temperature"])
>>> print(adapter.read_data_stream()) # [0, 15530, 20]

data_stream_start(sensors_list)

starts data stream

This function issues command which starts a stream of data packets. The provided list of packets is sent every 15 ms, which is the rate Roomba uses to update data.

Parameters

sensors_list (list) – One or more from following sensors: [“Charging State”, “Voltage”, “Current”, “Temperature”, “Battery Charge”, “Battery Capacity”, “OI Mode”]

Examples:

>>> adapter = PyRoombaAdapter("/dev/ttyUSB0")
>>> adapter.start_data_stream(["Charging State", "Voltage", "Temperature"])
>>> print(adapter.read_data_stream()) # list with values

data_stream_stop()

stops data stream

Stops data stream and resets sensors list.

move(velocity, yaw_rate)

control roomba at the velocity and the rotational speed (yaw rate)

Note:

The Roomba keep a control command until receiving next command

• Available in modes: Safe or Full

• Changes mode to: No Change

• Special cases:

  • Straight = 32768 or 32767 = hex 8000 or 7FFF

  • Turn in place clockwise = -1

  • Turn in place counter-clockwise = 1

Parameters

• velocity (float) – velocity (m/sec)

• yaw_rate (float) – yaw rate (rad/sec)

Examples:

>>> import math
>>> import time
>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.move(0, math.radians(-10)) # rotate to right side
>>> time.sleep(1.0) # keep rotate
>>> adapter.move(0.1, 0.0) # move straight with 10cm/sec

request_angle()

Requests the angular displacement since it was last checked.

Returns the angle in radians that the Roomba has turned since the angle was last requested. Counter-clockwise is defined positive.

Returns

Output range ± 571.9 rad

request_capacity()

requests estimated battery capacity

Returns the estimated charge capacity of Roomba’s battery in milliamp-hours (mAh).

Returns

Capacity in range: 0 – 65535 mAh

request_charge()

requests battery charge

Returns the current charge of Roomba’s battery in milliamp-hours (mAh). The charge value decreases as the battery is depleted during running and increases when the battery is charged.

Returns

Charge in range: 0 – 65535 mAh

request_charging_state()

requests charging state

This function returns one of following Roomba’s current charging states: 0 = Not charging, 1 = Reconditioning Charging, 2 = Full Charging, 3 = Trickle Charging, 4 = Waiting, 5 = Charging Fault Condition

Returns

State 0-5

request_current()

requests battery current

The current in milliamps (mA) flowing into or out of Roomba’s battery. Negative currents indicate that the current is flowing out of the battery, as during normal running. Positive currents indicate that the current is flowing into the battery, as during charging.

Returns

Current in range: -32768 – 32767 mA

request_distance()

Requests the Roomba’s total distance traveled since it was last checked.

Returns distance traveled in millimeters (mm) since the distance was last requested. Average between both wheel distances.

Returns

Output range ± 32768 mm

request_encoder_counts()

Requests the raw Roomba encoder counts.

Returns a tuple containing the following: (left count, right count). Linear distance traversed by each wheel is defined by the following: distance = (π * 72.0 / 508.8) * count.

Returns

A tuple of (left count, right count) in range -32767 - 32768

request_oi_mode()

requests corrent OI mode

This function returns the current OI mode. Modes see in following table: 0 = Off, 1 = Passive, 2 = Safe, 3 = Full

Returns

State 0-3

request_temperature(celsius=True)

requests battery temperature

This command requests the temperature of Roomba’s battery in degrees Celsius.

Parameters

celsius (bool) – true if celsius, false for fahrenheit

Returns

Temperature in range: -128 – 127 Celsius or converted in Fahrenheit

request_voltage()

requests battery voltage

This function returns the current voltage of Roomba’s battery in millivolts (mV).

Returns

Voltage in range: 0 – 65535 mV

send_buttons_cmd(clean=False, spot=False, dock=False, minute=False, hour=False, day=False, schedule=False, clock=False)

send buttons command

This command lets you push Roomba’s buttons. The buttons will automatically release after 1/6th of a second.

Note:

• This API doesn’t work on Roomba 690 Model

Parameters

• clean (bool) – clean button on

• spot (bool) – spot button on

• dock (bool) – dock button on

• minute (bool) – minute button on

• hour (bool) – hour button on

• day (bool) – day button on

• schedule (bool) – schedule button on

• clock (bool) – clock button on

send_drive_cmd(roomba_mm_sec, roomba_radius_mm)

send drive command

This command controls Roomba’s drive wheels. The radius is measured from the center of the turning circle to the center of Roomba. A Drive command with a positive velocity and a positive radius makes Roomba drive forward while turning left. A negative radius makes Roomba turn toward the right. Special cases for the radius make Roomba turn in place or drive straight. A negative velocity makes Roomba drive backward.

Parameters

• roomba_mm_sec (float) – the average velocity of the drive wheels in millimeters per second (-500 – 500 mm/s)

• roomba_radius_mm (float) – the radius in millimeters at which Roomba will turn. (-2000 – 2000 mm)

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.send_drive_cmd(-100, -1000) # back to the right side
>>> sleep(2.0) # keep 2 sec

send_drive_direct(right_mm_sec, left_mm_sec)

send drive direct command

This command lets you control the forward and backward motion of Roomba’s drive wheels independently. A positive velocity makes that wheel drive forward, while a negative velocity makes it drive backward.

• Available in modes: Safe or Full

Parameters

• right_mm_sec (float) – the velocity of the right drive wheels in millimeters per second (-500 – 500 mm/s)

• left_mm_sec (float) – the velocity of the left drive wheels in millimeters per second (-500 – 500 mm/s)

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.send_drive_direct(10, 100) # move right forward
>>> sleep(2.0) # keep 2 sec

send_drive_pwm(right_pwm, left_pwm)

send drive pwm command

This command lets you control the forward and backward motion of Roomba’s drive wheels independently. It takes four data bytes, which are interpreted as two 16-bit signed values using two’s complement. A positive PWM makes that wheel drive forward, while a negative PWM makes it drive backward.

• Available in modes: Safe or Full

Parameters

• right_pwm (int) – Right wheel PWM (-255 – 255)

• left_pwm (int) – Left wheel PWM (-255 - 255)

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.send_drive_pwm(-200, -200) # move backward
>>> sleep(2.0) # keep 2 sec

send_moters_cmd(main_brush_on, main_brush_direction_is_ccw, side_brush_on, side_brush_direction_is_inward, vacuum_on)

send moters command

This command controls the motion of Roomba’s main brush, side brush, and vacuum independently. Motor velocity cannot be controlled with this command, all motors will run at maximum speed when enabled. The main brush and side brush can be run in either direction. The vacuum only runs forward.

Parameters

• main_brush_on (bool) – main brush on or off

• main_brush_direction_is_ccw (bool) – main brush direction, clockwise or counter-clockwise(default)

• side_brush_on (bool) – side brush on or off

• side_brush_direction_is_inward (bool) – side brush direction, inward(default) or outward

• side_brush_on – side brush on or off

• vacuum_on (bool) – vacuum on or off

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.send_moters_cmd(False, True, True, True, False) # side brush is on, and it rotates inward
>>> sleep(2.0) # keep 2 sec

send_play_cmd(song_number)

send play command

This command lets you select a song to play from the songs added to Roomba using the Song command. You must add one or more songs to Roomba using the Song command in order for the Play command to work.

Parameters

song_number (int) – (0-4)

Examples:

>>> adapter = PyRoombaAdapter("/dev/ttyUSB0")
>>> # note names
>>> f4 = 65
>>> a4 = 69
>>> c5 = 72
>>> # note lengths
>>> MEASURE = 160
>>> HALF = int(MEASURE / 2)
>>> Q = int(MEASURE / 4)
>>> Ed = int(MEASURE * 3 / 16)
>>> S = int(MEASURE / 16)
>>> adapter.send_song_cmd(0, 9,
>>>             [a4, a4, a4, f4, c5, a4, f4, c5, a4],
>>>             [Q, Q, Q, Ed, S, Q, Ed, S, HALF]) # set song
>>> adapter.send_play_cmd(0) # play song
>>> sleep(10.0) # keep playing

send_pwm_moters(main_brush_pwm, side_brush_pwm, vacuum_pwm)

send pwm moters

This command control the speed of Roomba’s main brush, side brush, and vacuum independently. With each data byte, you specify the duty cycle for the low side driver (max 128). For example, if you want to control a motor with 25% of battery voltage, choose a duty cycle of 128 * 25% = 32. The main brush and side brush can be run in either direction. The vacuum only runs forward. Positive speeds turn the motor in its default (cleaning) direction. Default direction for the side brush is counterclockwise. Default direction for the main brush/flapper is inward.

• Available in modes: Safe or Full

Parameters

• main_brush_pwm (int) – main brush PWM (-127 - 127)

• side_brush_pwm (int) – side brush PWM (-127 - 127)

• vacuum_pwm (int) – vacuum duty cycle (0 - 127)

Examples:

>>> adapter = PyRoombaAdapter("/dev/ttyUSB0")
>>> adapter.send_pwm_moters(-55, 0, 0) # main brush is 55% PWM to opposite direction
>>> sleep(2.0) # keep 2 sec

send_song_cmd(song_number, song_length, note_number_list, note_duration_list)

Send song command

This command lets you specify up to four songs to the OI that you can play at a later time. Each song is associated with a song number. The Play command uses the song number to identify your song selection. Each song can contain up to sixteen notes. Each note is associated with a note number that uses MIDI note definitions and a duration that is specified in fractions of a second. The number of data bytes varies, depending on the length of the song specified. A one note song is specified by four data bytes. For each additional note within a song, add two data bytes.

• Available in modes: Passive, Safe, or Full

Parameters

• song_number (int) – (0-4) The song number associated with the specific song. If you send a second Song command, using the same song number, the old song is overwritten.

• song_length (int) – (1-16) The length of the song, according to the number of musical notes within the song.

• note_number_list (list) – Note Number (31 – 127) The pitch of the musical note Roomba will play, according to the MIDI note numbering scheme. The lowest musical note that Roomba will play is Note #31. Roomba considers all musical notes outside the range of 31 – 127 as rest notes, and will make no sound during the duration of those notes.

• note_duration_list (list) – Note Duration (0 – 255) The duration of a musical note, in increments of 1/64th of a second. Example: a half-second long musical note has a duration value of 32.

Examples:

>>> adapter = PyRoombaAdapter("/dev/ttyUSB0")
>>> # note names
>>> f4 = 65
>>> a4 = 69
>>> c5 = 72
>>> # note lengths
>>> MEASURE = 160
>>> HALF = int(MEASURE / 2)
>>> Q = int(MEASURE / 4)
>>> Ed = int(MEASURE * 3 / 16)
>>> S = int(MEASURE / 16)
>>> adapter.send_song_cmd(0, 9,
>>>             [a4, a4, a4, f4, c5, a4, f4, c5, a4],
>>>             [Q, Q, Q, Ed, S, Q, Ed, S, HALF]) # set song
>>> adapter.send_play_cmd(0) # play song
>>> sleep(10.0) # keep playing

start_cleaning()

Start the default cleaning

• Available in modes: Passive, Safe, or Full

• Changes mode to: Passive

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.start_cleaning()

start_max_cleaning()

Start the max cleaning

• Available in modes: Passive, Safe, or Full

• Changes mode to: Passive

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.start_max_cleaning()

start_seek_dock()

Start seek dock

• Available in modes: Passive, Safe, or Full

• Changes mode to: Passive

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.start_seek_dock()

start_spot_cleaning()

Start spot cleaning

• Available in modes: Passive, Safe, or Full

• Changes mode to: Passive

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.start_spot_cleaning()

turn_off_power()

Turn off power of Roomba

The mode change to passive mode.

• Available in modes: Passive, Safe, or Full

Examples:

>>> PORT = "/dev/ttyUSB0"
>>> adapter = PyRoombaAdapter(PORT)
>>> adapter.turn_off_power()