source: rtos_arduino/trunk/arduino_lib/libraries/ZumoShield/README.textile@ 232

h1. Pololu Zumo Shield Libraries(Modified)

This Libraries is based on "Pololu Zumo Shield Libraries":https://github.com/pololu/zumo-shield. 

Version: 1.2.3
Release Date: 2013-11-27
"www.pololu.com":http://www.pololu.com/

h2. Summary

This is a collection of libraries for the "Arduino":http://pololu.com/catalog/product/2191 that interfaces with the Pololu "Zumo Shield":http://www.pololu.com/catalog/product/2508, "Zumo Reflectance Sensor Array":http://www.pololu.com/catalog/product/1419, "Zumo robot kit":http://www.pololu.com/catalog/product/2509, and "Zumo robot for Arduino":http://www.pololu.com/catalog/product/2510. These libraries provide functions to help you program an Arduino-controlled Zumo robot, and the included example projects demonstrate how to use them for more complex tasks.

For more information about the libraries and examples, please see the "Zumo Shield user's guide":http://www.pololu.com/docs/0J57.

h2. Getting Started

h3. Software

Download the archive from "GitHub":https://github.com/pololu/zumo-shield-arduino, decompress it, and move each library folder (Pushbutton, QTRSensors, ZumoBuzzer, ZumoExamples, ZumoMotors, and ZumoReflectanceSensorArray) into the "libraries" subdirectory inside your Arduino sketchbook directory. You can view your sketchbook location by selecting File->Preferences in the Arduino environment; if there is not already a "libraries" folder in that location, you should create it yourself. After installing the library, restart the Arduino environment so it can find the Zumo Shield libraries and their examples.

Some of the examples also require our "LSM303 library":https://github.com/pololu/lsm303-arduino to be installed.

h3. Hardware

The Zumo Shield for Arduino can be purchased on Pololu's website:
* *"by itself":http://www.pololu.com/catalog/product/2508*;
* as part of a *"Zumo robot kit for Arduino":http://www.pololu.com/catalog/product/2509* that also includes a "Zumo chassis":http://www.pololu.com/catalog/product/1418 and a stainless steel "Zumo blade":http://www.pololu.com/catalog/product/1410; or
* as a fully-assembled *"Zumo robot for Arduino":http://www.pololu.com/catalog/product/2510* with "75:1 HP motors":http://www.pololu.com/catalog/product/2361 and a "reflectance sensor array":http://www.pololu.com/catalog/product/1419 installed.

See the "Zumo Shield user's guide":http://www.pololu.com/docs/0J57 for more details about purchasing and assembling the hardware.

h2. Using the Zumo Shield Libraries

h3. ZumoMotors

The ZumoMotors library provides functions for PWM-based speed (and direction) control of the two motors on the Zumo with the onboard DRV8835 dual motor driver. On Arduinos with ATmega328P, ATmega168, and ATmega32U4 microcontrollers (which include the Leonardo, Uno, and most older Arduinos), the motor control functions use hardware PWM outputs from Timer1 to generate pulse width modulation at a 20 kHz frequency.

If you accidentally soldered a motor to the Zumo Shield backwards (opposite the orientation indicated in the assembly instructions), you can simply call @flipLeftMotor(true)@ and/or @flipRightMotor(true)@ to make the motors behave consistently with the directions in your code.

This library comes with an example sketch demonstrating its use.

h3. ZumoBuzzer

The ZumoBuzzer library provides functions that allow various sounds to be played on the buzzer of the Zumo Shield, from simple beeps to complex tunes.  This library is fully compatible with the OrangutanBuzzer functions in the "Pololu AVR C/C++ Library":http://www.pololu.com/docs/0J18, so any melodies written for OrangutanBuzzer functions will also work with ZumoBuzzer functions.  This library comes with some example sketches demonstrating its use.

h3. Pushbutton

The Pushbutton library, which can also be found in the "pushbutton-arduino repository":https://github.com/pololu/pushbutton-arduino, provides a set of functions that are useful for detecting and debouncing pushbutton presses. While the most obvious application of this library is to work with the Zumo Shield's user pushbutton on digital pin 12, this library can be used as a general-purpose library for interfacing many types of buttons and switches to an Arduino, even without a Zumo Shield.  This library comes with an example sketch demonstrating its use.

h3. ZumoReflectanceSensorArray

This library provides a set of functions for reading reflectance values from a "Zumo Reflectance Sensor Array":http://www.pololu.com/catalog/product/1419.

This library depends on the QTRSensors library.  The ZumoReflectanceSensorArray class is a subclass of QTRSensorsRC.  The functions provided by QTRSensorsRC can also be used on the ZumoReflectanceSensorArray class, and are documented in the "Arduino Library for the Pololu QTR Reflectance Sensors":http://www.pololu.com/docs/0J19 document on Pololu's website.

This library comes with an example sketch demonstrating its use.

h3. QTRSensors

This library, which can also be found in the "qtr-sensors-arduino repository":https://github.com/pololu/qtr-sensors-arduino, is a general library for interfacing with "Pololu QTR reflectance sensors":http://www.pololu.com/catalog/category/123.  Since the "Zumo Reflectance Sensor Array":http://www.pololu.com/catalog/product/1419 has the same interface as the QTR RC reflectance sensors, the ZumoReflectanceSensorArray library uses QTRSensors to read the sensor array.

h2. Example Projects

Some additional example sketches can be found under Files->Examples->ZumoExamples in the Arduino environment. These examples demonstrate how you can program a Zumo to perform more complex and interesting tasks by combining the functionality of multiple libraries. The Example Projects section of the "Zumo Shield user's guide":http://www.pololu.com/docs/0J57 describes these examples in more detail.

h2. Version History

* 1.2.3 (2013-11-27): Updated examples to work with LSM303 library version 2.0.0.
* 1.2.2 (2013-10-08): Added SumoCollisionDetect example.
* 1.2.1 (2013-07-19): Added LineFollower example.
* 1.2.0 (2013-06-03): Added ZumoExamples dummy library containing example projects.
* 1.1.3 (2013-05-14): Added CompassExample.
* 1.1.2 (2013-04-18): Pulled in QTRSensors version 2.1.0.
* 1.1.1 (2013-04-17): Added ZumoReflectanceSensorArray constructors with parameters to call init() with and pulled fix from qtr-sensors-arduino 2.0.2.
* 1.1.0 (2013-01-07): Added ZumoReflectanceSensorArray and QTRSensors libraries.
* 1.0.0 (2012-11-09): Original release.