piswarm.h

00001 /*******************************************************************************************
00002  *
00003  * University of York Robot Lab Pi Swarm Robot Library
00004  *
00005  * (C) Dr James Hilder, Dept. Electronics & Computer Science, University of York
00006  * 
00007  * Version 0.5  February 2014
00008  *
00009  * Designed for use with the Pi Swarm Board (enhanced MBED sensor board) v1.2
00010  *
00011  ******************************************************************************************/
00012 
00013 #ifndef PISWARM_H
00014 #define PISWARM_H
00015 
00016 #include "mbed.h"
00017 #include "platform.h"
00018 #include "alpha433.h"
00019 #include "main.h"
00020 
00021 #ifdef MBED_RPC
00022 #include "rpc.h"
00023 #endif
00024 
00025 // The following defines are user parameters and may be edited 
00026 // SWARM_SIZE - size of swarm (+1).  Max 32.
00027 // USE_COMMUNICATION_STACK - 1 to enable, 0 to bypass
00028 // CALIBRATE_COLOURS - 1 to increase blue intensity, 0 to not
00029 // CENTER_LED_BRIGHTNESS - Range 0 to 100
00030 // OUTER_LED_BRIGHTNESS - Range 0 to 100
00031 // PC_BAUD - PC Serial Baudrate.  Max 115200
00032 // RF_ALLOW_COMMANDS - 1 to allow remote RF commands, 0 to block
00033 // RF_USE_LEDS - 1 to use MBED LEDs to display RF status
00034 // RF_USE_TDMA - 1 to use time-delayed responses to broadcast messages 
00035 // RF_TDMA_TIME_PERIOD_US 15625 - Period of delay to use (per ID) in us.
00036 // PISWARM_DEBUG - 1 to send general Pi Swarm debug information over USB serial interface
00037 // RF_DEBUG - 1 to send communication stack debug information over USB serial interface
00038 // RF_VERBOSE - 1 to send verbose RF debug information over USB serial interface
00039 // START_RADIO_ON_BOOT - 1 to enable RF transceiver and comms stack on boot
00040 // RF_FREQUENCY - Frequency of RF chip.  See datasheet for details (default 435000000)
00041 // RF_DATARATE - Baud rate of the RF chip. Max 115200, default 57600.
00042 
00043 #define SWARM_SIZE 32
00044 #define USE_COMMUNICATION_STACK 1
00045 #define CALIBRATE_COLOURS 1
00046 #define CENTER_LED_BRIGHTNESS 30
00047 #define OUTER_LED_BRIGHTNESS 50
00048 #define PC_BAUD 115200
00049 #define RF_ALLOW_COMMANDS 1
00050 #define RF_USE_LEDS 1
00051 #define RF_USE_TDMA 1
00052 #define RF_TDMA_TIME_PERIOD_US 15625
00053 #define PISWARM_DEBUG 1
00054 #define RF_DEBUG 1
00055 #define RF_VERBOSE 1
00056 #define START_RADIO_ON_BOOT 1
00057 #define RF_FREQUENCY 435000000
00058 #define RF_DATARATE 57600
00059 
00060 // The remaining defines give the addresses of hardware and 3-Pi instructions etc. and should not be changed
00061 #define SEND_SIGNATURE 0x81
00062 #define SEND_RAW_SENSOR_VALUES 0x86
00063 #define SEND_TRIMPOT 0xB0
00064 #define SEND_BATTERY_MILLIVOLTS 0xB1
00065 #define DO_PLAY 0xB3
00066 #define PI_CALIBRATE 0xB4
00067 #define DO_CLEAR 0xB7
00068 #define DO_PRINT 0xB8
00069 #define DO_LCD_GOTO_XY 0xB9
00070 #define LINE_SENSORS_RESET_CALIBRATION 0xB5
00071 #define SEND_LINE_POSITION 0xB6
00072 #define AUTO_CALIBRATE 0xBA
00073 #define SET_PID 0xBB
00074 #define STOP_PID 0xBC
00075 #define M1_FORWARD 0xC1
00076 #define M1_BACKWARD 0xC2
00077 #define M2_FORWARD 0xC5
00078 #define M2_BACKWARD 0xC6
00079 #define EXPANSION_IC_ADDRESS 0x40
00080 #define MAGNETOMETER_ADDRESS 0x1C
00081 #define ADC_ADDRESS 0x46
00082 #define EEPROM_ADDRESS 0XA0
00083 
00084 class PiSwarm :  public Stream {
00085 
00086     // Public functions
00087 public:
00088 
00089     // Create the Pi Swarm object connected to the default pins [see end of file]
00090     PiSwarm();
00091     
00092     
00093     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00094     // LED Functions
00095     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00096 
00097     // Returns the RGB Colour of the Outer LED as an int (r<<16 g<<8 b)
00098     int get_oled_colour(void);
00099    
00100     // Returns the enable state of an single outer led 
00101     char get_oled_state(char oled);
00102 
00103     // Set colour of outer LEDs
00104     void set_oled_colour ( char red, char green, char blue );
00105 
00106     // Toggle the state of a single outer LED without affected the others
00107     void set_oled(char oled, char value);
00108    
00109     // Toggle the states of all 10 outer LEDs
00110     void set_oleds(char oled_0, char oled_1, char oled_2, char oled_3, char oled_4, char oled_5, char oled_6, char oled_7, char oled_8, char oled_9);
00111     
00112     // Disable all the LEDs and the dedicated power supply
00113     void turn_off_all_oleds(void);
00114      
00115     // Set brightness of outer LEDs (works by increasing total period for PWM)
00116     void set_oled_brightness ( char brightness );
00117      
00118     // Sends the message to the GPIO expander to update which OLEDs are active
00119     void activate_oleds(void);
00120     
00121     // Returns the RGB Colour of the Center LED as an int (r<<16 g<<8 b)
00122     int get_cled_colour(void);
00123  
00124     // Returns the enable state of the center LED 
00125     char get_cled_state(void);
00126 
00127     // Set colour of central LED
00128     void set_cled_colour ( char red, char green, char blue );
00129        
00130     // Enable or disable the center LED
00131     void enable_cled ( char enable );
00132     
00133     // Set brightness of central LED (works by increasing total period for PWM)
00134     void set_cled_brightness ( char brightness );
00135 
00136     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00137     // IR Functions
00138     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00139  
00140     // Returns an approximate distance of any reflected obstacle in front of the given IR sensor (in millimeters, range 0 - 100)
00141     float read_reflected_ir_distance ( char index );
00142     
00143     // Returns the illuminated raw ADC value for a given IR sensor (500us pulse)
00144     unsigned short read_illuminated_raw_ir_value ( char index );
00145     
00146     // Returns the raw ADC value for a given IR sensor
00147     unsigned short read_adc_value( char index );
00148     
00149     // Turns on or off the LDO outputs based on the current enable variables (enable_ir_ldo and enable_led_ldo)
00150     void enable_ldo_outputs ( void );
00151     
00152     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00153     // Sensor Functions
00154     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00155 
00156     // Read the gyroscope yaw value.  Return value is degrees per second clockwise.
00157     float read_gyro ( void );
00158     
00159     // Read the X value from the accelerometer.  Return value is mps2.
00160     float read_accelerometer_x ( void );
00161     
00162     // Read the Y value from the accelerometer.  Return value is mps2.
00163     float read_accelerometer_y ( void );
00164     
00165     // Read the Z value from the accelerometer.  Return value is mps2.  Generally this will have g against it.
00166     float read_accelerometer_z ( void );
00167     
00168     // Read the I2C magnetometer and store values locally: use before get_magnetometer_x etc...
00169     char read_magnetometer ( void );
00170     
00171     // Return the magnetometer x value stored on last call of read_magnetometer()
00172     signed short get_magnetometer_x ( void );
00173     
00174     // Return the magnetometer y value stored on last call of read_magnetometer()
00175     signed short get_magnetometer_y ( void );
00176     
00177     // Return the magnetometer z value stored on last call of read_magnetometer()
00178     signed short get_magnetometer_z ( void );
00179     
00180     // Read temperature from the temperature IC; return is temperature in degrees Celsius
00181     float read_temperature ( void );
00182    
00183     // Read the value from the light sensor.  This will return a value ranging from 0 to a peak of around 100 in direct, bright light.
00184     float read_light_sensor ( void );
00185     
00186     // Read the raw line sensors into a 5-int array (range 0-2000)
00187     void read_raw_sensors ( int * raw_ls_array ); 
00188     
00189     // Returns the uptime of the system in seconds    
00190     float get_uptime (void);
00191     
00192     // Returns the battery voltage
00193     float battery(void);
00194     
00195     // Read the voltage of the user potentiometer on the 3-pi
00196     float pot_voltage(void);
00197 
00198     // Read the robot ID set using the DIP switches (these are read during setup and not updated).
00199     char get_id ( void );
00200     
00201     // Read the switches value from the last call of the ISR
00202     char get_switches ( void );
00203     
00204     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00205     // Motor and Actuator Functions
00206     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00207 
00208     // Returns the last speed value set for the left motor
00209     float get_left_motor (void);
00210      
00211     // Returns the last speed value set for the right motor
00212     float get_right_motor (void);
00213 
00214     // Directly control the speed and direction of the left motor (range -1.0 to 1.0)
00215     void left_motor (float speed);
00216 
00217     // Directly control the speed and direction of the right motor (range -1.0 to 1.0)
00218     void right_motor (float speed);
00219 
00220     // Drive both motors forward as the same speed (range -1.0 to 1.0)
00221     void forward (float speed);
00222 
00223     // Drive both motors backward as the same speed (range -1.0 to 1.0)
00224     void backward (float speed);
00225 
00226     // Drive left motor backwards and right motor forwards at the same speed to turn on the spot (range -1.0 to 1.0)
00227     void left (float speed);
00228 
00229     // Drive left motor forward and right motor backwards at the same speed to turn on the spot (range -1.0 to 1.0)
00230     void right (float speed);
00231 
00232     // Stop both motors
00233     void stop (void);
00234     
00235     // Play a tune on the 3-pi buzzer (see notes at end of file for more details)
00236     void play_tune (char * tune, int length);
00237     
00238     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00239     // EEPROM Functions
00240     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00241    
00242     // Write single byte to EEPROM
00243     void write_eeprom_byte ( int address, char data );  
00244   
00245     // Write (length) bytes to EEPROM
00246     void write_eeprom_block ( int address, char length, char * data);
00247     
00248     // Read single byte from EEPROM
00249     char read_eeprom_byte ( int address );
00250 
00251     // Read next byte from EEPROM at current address 
00252     char read_next_eeprom_byte ( void ); 
00253 
00254     // Read (length) from EEPROM
00255     char read_eeprom_block ( int address, char length );
00256     
00257     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00258     // Display Functions
00259     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00260    
00261     // Locate the cursor on the 8x2 LCD [to position x (0-7), y (0-1)]
00262     void locate(int x, int y);
00263 
00264     // Clear the LCD
00265     void cls(void);
00266 
00267     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00268     // Setup and Internal Functions
00269     // Generally these functions should not be called by user code
00270     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00271 
00272     // Send a message of given length over the RF interface
00273     void send_rf_message(char* message, char length);
00274  
00275     // The default setup routine: called when the Pi Swarm is created
00276     void setup ( void );
00277        
00278     // Sets up the IO expansion IC using I2C commands; returns a zero if successful
00279     int setup_expansion_ic ( void );
00280     
00281     // Called after a delay from the IO expansion interrupt; delay helps debounce switches
00282     void interrupt_timeout_event ( void );
00283 
00284     // The interrupt handler for the IO expansion IC; calls the timeout event to debounce switches
00285     void expansion_interrupt_handler ( void );
00286     
00287     // Turns off interrupt LED after a delay to indicate switch has been pressed
00288     void led_timeout_event ( void );
00289     
00290     // Routine to calibrate gyro; by default run in setup, robot should be stationary to avoid errors (Returns 1 if successful, 0 if failed)
00291     char calibrate_gyro ( void );
00292     
00293     // Routine to calibrate accelerometer, by default run after successful gyro calibration, robot should be flat and stationary to avoid errors (Returns 1 if successful, 0 if failed)
00294     char calibrate_accelerometer ( void );
00295 
00296     // Routine to calibrate magnetometer (Returns 1 if successful, 0 if failed)    
00297     char calibrate_magnetometer ( void );
00298     
00299     // Send instructions to the I2C ADC (for IR measurement)
00300     char setup_adc( void );
00301     
00302     // Routine to initialise radio
00303     void setup_radio( void );
00304     
00305     // Blinks the calibration LED during calibration (turns off if calibration successful)
00306     void calibrate_ticker_routine ( void );
00307     
00308     // Used to debug/test the OLED array
00309     void test_oled(void);
00310 
00311     // Starts the system timer
00312     void start_system_timer(void);
00313     
00314     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////  
00315     // Native m3Pi Functions
00316     // These should preserve functionality of (most) m3pi code but may be fully functional on Pi Swarm
00317     //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00318 
00319     // Force a hardware reset of the 3-pi
00320     void reset (void);
00321     
00322     // Read the position of the detected line [using line-following IR]
00323     float line_position (void);
00324 
00325     // Calibrate the sensors. This turns the robot left then right, looking for a line [using line-following IR]
00326     char sensor_auto_calibrate (void);
00327 
00328     // Set calibration manually to the current settings.
00329     void calibrate(void);
00330 
00331     // Clear the current calibration settings
00332     void reset_calibration (void);
00333 
00334     // Start the PID contoller
00335     void PID_start(int max_speed, int a, int b, int c, int d);
00336 
00337     // Stop the PID controller
00338     void PID_stop();
00339 
00340     // Send a character directly to the 3pi serial interface
00341     int putc(int c);
00342 
00343     // Receive a character directly to the 3pi serial interface
00344     int getc();
00345 
00346     // Send a string buffer to the 3pi serial interface
00347     int print(char* text, int length);
00348 
00349     #ifdef MBED_RPC
00350     virtual const struct rpc_method *get_rpc_methods();
00351     #endif
00352 
00353     private :
00354 
00355     Serial _ser;
00356     PwmOut _oled_r, _oled_g, _oled_b, _cled_r, _cled_g, _cled_b;
00357     AnalogIn _gyro, _accel_x, _accel_y, _accel_z, _temperature, _light;
00358     I2C _i2c;
00359     DigitalOut _irpulse_1, _irpulse_2;
00360     Alpha433 _rf;
00361     Timer _system_timer;
00362  
00363     void motor (int motor, float speed);
00364     virtual int _putc(int c);
00365     virtual int _getc();
00366 
00367 };
00368 
00369 void display_system_time(void);
00370 void init(void);
00371 extern Serial pc;
00372 extern PiSwarm piswarm;
00373 
00374 #endif
00375 
00376 
00377 /********************************************************************************
00378  *     MBED Pin connection layout                                               *
00379  *                                                                              *
00380  *   * Pin 05 : Alpha Transceiver SDI                                           *
00381  *   * Pin 06 : Alpha Transceiver SDO                                           *
00382  *   * Pin 07 : Alpha Transceiver CLK                                           *
00383  *   * Pin 08 : Alpha Transceiver FSS                                           *
00384  *   * Pin 09 : Serial (3pi) transmit                                           *
00385  *   * Pin 10 : Serial (3pi) receive                                            *
00386  *   * Pin 11 : Alpha Transceiver NIRQ                                          *
00387  *   * Pin 12 : IR Pulse Output for IR1,2,7,8                                   *
00388  *   * Pin 13 : IR Pulse Output for IR3,4,5,6                                   *
00389  *   * Pin 14 : Echo Pin for Sonar                                              *
00390  *   * Pin 15 : Light Sensor Analogue Input                                     *
00391  *   * Pin 16 : Gyrometer Analogue Input                                        *
00392  *   * Pin 17 : Accelerometer Z Analogue Input                                  *
00393  *   * Pin 18 : Accelerometer Y Analogue Input                                  *
00394  *   * Pin 19 : Accelerometer X Analogue Input                                  *
00395  *   * Pin 20 : Temperature Sensor Analogue Input                               *
00396  *   * Pin 21 : Center LED Blue PWM Output                                      *
00397  *   * Pin 22 : Center LED Green PWM Output                                     *
00398  *   * Pin 23 : Center LED Red PWM Output                                       *
00399  *   * Pin 24 : Outer LED Blue PWM Output                                       *
00400  *   * Pin 25 : Outer LED Green PWM Output                                      *
00401  *   * Pin 26 : Outer LED Red PWM Output                                        *
00402  *   * Pin 27 : I2C SCL                                                         *
00403  *   * Pin 28 : I2C SDA                                                         *
00404  *   * Pin 29 : GPIO Expander Interrupt                                         *
00405  *   * Pin 30 : Trigger Pin for Sonar                                           *
00406  *   * Pin 31 : USB D+ Connector                                                *
00407  *   * Pin 32 : USB D- Connector                                                *
00408  *                                                                              *
00409  *******************************************************************************/     
00410 
00411 /********************************************************************************
00412  *     Using the 3-Pi Buzzer                                                    *
00413  *                                                                              * 
00414  *     play_tune (char * tune, int length)                                      *
00415  *                                                                              *
00416  *     tune - Pointer to a character sequence of the tune                       * 
00417  *     length - Length of characters in sequence                                *
00418  *                                                                              *
00419  *     The character sequence recognises the following characters:              *
00420  *                                                                              *
00421  *      A – G : used to specify the notes that will be played                   *
00422  *                                                                              *
00423  *      R : used to specify a rest (no sound for the duration of the note)      *
00424  *                                                                              *
00425  *      < or > : plays the next note one octave lower or higher                 *
00426  *                                                                              *
00427  *      + or # : raises the previous notes pitch by one semitone                *
00428  *                                                                              *
00429  *      - : lowers the previous note pitch by one semitone                      *
00430  *                                                                              *
00431  *      . : extend length of previous by 50% (each additional dot adds half as  *
00432  *          much as the previous dot, so that A.. is 1.75 times the length of A *
00433  *                                                                              *
00434  *      O followed by a number : sets the octave (default : O4)                 *
00435  *                                                                              *
00436  *      T followed by a number : sets the tempo in beats/min (default : T120)   *
00437  *                                                                              *
00438  *      L followed by a number : sets the default note duration specified by the*
00439  *                               number - 4 for quarter notes, 8 for eighth, 16 *
00440  *                               for sixteenth notes, etc. (default : L4)       *
00441  *                                                                              *
00442  *      V followed by a number : sets the volume (range 0 - 15, default : V15)  *
00443  *                                                                              *
00444  *      MS : sets all subsequent notes to play staccato (each note is played for*
00445  *           1/2 of its allotted time followed by an equal period of silence)   *
00446  *                                                                              *
00447  *      ML : sets all subsequent notes to play legato (each note is played for  *
00448  *           full length. This is the default setting.                          *
00449  *                                                                              *
00450  *      ! : resets the octave, tempo, duration, volume, and staccato setting to *
00451  *          their default values. These settings persist from one play_tune() to*
00452  *          the next, which allows you to more conveniently break up your music *
00453  *          into reusable sections.                                             *
00454  *                                                                              *
00455  *      1 - 2000 : when immediately following a note, a number determines the   *
00456  *                 duration of the note. For example, C16 specifies C played as *
00457  *                 a sixteenth note (1/16th the length of a whole note).        * 
00458  *                                                                              *
00459  *                                                                              *
00460  *      Some examples:                                                          *
00461  *                                                                              *
00462  *      Blue Danube Waltz (played badly!)                                       *
00463  *      play_tune("MSCEGGR>F>FR>D>DRCCEGGR>G>GR>E>ER<B<BDAAR>A>AR>F>F",51);     *
00464  *                                                                              *
00465  *******************************************************************************/
00466          
00467 /********************************************************************************
00468  * COPYRIGHT NOTICE                                                             *
00469  *                                                                              *
00470  *                                                                              *
00471  * Parts of code based on the original m3pi library, Copyright (c) 2010 cstyles *
00472  *                                                                              *
00473  * Permission is hereby granted, free of charge, to any person obtaining a copy *
00474  * of this software and associated documentation files (the "Software"), to deal*
00475  * in the Software without restriction, including without limitation the rights * 
00476  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell    *
00477  * copies of the Software, and to permit persons to whom the Software is        *
00478  * furnished to do so, subject to the following conditions:                     *
00479  *                                                                              *
00480  * The above copyright notice and this permission notice shall be included in   * 
00481  * all copies or substantial portions of the Software.                          *
00482  *                                                                              *
00483  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   *
00484  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,     *
00485  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  *
00486  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       *
00487  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,*
00488  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN    *
00489  * THE SOFTWARE.                                                                *
00490  *                                                                              *
00491  *******************************************************************************/