PololuQik2.h

00001 /**
00002  *    @file         PololuQik2.h
00003  *    @author       Edward Wilson (edwilson1989@gmail.com)
00004  *    @author       Eric Fialkowski (eric.fialkowski@gmail.com)
00005  *    @date         Aug 6, 2010
00006  *    @brief        PololuQik2 motor drivers.
00007  *
00008  *  @details This class is a derivative work based on work of Mr Fialkowski.
00009  *
00010  *  PololuQik2 - basic class to control Pololu's Qik2s9v1
00011  *    motor controller (http://www.pololu.com/catalog/product/1110)
00012  *
00013  * This uses the default settings for the motor controller and the
00014  * Compact Protocol to communicate to it.
00015  *
00016  * This library is free software; you can redistribute it and/or
00017  * modify it under the terms of the GNU Lesser General Public
00018  * License as published by the Free Software Foundation; either
00019  * version 2.1 of the License, or (at your option) any later version.
00020  *
00021  * This library is distributed in the hope that it will be useful,
00022  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00023  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00024  * Lesser General Public License for more details.
00025  *
00026  * You should have received a copy of the GNU Lesser General Public
00027  * License along with this library; if not, write to the Free Software
00028  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00029  *
00030  *  @version 1.0    August 6, 2010      Initial code
00031  *  @version 1.2    December 28, 2010   Composition constructor added
00032  *  @version 1.3    April 22, 2011      Ported for MBED
00033  */
00034 
00035 #ifndef POLOLUQIK2_H_
00036 #define POLOLUQIK2_H_
00037 
00038 #include "CRC7.h"
00039 #include "mbed.h"
00040 #include <inttypes.h>
00041 
00042 #define INITIALPACKET 0xAA /**< The packet used to initialise the motor controller*/
00043 #define MOTOR0FORWARDPACKET 0x88 /**< The packet used to set motor 0 forward */
00044 #define MOTOR1FORWARDPACKET 0x8C /**< The packet used to set motor 1 forward */
00045 #define MOTOR0REVERSEPACKET 0x8A /**< The packet used to set motor 0 in reverse */
00046 #define MOTOR1REVERSEPACKET 0x8E /**< The packet used to set motor 1 in reverse */
00047 #define MOTOR0COASTPACKET 0x86 /**< The packet used to all motor 0 to coast */
00048 #define MOTOR1COASTPACKET 0x87 /**< The packet used to all motor 1 to coast */
00049 #define FWVERSIONPACKET 0x81 /**< The packet to query the firmware version of the motor controller */
00050 #define ERRORPACKET 0x82 /**< The packet to request the error state from the motor controller */
00051 #define MOTOR0CURRENTPACKET 0x90
00052 #define MOTOR1CURRENTPACKET 0x91
00053 
00054 
00055 #define DATAOVERRUNERRORBIT 3 /**< The bit which signifies a data over run error */
00056 #define FRAMEERRORBIT 4 /**< The bit which signifies a frame error */
00057 #define CRCERRORBIT 5 /**< The bit which signifies CRC error */
00058 #define FORMATERRORBIT 6 /**< The bit which signifies a format error */
00059 #define TIMEOUTERRORBIT 7 /**< The bit which signifies time out error */
00060 
00061 /**
00062  * This is the driver for the motor controller. This is to control a Qik2s9v1.
00063  * It will not control multiple motor and it does not support daisy chaining motor controllers.
00064  *
00065  * The specification for the motor controller can be found http://www.pololu.com/catalog/product/1110/
00066  *
00067  * This motor controller is based on the work of Mr Fialkowski.
00068  * This motor controller requires the newSoftSerial library be installed on the build path.
00069  * This motor controller also requires the CRC7 class.
00070  *
00071  * @see CRC7
00072  */
00073 class PololuQik2 {
00074 public:
00075 
00076     /**
00077      * The parameterised constructor for the pololuQik2 motor controller.
00078      *
00079      * @attention It is important to call the begin() method as this initialises the controller.
00080      * @see begin()
00081      *
00082      * @param txPin the pin on the controller to use for transmitting serial bytes.
00083      * @param rxPin the pin on the controller to use for recieving serial bytes.
00084      * @param errPin the digital output pin to use to reset the motor controller.
00085      * @param EnableCRC true if CRC should be used when communicating with the motor controller.
00086      * @param reset the pin on the controller to use to reset the motor controller.
00087      */
00088     PololuQik2::PololuQik2(PinName TxPin, PinName RxPin, PinName RSTPin, PinName errPin, void (*errorFunction)(void), bool enCRC);
00089 
00090     // get current
00091     uint8_t PololuQik2::GetMotor0Current();
00092     uint8_t PololuQik2::GetMotor1Current();
00093     //
00094     /**
00095      * This method initialises and begins communication with the motor controller.
00096      * This method is also called when an error is exhibited.
00097      *
00098      * @see PololuQik2()
00099      */
00100     void begin();
00101 
00102     /**
00103      * sets the speed of motor 0. This command has superseded motor0Forwards and motor0Reverse.
00104      * If the speed is less than 0 then the motor will reverse.
00105      * If the speed is greater than 0 then the motor will run forward
00106      * If the speed is 0 then the motor will be stopped.
00107      *
00108      * The bound for the speed are -127 to 127.
00109      * @since 1.2
00110      * @param speed the speed of the motor. If this value is negative the motor will reverse to the
00111      * appropriate speed.
00112      */
00113     void setMotor0Speed(int8_t speed);
00114 
00115     /**
00116      * sets the speed of motor 1. This command has superseded motor1Forwards and motor1Reverse.
00117      * If the speed is less than 0 then the motor will reverse.
00118      * If the speed is greater than 0 then the motor will run forward
00119      * If the speed is 0 then the motor will be stopped.
00120      *
00121      * The bound for the speed are -127 to 127.
00122      * @since 1.2
00123      * @param speed the speed of the motor. If this value is negative the motor will reverse to the
00124      * appropriate speed.
00125      */
00126     void setMotor1Speed(int8_t speed);
00127 
00128     /**
00129      * instructs the motor controller to halt both motors.
00130      * This is equivalent to called any of the forward or reverse methods
00131      * with the speed as zero (0).
00132      */
00133     void stopBothMotors(int8_t speed);
00134 
00135     /**
00136      * retrieves the firmware version from the motor controller. This will return one of two values.
00137      * Either the ASCII representation of 1 or the ASCII representation of 2.
00138      *
00139      * The return from this method will be either 49 or 50. If otherwise there is an error.
00140      *
00141      * @return the firmware version of the motor controller.
00142      */
00143     uint8_t getFirmwareVersion();
00144 
00145     /**
00146      * Checks if the motor controller has a Data over run error
00147      *
00148      * returns true if it has a data over run error
00149      */
00150     bool hasDataOverrunError();
00151 
00152     /**
00153      * Checks if the motor controller has a Frame error
00154      *
00155      * returns true if it has a Frame error
00156      */
00157     bool hasFrameError();
00158 
00159     /**
00160      * Checks if the motor controller has a CRC error
00161      *
00162      * returns true if it has a CRC error
00163      */
00164     bool hasCRCError();
00165 
00166     /**
00167      * Checks if the motor controller has a Format error
00168      *
00169      * returns true if it has a Format error
00170      */
00171     bool hasFormatError();
00172 
00173     /**
00174      * Checks if the motor controller has a time out error
00175      *
00176      * returns true if it has a time out error
00177      */
00178     bool hasTimeoutError();
00179     
00180     /**
00181      * retrieves the error value from the motor controller and stores it in the
00182      * class internal workings.
00183      *
00184      * @see errorBitSet()
00185      * @see error()
00186      */
00187     uint8_t getError();
00188 
00189 private:
00190 
00191     void errorCall();
00192     
00193     /**
00194      * This actually sends the data to the motor controller.
00195      *
00196      * @param message[] the message to be sent
00197      * @param length the length of the message to be sent
00198      */
00199     void sendMessage(unsigned char message[], uint8_t length);
00200 
00201     /**
00202      * Checks if a specific bit in the error byte is set.
00203      * @param bitToCheck the bit number to check. Assume that the least significant bit is bit 1.
00204      * @return true if the bit is set.
00205      */
00206     bool errorBitSet(uint8_t bitToCheck);
00207 
00208     /**
00209      * retrieves the error value from the motor controller and stores it in the
00210      * class internal workings.
00211      *
00212      * @see errorBitSet()
00213      * @see error()
00214      */
00215     //uint8_t getError();
00216     
00217     /**
00218      * sends a single byte to the motor controller
00219      *
00220      * @param byte the byte of data to send
00221      */
00222     void sendByte(uint8_t byte);
00223 
00224     /**
00225      * Reads a byte from the motor controller. This is a blocking call.
00226      * If the motor controller is not sending anything then the program will
00227      * halt indefinitely.
00228      *
00229      * @return the byte from the motor controller.
00230      * @bug There is a suspected bug in this method.
00231      */
00232     uint8_t readByte();
00233 
00234     Serial serialConnection; /**< Serial connection to the motor controller */
00235     DigitalOut resetPin; /**< The digital output on the controller which is connected to the motor controllers reset pin. */
00236     InterruptIn errorPin; /**< The digital output on the controller which is connected to the motor controllers error pin. This must be an interrrupt pin on the controller */
00237     uint8_t errByte; /**< A temporary store for the error code received from the motor controller. */
00238     uint8_t firmwareVersion; /**< The motor controller firmware version */
00239     bool enableCRC; /**< this value will be true if CRCs are expected by the motor controller. */
00240     CRC7 CRC; /**< The CRC object used to generate the CRC checksums */
00241 
00242 };
00243 
00244 #endif /* POLOLUQIK2_H_ */