Robotics::IRobot - provides interface to iRobot Roomba and Create robots
use Robotics::IRobot; my $robot=Robotics::IRobot->new('/dev/rfcomm0'); #could be /dev/ttyUSB0, /dev/ttyS0, etc. #Initializes port and sends OI Init command $robot->init(); #Takes robot out of passive mode and enables #hardware based safeties $robot->startSafeMode(); #Move robot forward at 100mm/s $robot->forward(100); #Get sensor state hash ref $robot->refreshSensors(); my $sensorState=$robot->getSensorState(); #Wait until we have moved 500mm while($sensorState->{totalDistance}<500) { sleep 1; $robot->refreshSensors(); } $robot->stop(); $robot->close();
Version 0.1
IRobot Open Interface specification -- http://www.irobot.com/filelibrary/pdfs/hrd/create/Create%20Open%20Interface_v2.pdf
Time::HiRes, Device::SerialPort, POSIX, Math::Trig
Nothing
Robotics::IRobot provides an interface for controlling and accessing sensor data from iRobot robots that support the OI Interface.
This module provides on object oriented interface to the robot and allows for both event-driven and polling-based reading of sensor data. It provides all functionality defined in the OI Interface for Roomba 400 series and Create robots. Also provided is some additional functionality such as primative dead reckoning and enhanced use of the Create's song functionality.
NOTE: This module is designed for controlling Create but will work with Roomba where applicable.
I make no warranty as to the correct functioning of this module. Use may cause your robot to fall down your basement stairs, catch fire, and burn your house down. Be prepared to take physical control of robot at all times.
I assume no responsibility or liability for damage to robot or its surroundings. If you do not agree to this, do not use this module.
This software is currently in alpha status. Dead reckoning and telemetry are still a work in progress. So, expect sensor values produced by dead reckoning and motions produced by $robot->goTo and $robot->turnTo to be inaccurate at best.
Creates a new IRobot object using the given communications port.
Initializes the port, connects to the robot, and initiates the OI Interface.
Replays saved telemetry data, can be used for testing or analysis.
See section TELEMETRY
Does a soft-reset of robot. Needed to begin charging or recover after triggering hardware based safeties.
Puts robot into passive mode.
Puts robot into safe mode. (Turns on hardware based safeties.)
You must call one of startSafeMode or startFullMode before calling other actuator commands.
Puts robot into full mode. (Turns off hardware based safeties.)
Puts robot in passive mode and starts built in demo. Consult OI Interface doc for available demos.
Stops currently running demo.
Sends robot command to make a turn with speed $velocity (in mm/s), negative values are reverse; and turning radius $radius (in mm), positive values turn counter-clockwise, negative turn clockwise.
Sends robot command to drive right wheel at $rightVelocity (mm) and left wheel at $leftVelocity (mm). Positive values are forward, negative values are reverse.
Stops robot.
Moves robot forward at $velocity in (mm/s).
NOTE: This does not actually drive robot in a straight line, it actually performs right turn with a radius of 32768mm.
Moves robot in reverse at $velocity in (mm/s).
Rotates robot in place right (counter-clockwise) at $velocity (in mm/s).
Rotates robot in place left (clockwise) at $velocity (in mm/s).
Sets robot LEDs
$powerColor should be >=0 and <=255. 0 is green, 255 is red. $powerIntensity should be >=0 and <=255 $playOn and $advanceOn are boolean
Sets "Play" LED on or off.
Toggles "Play" LED.
Sets "Advance" LED on or off.
Toggles "Advance" LED.
Sets "Power" LED
$powerColor should be >=0 and <=255. 0 is green, 255 is red. $powerIntensity should be >=0 and <=255
Returns a hash reference with keys advance, play, powerColor, and powerIntensity that give current LED state. If modified, calls to updateLEDs will send modifications to robot.
NOTE: Values in hash reflect history of commands sent through interface. Actual LED state on robot may be different.
Writes current values in hash reference returned by getLEDState to robot.
Sets state of robot's digital outputs. Values are boolean.
Sets state of output $output to $state.
$output is >=0 and <=2. $state is boolean.
Toggles state of digital output $output
Returns an array ref containing state of robots digital outputs. If modified, calls to updateDigitalOutputs will send modifications to robot.
NOTE: Values in array reflect history of commands sent through interface. Actual output state on robot may be different.
Writes current values in array reference returned by getDigitalOutputs to robot.
Sets pwm duty cycle on low side drivers. Load values should be between 0 and 1 inclusive.
0 is off, 1 is on, .5 is pulsed on 50% of the time, etc.
Sets pwm duty cycle on low side driver $lsd to $load. Load values should be between 0 and 1 inclusive.
Changes pwm duty cycle on low side driver $lsd by $loadDelta. Load Delta should be between 0 and 1 inclusive.
Returns an array reference that contains current duty cycles of low side drivers. If modified, calls to updatePWMLoads will send modifications to robot.
NOTE: Values returned in this array are in the range 0-128, not 0-1 like the other methods. Also, values in array reflect history of commands sent through interface. Actual output state on robot may be different.
Writes current values in array reference returned by getPWMLoads to robot.
Turns on and off low side drivers. Values are boolean.
Sends IR byte through LED hooked up to LSD1.
See Open Interface doc for details.
Sets song $songId in robot's memory to @songBytes. @songBytes can contain up to 16 notes.
Loads song in ABC format (see abcnotation.com) from $file and begins playing on Create. If passed, calls &$callback($robot) when done.
NOTE: You must either poll sensor values frequently or use the sensor data streaming methods for this method to work properly. Calling this method will overwrite any data contained in song banks 14 and 15
Plays song contained in @songBytes (may be longer than 16 notes). If passed, calls &$callback($robot) when done.
Loads song in ABCNotation format from $file (see abcnotation.com). Returns song in format defined in OI Interface. If smaller than 16 notes (32 bytes) can be passed to setSongRaw. Otherwise resulting bytes can be passed to playLongSongRaw.
Sets song bank $songId to the song specified in $song.
$song is expected to be a whitespace seperated list of notes. Each note is made up of an optional octave number, a note letter (a-g) or r for a rest, an optional sharp designator (#), and a duration in 64ths of a second. If no octave is given the last octave specified is used. If no octave has yet been specified octave 4 is used. Example:
d16 a16 r32 3a16 a#32 b16 2b8 c#16
The example above will play a d in the 4th octave for 1/4 second, an a in the 4th octave for 1/4 second, rest for 1/2 second, an a in the 3rd octave for 1/4 second, and a sharp in the 3rd octage for 1/2 second, a b in the 3rd octave for 1/4 second, a b in the 2nd octave for 1/8 second, and a c sharp in the 2nd octave for 1/4 second.
The method will return the estimated duration in seconds the song will play. Using the example above the method would return 2.375
Plays song from bank $songId.
Attempts to turn the robot to face $direction relative to the direction it was facing when $robot->init() was called or last $robot->markOrigin call. Robot will make the turn at $speed. Robot will stop once complete and call &$callback($robot) if $callback is passed.
See section DEAD RECKONING for more information.
NOTE: You must either poll sensor values frequently or use the sensor data streaming methods for this method to work properly.
Attempts to drive the robot to position ($x,$y) relative to its location when $robot->init() was called or last $robot->markOrigin call. Robot will make the proceed at $speed. Robot will stop once complete and call &$callback($robot) if $callback is passed.
The robot's sensor data can be retrieved in several different ways. The easiest is to simply call $robot->refreshSensors on a regular basis. This will retrieve all sensor data from the robot, which can then be accessed from the hash returned by $robot->getSensorState(). If you do not want all sensor data to be retrieved, then you can use the $robot->getSensor($id) method. This will only retrieve data for one sensor (or sensor set) but, it is not recommended.
Consult the OI Interface document for more details on sensor ids.
Another method is to use the iRobot's sensor streaming functionality. When the robot is put in streaming mode it will send back sensor data once every 15ms. Use the $robot->startSteam, $robot->pauseStream. $robot->resumeStream method to start and stop the stream. The $robot->getStreamFrame method should be called at least every 15ms to read in the sensor data and update the sensor state hash. As with the polling method, you can pass a sensor ids to $robot->startStream to have the robot stream data for only particular sensors, but again, this is not recommeded.
The third method is to use the event-driven approach. Your program can register sensor listeners or events to listen for using the $robot->addSensorListener, $robot->addSensorEvent, $robot->runEvery, $robot->waitTime, $robot->waitDistance, and $robot->waitAngle methods. Once these have been registered the $robot->runSensorLoop and $robot->exitSensorLoop methods will put the robot in streaming mode then read sensor data as it comes in while updating the sensor state hash and calling any sensor listeners or events.
Returns a hash reference containing last read values from robot sensors.
Returns an array indicating the presense of a "home base" docking station and any docking beacons seen.
Example:
my ($dockPresent,$greenBeacon,$forceField,$redBeacon)=$robot->getDockSignal();
Retrieves all sensor data, refreshes sensor state hash, and triggers any sensor listeners or events. This method will block for up to 15ms if called more than once every 15ms.
Retreives data from a single sensor, refreshes sensor state hash, and triggers any sensor listeners or events. This method is generally not recommedended. $robot->refreshSensors() should be used instead.
Retrieves data for a particular sensor, refreshes sensor state hash, and triggers any sensor listeners or events. This method is generally not recommended. $robot->refreshSensors() should be used instead.
See OI Documentation for sensor ids.
Begins streaming sensor data from the robot. Updates sensor state hash every 15ms and triggers any sensor listeners or events. This method will block until $robot->exitSensorLoop() is called.
Stops streaming data from robot. Causes any previous call to runSensorLoop to return.
Puts robot into streaming mode. If a $sensorId is passed only streams that sensor. Otherwises streams data from all sensors.
See OI Documentation for more details
Pauses the sensor data stream.
Resumes a previously paused sensor stream.
Gets one frame of sensor data, updates sensor data hash, and triggers any sensor listerners or events. Should be called at least once every 15ms. Method will block until one frame of sensor data has been read.
See OI Documentation for more details.
Adds a sensor listener. This listener will be called whenever sensor data is retrieved, either as a group such as when $robot->refreshSensors or $robot->getStreamFrame is called or when individual sensors are retrieved using $robot->getSensors.
The priority parameter is used to determine the order in which listeners are called. Lower priorities are called first. Any listeners with a negative priority will be called before indirect sensors (dead reckoning) is calculated. Listeners with a priority less than 200 will be called before triggers for waitDistance, waitAngle, etc. events are called.
On each sensor data retrieval &$action($robot,$listener,$sensorId) will be called. $listener is a hash containing the following keys
id: listener id -- used to remove listener priority: listener priority -- do not changed this value action: the function being called param: the value of $param passed to addSensorListener
The same hash ref is returned with each call, so this can be used by the action callback to store values. $action must return true for processing of additional listeners to continue. This is useful for saftey checks, if you do not want any additional processing which could restart a stopped robot have $action return false.
$robot->addSensorListener returns the listener id. This can be used to remove the listener later.
Remove listener or event with $id.
Executes &$test($robot,$listener,$sensorId) each time sensor data is retrieved. $listener is a hash reference (see addSensorListener). $sensorId is the id of the sensor read. &$action($robot,$listener,$sensorId) is called if $test returns true. $param is included in the $listener hash ref. If $oneTime is true, the created listener is automatically removed the first time $test returns true.
As with addSensorListener, $action must return true if you wish additional listeners to continue processing. Returning false will stop further listeners and events from processing.
This method returns an id which can be passed to removeSensorListener to remove the event.
Creates a sensor event with $priority that calls &$callback($robot) every $time seconds. Returns an id that can be passed to removeSensorListener.
Creates a one time sensor event with $priority that calls &$callback($robot) once the robot has traveled $distance mm. Distance must be positive. Distances traveled in reverse will be used in determining total distance traveled. Returns an id that can be passed to removeSensorListener.
NOTE: if this method is called while in scripting mode, $priority and $callback are ignored and the scriptWaitDistance will be executed instead. (See scripting section below.)
Creates a one time sensor event with $priority that will call &$callback($robot) after robot has turned $angle radians in either direction. $angle must be positive. Turns in either direction will be used to determine total angle turned. Returns an id that can be passed to removeSensorListener.
NOTE: if this method is called while in scripting mode, $priority and $callback are ignored and the scriptWaitAngle will be executed instead. (See scripting section below.)
Creates a one-time sensor event with priority $priority that will call &$callback($robot) when robot is within $maxDelta of absolute direction $direction (in radians). 0 radians is the direction the robot was facing when last $robot->init or $robot->markOrigin was called. $direction should be between -PI and PI. Returns an id that can be passed to removeSensorListener.
Creates a one-time sensor event with priority $priority that will call &$callback($robot) after $time seconds. Returns an id that can be passed to removeSensorListener.
NOTE: if this method is called while in scripting mode, $priority and $callback are ignored and the scriptWaitTime will be executed instead. (See scripting section below.)
Sets the robot's current position as (0,0) and the direction the robot is currently facing as 0.
Returns a string listing each sensor value from the sensor state hash.
Returns a string condensed version of the current state of the robots sensors. Suitable for output in a command line program.
Bu Bp Cliff DIn AIn Chrg Wl Whl Oc Sng Md AP LR LFlFrR 0123 0704 HbIn AV LCR 012LR P00 1 Batt: 2606/2702 +1087@17200 (32) C Ir: 254 (+00003,+00052) -002 DGFR Cliff: 0000 0000 00000 00000 Wall: 00000
In the first 2 lines, Bu shows the status of the buttons on the robot. In the example above both the Advance and Play Buttons are pressed. Bp shows the status of the left (L) and right (R) bump sensors. Cliff shows the status of left (L), front-left (Fl), front-right (Fr), and right (R) sensors. DIn shows the state of the 4 digital inputs, AIn shows the value of the analog input. Chrg shows if charging is available from the home base (Hb) or internal (In) chargers. Wl shows the state of the actual (A) and virtual (V) wall sensors. Whl shows the state of the left (L), caster (C), and right (R) wheeldrop sensors. Oc shows the state of the overcurrent sensors for the 3 low side drivers, (0-2) and the left (L) and right (R) wheels. Sng indicates is a song is playing (P) and the currently selected song bank. Md shows the current mode number.
The battery line shows the battery charge and maxium capacity, the current and voltage flowing from the battery, the battry temperature, the charging state. Also, the byte recieved by the IR sensor is shown on this line. In the example above, the battery has charge of 2606 mAh out of a maximum capacity of 2702 mAh. The battery is charging at 1087 mA and 17200 mV. Positive current values indicate charging, negative ones indicate discharge. The battery temperature is 32 degrees C. The C indicates the battery is charging. And the IR byte receiving byte 254.
The fourth line shows the estimated x and y position in mm, and the current direction in degrees. Also shown is any docking indicators: dock present (D), green beacon (G), force field (F), red beacon (R).
The last line indicates the raw signal values of the four cliff sensors (left, front-left, front-right, and right) and the wall sensor.
These commands make use of the builtin scripting functionality of the iRobot create.
Puts robot in scripting mode. Subsequent commands will not be sent to robot, but instead be saved to robots script memory. Create can store a maximum of 100 bytes of scripting commands.
Runs the script currently stored in robot. This will cause the robot to go into passive mode and not respond to commands until script is complete.
If called while in scripting mode, causes script to repeat from begining.
Returns true if currently in scripting mode, false otherwise.
Leaves scripting mode without writing script to robot.
Leaves scripting mode and writes script to robot.
Waits $time seconds (rounded to nearest tenth). Robot will not respond to commands during this time. Not recommended to be used outside of scripting mode.
Waits until robot travels $distance mm. Robot will not respond to commands during this time. Not recommended to be used outside of scripting mode.
Waits until robot turns through $angle degrees. Robot will not respond to commands during this time. Not recommended to be used outside of scripting mode.
Waits until event with id $eventId occurs. Robot will not respond to commands during this time. Not recommended to be used outside of scripting mode.
See OI Documentation for list of event ids.
This module has the ability to record telemetry data containing bytes sent to and from robot. And any debuging data that can be provided by client programs.
Begins writing telemetry data to $file. Appends data unless $overwrite is true.
Stops recording telemetry data.
Write client application provided data to telemetry file. The $type value should use the following specification for maxium compatibility with other applications. $data can be any binary value.
Types: 0- indirect sensor field 16 - stream sync indicator 32 - 63 -- reserved for client UI 32 - key press 64-127 -- Debug info 64 - general debug 255 - String message
Stops the robot motion and sensor streaming and closes communication port.
The sensor state hash can be retrieved from the $robot->getSensorState() method. This only need be retrieved once as subsequent updates will be made to the same hash.
These are sensor values that are read directly from the robot.
--Keys-- wheeldropCaster -- wheeldrop sensor on front caster (boolean) wheeldropLeft -- wheeldrop sensor on left wheel (boolean) wheeldropRight -- wheeldrop sensor on right wheel (boolean) bumpLeft -- left bump sensor (boolean) bumpRight -- right bump sensor (boolean) wall -- physical wall sensor (boolean) cliffLeft -- left cliff sensor (boolean) cliffFrontLeft -- front-left cliff sensor (boolean) cliffFrontRight -- front-right cliff sensor (boolean) virtualWall -- virtual wall sensor (boolean) ocLeftWheel -- overcurrent on left wheel (boolean) ocRightWheel -- overcurrent on right wheel (boolean) ocLD0 -- overcurrent on low side driver 0 (boolean) ocLD1 -- overcurrent on low side driver 1 (boolean) ocLD2 -- overcurrent on low side driver 2 (boolean) irByte -- byte received by IR sensor (unsigned byte) advanceButton -- advance button state (boolean) playButton -- play button state (boolean) distance -- distance travelled in mm since last sensor refresh (signed short) angle -- angle turned in degrees since last sensor refresh (signed short) positive angles are counter-clockwise negative are clockwise NOTE: This sensor is extremely inaccurate chargingState -- indicates if robot is charging (boolean) voltage -- voltage of battery (unsigned short) current -- current of battery charge/discharged (signed short) positive values indicate charging negative indicate discharging batteryTemp -- temperature of battery in degrees C (unsigned byte) batteryCharge -- current battery charge in mAh (unsigned short) batteryCapacity -- maximum battery capacity in mAh (unsigned short) wallSignal -- raw signal value of wall sensor (unsigned short) cliffLeftSignal -- raw signal value of left cliff sensor (unsigned short) cliffFrontLeftSignal -- raw signal value of front-left sensor (unsigned short) cliffFrontRightSignal -- raw signal value of front-right cliff sensor (unsigned short) cliffRightSignal -- raw signal value of right cliff sensor (unsigned short) deviceDetect -- state of robot's device detect pin (boolean) digitalInput0 -- state of digital input 0 (boolean) digitalInput1 -- state of digital input 1 (boolean) digitalInput2 -- state of digital input 2 (boolean) digitalInput3 -- state of digital input 3 (boolean) analogIn -- value of analog input (unsigned short) homeBaseAvailable -- true if robot is connected to home base (boolean) internalCharger -- true if robot can charge battery using internal charger (boolean) oiMode -- OI Interface mode (unsigned byte) songNumber -- last selected song bank (unsigned byte) songPlaying -- true if song is playing (boolean) numPackets -- number of packets sent in last stream (byte) requestedVelocity -- last requested velocity (signed short) requestedRadius -- last requested turning radius (signed short) requestedRightVelocity -- last requested right wheel velocity (signed short) requestedLeftVelocity -- last requested left wheel velocity (signed short)
These are sensor values that are derived from direct sensors.
--Keys-- totalAngle -- sum of all previous angle readings totalDistance -- sum of all previous distance readings deltaX -- change in x coordinate since last reading deltaY -- change in y coordinate since last reading x -- x coordinate of current position y -- y coordinate of current position direction -- direction robot is currently facing in radians (between -PI and PI) actualAngle -- an attempt to correct angle sensor, actual angle turned in radians totalActualAngle -- sum of all previous actual angle readings turningRadius -- estimated actual turning radius cliffFrontSignalDelta, cliffFrontRightSignalDelta, cliffLeftSignalDelta, cliffFrontLeftSignalDelta -- raw cliff signal readings using intial reading as 0 baseline.
This module attempts to do some sensor correction and dead reckoning using sensor readings.
When the $robot->init or $robot->markOrigin is called. The x,y, and direction values of the robot are set to 0. The robot is then assumed to be facing along the positive y-axis (direction 0). The positive x-axis is 90 clockwise. Positive directions are counter-clockwise, negative directions are clockwise.
An attempt is made to correct inaccurate angle readings. The correction is done using error factors determined experimentally on an Create. Your mileage may vary.
A feature is planned to implement a calibration routine to determine error factors on an idividual robot.
Michael Ratliff, <$_='email@michaelratlixx.com'; s/x/f/g; print;>
<$_='email@michaelratlixx.com'; s/x/f/g; print;>
Please report any bugs or feature requests to bug-robotics-irobot at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Robotics-IRobot. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-robotics-irobot at rt.cpan.org
I only have an iRobot Create to use for testing. So, any Roomba bugs that are unable to be reproduced on a Create may go unresolved.
You can find documentation for this module with the perldoc command.
perldoc Robotics::IRobot
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Robotics-IRobot
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Robotics-IRobot
CPAN Ratings
http://cpanratings.perl.org/d/Robotics-IRobot
Search CPAN
http://search.cpan.org/dist/Robotics-IRobot/
Copyright 2011 Michael Ratliff.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See section NOTICE at the top of this document.
See http://dev.perl.org/licenses/ for more information.
To install Robotics::IRobot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Robotics::IRobot
CPAN shell
perl -MCPAN -e shell install Robotics::IRobot
For more information on module installation, please visit the detailed CPAN module installation guide.