A Python implementation of the iRobot Open Interface.
- Provides a low level interface for building Open Interface commands to send over a serial connection
- Provides a low level set of response parsers to read data returned from robots
- Provides a high level object oriented Interface for the Create2
- Provides a REPL to interactively control a Create2 robot over a serial connection
Low Level Interface:
from irobot.openinterface.commands import set_mode_full, request_sensor_data # or other commands from irobot.openinterface.constants import RESPONSE_SIZES from irobot.openinterface.response_parsers import unsigned_byte_response # open a serial connection # assumed to be serial here # change mode serial.write(set_mode_full()) # read oi mode serial.write(request_sensor_data(35)) unsigned_byte_response(serial.read(RESPONSE_SIZES[35]))
High Level Object Oriented Interface for the Create2:
from irobot.robots.create2 import Create2 from irobot.openinterface.constants import MODES # instantiate robot robot = Create2(port) # read sensor print(robot.left_encoder_counts) # change mode to drive (SAFE|FULL) robot.oi_mode = MODES.SAFE robot.drive_straight(50) # stop driving robot.drive_straight(0) # return to passive mode robot.oi_mode = MODES.PASSIVE # shutdown OI robot.stop()
REPL
Launch
console_interfaces.create2 (this should be callable as Create2 from the command line after installation)In the REPL, the robot is bound to the
robot variableIssue Python commands as you see fit
To see what data is being sent/received enable logging
enable_logging()To turn off
disable_logging()Example:
>>> enable_logging()
>>> robot.sensor_group0
INFO
Last command sent 19.53 seconds ago
Sending Command
Decimal: [142|0]
Hex: [8E|0]
Bin: [10001110|00000000]
INFO
Received
Decimal: [3|0|1|1|1|1|0|0|0|0|0|0|0|0|0|0|2|67|20|4|101|38|10|136|10|136]
Hex: [3|0|1|1|1|1|0|0|0|0|0|0|0|0|0|0|2|43|14|4|65|26|A|88|A|88]
Bin: [00000011|00000000|00000001|00000001|00000001|00000001|00000000| ... |10001000|00001010|10001000]
The commands and response parsers in openinterface provide all the primitives needed to issue and retrieve the response for any command in the Roomba Open Interface Spec.:
openinterface.commands
low level support for packing data to send over a serial connection
pack_op_code
pack_signed_byte
pack_unsigned_byte
pack_2unsigned_bytes
pack_3signed_bytes
pack_3unsigned_bytes
pack_4unsigned_bytes
pack_schedule
pack_drive
pack_drive_special_cases
functions for building data packets for each command
start
reset
stop
set_baud
set_mode_passive
set_mode_safe
set_mode_full
clean
clean_max
clean_spot
seek_dock
power_down
get_days
set_schedule
set_day_time
drive
drive_direct
drive_pwm
set_motors
set_motors_pwm
set_leds
set_scheduling_leds
set_raw_leds
trigger_buttons
set_ascii_leds
set_song
play_song
request_sensor_data
openinterface.response_parsers
low level support for unpacking data received over a serial connection
binary_response
packed_binary_response
byte_response
unsigned_byte_response
short_response
unsigned_short_response
classes to extract composite responses
PackedBinaryData Ex: BumpsAndWheelDrop
BumpsAndWheelDrop bump_right
WheelOvercurrents bump_left
Buttons wheel_drop_right
ChargingSources wheel_drop_left
LightBumper
Stasis
SensorGroup0
SensorGroup1
SensorGroup2
SensorGroup3
SensorGroup4
SensorGroup5
SensorGroup6
SensorGroup100
SensorGroup101
SensorGroup106
SensorGroup107
openinterface.constants
named value used in the spec used as parameters to functions and range checking
BAUD_RATE
DAYS
DRIVE
MOTORS
LEDS
WEEKDAY_LEDS
SCHEDULING_LEDS
RAW_LED
BUTTONS
ROBOT
MODES
WHEEL_OVERCURRENT
BUMPS_WHEEL_DROPS
CHARGE_SOURCE
LIGHT_BUMPER
STASIS
POWER_SAVE_TIME
RESPONSE_SIZES
The class Create2 in robots.create2 is built upon the primitives in openinterface and provides niceties like management of the serial connection. All sensors are exposed as properties of the Create2 class while actions are implemented as methods.
robots.create2
methods
wake
start
reset
stop
set_baud
clean
clean_max
clean_spot
seek_dock
power_down
set_schedule
clear_schedule
set_day_time
drive
drive_straight
spin_left
spin_right
drive_direct
drive_pwm
set_motors
set_motors_pwm
set_leds
set_scheduling_leds
set_raw_leds
set_ascii_leds
trigger_buttons
set_song
play_song
properties
enable_quirks
auto_wake
bumps_and_wheel_drops
wall_sensor
cliff_left
cliff_front_left
cliff_front_right
cliff_right
virtual_wall
wheel_overcurrents
dirt_detect
ir_char_omni
ir_char_left
ir_char_right
buttons
distance
angle
charging_state
voltage
current
temperature
battery_charge
battery_capacity
wall_signal
cliff_left_signal
cliff_front_left_signal
cliff_front_right_signal
cliff_right_signal
charging_sources
oi_mode
song_number
is_song_playing
number_stream_packets
requested_velocity
requested_radius
requested_right_velocity
requested_left_velocity
left_encoder_counts
right_encoder_counts
light_bumper
light_bump_left_signal
light_bump_front_left_signal
light_bump_center_left_signal
light_bump_center_right_signal
light_bump_front_right_signal
light_bump_right_signal
left_motor_current
right_motor_current
main_brush_motor_current
side_brush_motor_current
stasis
sensor_group0
sensor_group1
sensor_group2
sensor_group3
sensor_group4
sensor_group5
sensor_group6
sensor_group100
sensor_group101
sensor_group106
sensor_group107
firmware_version
The Create2 class also provides the following features not explicitly provided in the spec:
- auto_wake - the Open Interface goes to sleep after 5 minutes of inactivity when in Passive mode. With this property set to True, the
Create2object will track idle time when in Passive mode and automatically wake the robot when a command is issued if necessary. Enabled by default in the constructor. wake maybe be called any time with wake() - enable_quirks - Roomba 500/600 firmware versions prior to 3.3.0 return an incorrect value for distance and angle. With this property set to True, the properties
distanceandanglewill use the encoder counts to determine the correct value. This only works for thedistanceandangleproperties. Distance and angle in the sensor groups will still report the wrong value. - firmware_version - a property of the
Create2class that gets the welcome message in order to determine the firmware version. Reading this property will reset the robot and will take approximately 5 seconds to complete. To see this used to automatically determine ifenable_quirksshould be set, please seecheck_for_quirksinconsole_interfaces.create2.
Please see the iRobot Roomba Open Interface Spec for a listing of all commands and their purposes.
irobot-1.0.0b1
- Initial release
irobot-1.0.0b2
- Bugfix: Improperly set baud rate on serial connection preventing the library from working under Linux.
irobot-1.0.0b3
- Bugfix: Wrong op code for seek_dock
- Bugfix: Use of Python 2.7 incompatible version of super()
This is beta software. It has been tested under Pyhon 2.7 and 3.x under Windows 8 and Python 3.x under Debain GNU/Linux 8 (jessie) 64 bit.
Download the package irobot-1.0.0b3.tar.gz
Install with pip
pip install [path to file]Linux notes:
- In order to use the Create Cable on
/dev/ttyUSB0I had to - remove modemmanager (apparently is takes possession of
/dev/ttyUSB0) - add myself to
dialoutwithsudo adduser [username] dialout
- remove modemmanager (apparently is takes possession of
- In order to use the Create Cable on
Unit tests for verifying some of the command builders may be found in
tests.commands_testA test script to connect to a Create2 over a serial connection and exercise all read commands maybe found in
tests.create2_test- Issues
- set_raw_leds does not presently behave as detailed in the spec. The issue has been reported to the manufacturer.
- The orange and green wires are swapped on the official Create Cables preventing the robot form waking. You will need to create your own cable in order to use the
auto_wakefeature.
- Notes
- the arguments to
set_raw_ledsare integers that should be composed by ORing the segments you wish to turn on. Example:set_raw_leds(RAW_LED.A | RAW_LED.B | RAW_LED.C)to turn on segments A, B, and C of the first display. - the notes argument to
set_songis a list of tuples where each tuple is a note and a duration. Eample:set_song(0, [(57,32),(59,32),(60,32)])to create a song as song0 consisting of the notes A, B, and C played for .5 seconds each.
- the arguments to
MIT License Copyright (c) 2016 Matthew Witherwax Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.