Diff: piswarm.h

Revision:

0:9ffe8ebd1c40

Child:

1:b067a08ff54e

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/piswarm.h	Fri Jan 31 22:59:25 2014 +0000
@@ -0,0 +1,414 @@
+/* University of York Robot Lab Pi Swarm Robot Library
+ *
+ * (C) Dr James Hilder, Dept. Electronics & Computer Science, University of York
+ * 
+ * Version 0.4  January 2014
+ *
+ * Designed for use with the Pi Swarm Board (enhanced MBED sensor board) v1.2
+ *
+ * Based on the original m3pi library, Copyright (c) 2007-2010 cstyles (see copyright notice at end of file)
+ */
+
+#ifndef PISWARM_H
+#define PISWARM_H
+
+#include "mbed.h"
+#include "platform.h"
+#include "alpha433.h"
+#include "main.h"
+
+
+#ifdef MBED_RPC
+#include "rpc.h"
+#endif
+
+#define SEND_SIGNATURE 0x81
+#define SEND_RAW_SENSOR_VALUES 0x86
+#define SEND_TRIMPOT 0xB0
+#define SEND_BATTERY_MILLIVOLTS 0xB1
+#define DO_PLAY 0xB3
+#define PI_CALIBRATE 0xB4
+#define DO_CLEAR 0xB7
+#define DO_PRINT 0xB8
+#define DO_LCD_GOTO_XY 0xB9
+#define LINE_SENSORS_RESET_CALIBRATION 0xB5
+#define SEND_LINE_POSITION 0xB6
+#define AUTO_CALIBRATE 0xBA
+#define SET_PID 0xBB
+#define STOP_PID 0xBC
+#define M1_FORWARD 0xC1
+#define M1_BACKWARD 0xC2
+#define M2_FORWARD 0xC5
+#define M2_BACKWARD 0xC6
+#define EXPANSION_IC_ADDRESS 0x40
+#define MAGNETOMETER_ADDRESS 0x1C
+#define ADC_ADDRESS 0x46
+#define EEPROM_ADDRESS 0XA0
+
+class PiSwarm :  public Stream {
+
+    // Public functions
+public:
+
+    /** Create the m3pi object connected to the default pins
+     * Pin 05 : Alpha Transceiver SDI
+     * Pin 06 : Alpha Transceiver SDO
+     * Pin 07 : Alpha Transceiver CLK
+     * Pin 08 : Alpha Transceiver FSS
+     * Pin 09 : Serial (3pi) transmit
+     * Pin 10 : Serial (3pi) receive
+     * Pin 11 : Alpha Transceiver NIRQ
+     * Pin 12 : IR Pulse Output for IR1,2,7,8
+     * Pin 13 : IR Pulse Output for IR3,4,5,6
+     * Pin 14 : Echo Pin for Sonar
+     * Pin 15 : Light Sensor Analogue Input
+     * Pin 16 : Gyrometer Analogue Input
+     * Pin 17 : Accelerometer Z Analogue Input
+     * Pin 18 : Accelerometer Y Analogue Input
+     * Pin 19 : Accelerometer X Analogue Input
+     * Pin 20 : Temperature Sensor Analogue Input
+     * Pin 21 : Center LED Blue PWM Output
+     * Pin 22 : Center LED Green PWM Output
+     * Pin 23 : Center LED Red PWM Output
+     * Pin 24 : Outer LED Blue PWM Output
+     * Pin 25 : Outer LED Green PWM Output
+     * Pin 26 : Outer LED Red PWM Output
+     * Pin 27 : I2C SCL 
+     * Pin 28 : I2C SDA
+     * Pin 29 : GPIO Expander Interrupt
+     * Pin 30 : Trigger Pin for Sonar
+     * Pin 31 : USB D+ Connector
+     * Pin 32 : USB D- Connector
+     */
+    PiSwarm();
+
+    // Returns the RGB Colour of the Outer LED as an int (r<<16 g<<8 b)
+    int get_oled_colour(void);
+   
+    // Returns the RGB Colour of the Center LED as an int (r<<16 g<<8 b)
+    int get_cled_colour(void);
+
+    // Toggle the state of a single outer LED without affected the others
+    void set_oled(char oled, char value);
+
+    void test_oled(void);
+    void turn_off_all_oleds(void);
+    
+    // Toggle the states of all 10 outer LEDs
+    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);
+    
+    void activate_oleds(void);
+
+    // The default setup routine: called when s3pi is created
+    void setup ( void );
+    
+    // Send a message of given length over the RF interface
+    void send_rf_message(char* message, char length);
+    
+    // Sets up the IO expansion IC using I2C commands; returns a zero if successful
+    int setup_expansion_ic ( void );
+    
+    // Turns on or off the LDO outputs based on the current enable variables (enable_ir_ldo and enable_led_ldo)
+    void enable_ldo_outputs ( void );
+    
+    // Called after a delay from the IO expansion interrupt; delay helps debounce switches
+    void interrupt_timeout_event ( void );
+
+    // The interrupt handler for the IO expansion IC; calls the timeout event to debounce switches
+    void expansion_interrupt_handler ( void );
+    
+    // Turns off interrupt LED after a delay to indicate switch has been pressed
+    void led_timeout_event ( void );
+    
+    // Set colour of outer LEDs
+    void set_oled_colour ( char red, char green, char blue );
+    
+    // Set colour of central LED
+    void set_cled_colour ( char red, char green, char blue );
+    
+    // Set brightness of outer LEDs (works by increasing total period for PWM)
+    void set_oled_brightness ( char brightness );
+    
+    // Set brightness of central LED (works by increasing total period for PWM)
+    void set_cled_brightness ( char brightness );
+    
+    // Read temperature from the temperature IC; return is temperature in degrees Celsius
+    float read_temperature ( void );
+    
+    // Routine to calibrate gyro; by default run in setup, robot should be stationary to avoid errors
+    // Returns 1 if successful, 0 if failed
+    char calibrate_gyro ( void );
+    
+    // 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
+    char calibrate_accelerometer ( void );
+
+    // Routine to calibrate magnetometer
+    // Returns 1 if successful, 0 if failed    
+    char calibrate_magnetometer ( void );
+    
+    char setup_adc( void );
+    
+    // Routine to initialise radio
+    void setup_radio( void );
+    
+    // Routines returns an approximate distance of any reflected obstacle in front of the given IR sensor (in millimeters)
+    // Returns a value of 100 if nothing is detected
+    // True distance depends on a number of factors (reflectiveness of surface being one of the key ones)
+    // Minimum value is around 5
+    float read_reflected_ir_distance ( char index );
+    
+    // Returns the raw ADC value for a given IR sensor
+    unsigned short read_adc_value( char index );
+    
+    // Read the I2C magnetometer and store values locally: use before get_magnetometer_x etc...
+    char read_magnetometer ( void );
+    
+    // Return the magnetometer x value stored on last call of read_magnetometer()
+    signed short get_magnetometer_x ( void );
+    
+    // Return the magnetometer y value stored on last call of read_magnetometer()
+    signed short get_magnetometer_y ( void );
+    
+    // Return the magnetometer z value stored on last call of read_magnetometer()
+    signed short get_magnetometer_z ( void );
+    
+    // Blinks the calibration LED during calibration (turns off if calibration successful)
+    void calibrate_ticker_routine ( void );
+    
+    // Read the gyroscope yaw value.  Return value is degrees per second clockwise.
+    float read_gyro ( void );
+    
+    // Read the X value from the accelerometer.  Return value is mps2.
+    float read_accelerometer_x ( void );
+    
+    // Read the Y value from the accelerometer.  Return value is mps2.
+    float read_accelerometer_y ( void );
+    
+    // Read the Z value from the accelerometer.  Return value is mps2.  Generally this will have g against it.
+    float read_accelerometer_z ( void );
+    
+    // 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.
+    float read_light_sensor ( void );
+    
+    // Read the robot ID set using the DIP switches (these are read during setup and not updated).
+    char get_id ( void );
+    
+    // Read the switches value from the last call of the ISR
+    char get_switches ( void );
+    
+    // Enable or disable the center LED
+    void enable_cled ( char enable );
+    
+    // Write single byte to EEPROM
+    void write_eeprom_byte ( int address, char data );  
+  
+    // Write (length) bytes to EEPROM
+    void write_eeprom_block ( int address, char length, char * data);
+    
+    // Read single byte from EEPROM
+    char read_eeprom_byte ( int address );
+
+    // Read next byte from EEPROM at current address 
+    char read_next_eeprom_byte ( void ); 
+
+    // Read (length) from EEPROM
+    char read_eeprom_block ( int address, char length );
+
+    // The following functions are (generally) those which are part of the original M3Pi library and interact with the 3Pi robot
+
+    /** Read the raw line sensors into a 5-int array
+     * @ param raw_ls_array Pointer to 5-int array for raw values (range 0-2000)
+     */
+    void read_raw_sensors ( int * raw_ls_array ); 
+     
+
+    /** Play a tune on the 3pi buzzer
+     * @ param tune Pointer to a character sequence of the tune 
+     * @ param length Length of characters in sequence
+     * ‘A’ – ‘G’: used to specify the notes that will be played
+     * ‘R’: used to specify a rest (no sound for the duration of the note)
+     * ‘<’ ‘>’ plays the next note one octave lower or higher
+     * ‘+’ or ‘#’ after a note raises any note one half-step, ‘-’ after a note lowers any note one half-step
+     * ‘.’ after a note “dots” it, increasing the length by 50%. Each additional dot adds half as much as the previous dot, so that “A..” is 1.75 times the length of “A”.
+     * ‘O’ followed by a number sets the octave (default: O4).
+     * ‘T’ followed by a number sets the tempo in beats/min (default: T120).
+     * ‘L’ followed by a number sets the default note duration to the type specified by the number: 4 for quarter notes, 8 for eighth notes, 16 for sixteenth notes, etc. (default: L4).
+     * ‘V’ followed by a number from 0-15 sets the music volume (default: V15).
+     * ‘MS’ sets all subsequent notes to play play staccato – each note is played for 1/2 of its allotted time, followed by an equal period of silence.
+     * ‘ML’ sets all subsequent notes to play legato – each note is played for full length. This is the default setting.
+     * ‘!’ resets the octave, tempo, duration, volume, and staccato setting to their default values. These settings persist from one play() to the next, which allows you to more conveniently break up your music into reusable sections.
+     * 1-2000: when immediately following a note, a number determines the duration of the note. For example, C16 specifies C played as a sixteenth note (1/16th the length of a whole note).
+     * EG Blue Danube Waltz (badly): s3pi.play_tune("MSCEGGR>F>FR>D>DRCCEGGR>G>GR>E>ER<B<BDAAR>A>AR>F>F",51);
+     */
+    void play_tune (char * tune, int length);
+    
+    /** Force a hardware reset of the 3pi
+     */
+    void reset (void);
+    
+    float get_left_motor (void);
+    float get_right_motor (void);
+
+    /** Directly control the speed and direction of the left motor
+     *
+     * @param speed A normalised number -1.0 - 1.0 represents the full range.
+     */
+    void left_motor (float speed);
+
+    /** Directly control the speed and direction of the right motor
+     *
+     * @param speed A normalised number -1.0 - 1.0 represents the full range.
+     */
+    void right_motor (float speed);
+
+    /** Drive both motors forward as the same speed
+     *
+     * @param speed A normalised number 0 - 1.0 represents the full range.
+     */
+    void forward (float speed);
+
+    /** Drive both motors backward as the same speed
+     *
+     * @param speed A normalised number 0 - 1.0 represents the full range.
+     */
+    void backward (float speed);
+
+    /** Drive left motor backwards and right motor forwards at the same speed to turn on the spot
+     *
+     * @param speed A normalised number 0 - 1.0 represents the full range.
+     */
+    void left (float speed);
+
+    /** Drive left motor forward and right motor backwards at the same speed to turn on the spot
+     * @param speed A normalised number 0 - 1.0 represents the full range.
+     */
+    void right (float speed);
+
+    /** Stop both motors
+     *
+     */
+    void stop (void);
+
+    /** Read the voltage of the potentiometer on the 3pi
+     * @returns voltage as a float
+     *
+     */
+    float pot_voltage(void);
+
+    /** Read the battery voltage on the 3pi
+     * @returns battery voltage as a float
+     */
+    float battery(void);
+
+    /** Read the position of the detected line
+     * @returns position as A normalised number -1.0 - 1.0 represents the full range.
+     *  -1.0 means line is on the left, or the line has been lost
+     *   0.0 means the line is in the middle
+     *   1.0 means the line is on the right
+     */
+    float line_position (void);
+
+
+    /** Calibrate the sensors. This turns the robot left then right, looking for a line
+     *
+     */
+    char sensor_auto_calibrate (void);
+
+    /** Set calibration manually to the current settings.
+     *
+     */
+    void calibrate(void);
+
+    /** Clear the current calibration settings
+     *
+     */
+    void reset_calibration (void);
+
+    void PID_start(int max_speed, int a, int b, int c, int d);
+
+    void PID_stop();
+
+    /** Locate the cursor on the 8x2 LCD
+     *
+     * @param x The horizontal position, from 0 to 7
+     * @param y The vertical position, from 0 to 1
+     */
+    void locate(int x, int y);
+
+    /** Clear the LCD
+     *
+     */
+    void cls(void);
+
+    /** Send a character directly to the 3pi serial interface
+     * @param c The character to send to the 3pi
+     */
+    int putc(int c);
+
+    /** Receive a character directly to the 3pi serial interface
+     * @returns c The character received from the 3pi
+     */
+    int getc();
+
+    /** Send a string buffer to the 3pi serial interface
+     * @param text A pointer to a char array
+     * @param int The character to send to the 3pi
+     */
+    int print(char* text, int length);
+
+
+    void start_system_timer(void);
+
+    float get_uptime (void);
+
+#ifdef MBED_RPC
+    virtual const struct rpc_method *get_rpc_methods();
+#endif
+
+private :
+
+    Serial _ser;
+    PwmOut _oled_r, _oled_g, _oled_b, _cled_r, _cled_g, _cled_b;
+    AnalogIn _gyro, _accel_x, _accel_y, _accel_z, _temperature, _light;
+    DigitalOut _irpulse_1, _irpulse_2;
+    I2C _i2c;
+    Alpha433 _rf;
+    Timer _system_timer;
+ 
+    void motor (int motor, float speed);
+    virtual int _putc(int c);
+    virtual int _getc();
+
+};
+
+void display_system_time(void);
+void init(void);
+extern Serial pc;
+extern PiSwarm piswarm;
+
+#endif
+
+
+/********************************************************************************
+ * COPYRIGHT NOTICE                                                             *
+ *                                                                              *
+ * 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.                                                                *
+ *                                                                              *
+ *******************************************************************************/
\ No newline at end of file