====== iRobot

A Python implementation of the iRobot Open Interface.

|

Main Features

• 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 | Code Examples

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 variable | Issue 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]

| API Reference

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 Create2 object 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 distance and angle will use the encoder counts to determine the correct value. This only works for the distance and angle properties. Distance and angle in the sensor groups will still report the wrong value.
• firmware_version - a property of the Create2 class 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 if enable_quirks should be set, please see check_for_quirks in console_interfaces.create2.

Please see the iRobot Roomba Open Interface Spec <http://www.irobotweb.com/~/media/MainSite/PDFs/About/STEM/Create/iRobot_Roomba_600_Open_Interface_Spec.pdf>_ for a listing of all commands and their purposes.

|

Changelog

| 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()

|

Installation

| 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 <http://blog.lemoneerlabs.com/src/iRobot/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/ttyUSB0 I had to
  • remove modemmanager (apparently is takes possession of /dev/ttyUSB0)
  • add myself to dialout with sudo adduser [username] dialout |

Tests

| Unit tests for verifying some of the command builders may be found in tests.commands_test | A test script to connect to a Create2 over a serial connection and exercise all read commands maybe found in tests.create2_test

| Known Issues/Notes

• 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_wake feature.
• Notes
  • the arguments to set_raw_leds are 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_song is 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.

Author

Matthew Witherwax (lemoneer) <http://blog.lemoneerlabs.com/page/About>_

|

License

::

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.