Unfinished v0.7, added bearing detection
Fork of Pi_Swarm_Library_v06_alpha by
Diff: piswarm.h
- Revision:
- 4:52b3e4c5a425
- Parent:
- 3:4c0f2f3de33e
- Child:
- 5:09d535cb9e9d
--- a/piswarm.h Sun Feb 02 21:18:05 2014 +0000 +++ b/piswarm.h Sun Feb 02 22:30:47 2014 +0000 @@ -1,13 +1,14 @@ -/* University of York Robot Lab Pi Swarm Robot Library +/******************************************************************************************* + * + * 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 + * Version 0.5 February 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 @@ -51,6 +52,11 @@ // Create the Pi Swarm object connected to the default pins [see end of file] PiSwarm(); + + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // LED Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // Returns the RGB Colour of the Outer LED as an int (r<<16 g<<8 b) int get_oled_colour(void); @@ -58,80 +64,44 @@ // Returns the enable state of an single outer led char get_oled_state(char oled); - // Returns the enable state of the center LED - char get_cled_state(void); - - // Returns the RGB Colour of the Center LED as an int (r<<16 g<<8 b) - int get_cled_colour(void); + // Set colour of outer LEDs + void set_oled_colour ( char red, char green, char blue ); // 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); + // Disable all the LEDs and the dedicated power supply + void turn_off_all_oleds(void); + + // Set brightness of outer LEDs (works by increasing total period for PWM) + void set_oled_brightness ( char brightness ); + + // Sends the message to the GPIO expander to update which OLEDs are active 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 ); + // Returns the RGB Colour of the Center LED as an int (r<<16 g<<8 b) + int get_cled_colour(void); + + // Returns the enable state of the center LED + char get_cled_state(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 ); + + // Enable or disable the center LED + void enable_cled ( char enable ); // 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 + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // IR Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + // Returns an approximate distance of any reflected obstacle in front of the given IR sensor (in millimeters, range 0 - 100) float read_reflected_ir_distance ( char index ); // Returns the illuminated raw ADC value for a given IR sensor (500us pulse) @@ -140,6 +110,25 @@ // Returns the raw ADC value for a given IR sensor unsigned short read_adc_value( char index ); + // 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 ); + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Sensor Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + // 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 I2C magnetometer and store values locally: use before get_magnetometer_x etc... char read_magnetometer ( void ); @@ -152,33 +141,68 @@ // 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 temperature from the temperature IC; return is temperature in degrees Celsius + float read_temperature ( 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 raw line sensors into a 5-int array (range 0-2000) + void read_raw_sensors ( int * raw_ls_array ); + + // Returns the uptime of the system in seconds + float get_uptime (void); + + // Returns the battery voltage + float battery(void); + + // Read the voltage of the user potentiometer on the 3-pi + float pot_voltage(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 ); + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Motor and Actuator Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + // Returns the last speed value set for the left motor + float get_left_motor (void); + + // Returns the last speed value set for the right motor + float get_right_motor (void); + + // Directly control the speed and direction of the left motor (range -1.0 to 1.0) + void left_motor (float speed); + + // Directly control the speed and direction of the right motor (range -1.0 to 1.0) + void right_motor (float speed); + + // Drive both motors forward as the same speed (range -1.0 to 1.0) + void forward (float speed); + + // Drive both motors backward as the same speed (range -1.0 to 1.0) + void backward (float speed); + + // Drive left motor backwards and right motor forwards at the same speed to turn on the spot (range -1.0 to 1.0) + void left (float speed); + + // Drive left motor forward and right motor backwards at the same speed to turn on the spot (range -1.0 to 1.0) + void right (float speed); + + // Stop both motors + void stop (void); + // Play a tune on the 3-pi buzzer (see notes at end of file for more details) + void play_tune (char * tune, int length); + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // EEPROM Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Write single byte to EEPROM void write_eeprom_byte ( int address, char data ); @@ -193,147 +217,110 @@ // Read (length) from EEPROM char read_eeprom_block ( int address, char length ); + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Display Functions + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + // Locate the cursor on the 8x2 LCD [to position x (0-7), y (0-1)] + void locate(int x, int y); - // The following functions are (generally) those which are part of the original M3Pi library and interact with the 3Pi robot + // Clear the LCD + void cls(void); + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Setup and Internal Functions + // Generally these functions should not be called by user code + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + // Send a message of given length over the RF interface + void send_rf_message(char* message, char length); + + // The default setup routine: called when the Pi Swarm is created + void setup ( void ); + + // Sets up the IO expansion IC using I2C commands; returns a zero if successful + int setup_expansion_ic ( void ); + + // Called after a delay from the IO expansion interrupt; delay helps debounce switches + void interrupt_timeout_event ( void ); - /** 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 ); - + // 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 ); + + // 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 ); - // Play a tune on the 3-pi buzzer (see end of file for more details) - void play_tune (char * tune, int length); + // Routine to calibrate magnetometer (Returns 1 if successful, 0 if failed) + char calibrate_magnetometer ( void ); + + // Send instructions to the I2C ADC (for IR measurement) + char setup_adc( void ); + + // Routine to initialise radio + void setup_radio( void ); + + // Blinks the calibration LED during calibration (turns off if calibration successful) + void calibrate_ticker_routine ( void ); + // Used to debug/test the OLED array + void test_oled(void); + + // Starts the system timer + void start_system_timer(void); + + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Native m3Pi Functions + // These should preserve functionality of (most) m3pi code but may be fully functional on Pi Swarm + ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Force a hardware reset of the 3-pi 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 - */ + // Read the position of the detected line [using line-following IR] float line_position (void); - - /** Calibrate the sensors. This turns the robot left then right, looking for a line - * - */ + // Calibrate the sensors. This turns the robot left then right, looking for a line [using line-following IR] char sensor_auto_calibrate (void); - /** Set calibration manually to the current settings. - * - */ + // Set calibration manually to the current settings. void calibrate(void); - /** Clear the current calibration settings - * - */ + // Clear the current calibration settings void reset_calibration (void); + // Start the PID contoller void PID_start(int max_speed, int a, int b, int c, int d); + // Stop the PID controller 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 - */ + // Send a character directly to the 3pi serial interface int putc(int c); - /** Receive a character directly to the 3pi serial interface - * @returns c The character received from the 3pi - */ + // Receive a character directly to the 3pi serial interface 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 - */ + // Send a string buffer to the 3pi serial interface 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 -#ifdef MBED_RPC - virtual const struct rpc_method *get_rpc_methods(); -#endif - -private : + 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; + I2C _i2c; DigitalOut _irpulse_1, _irpulse_2; - I2C _i2c; Alpha433 _rf; Timer _system_timer; @@ -443,6 +430,9 @@ /******************************************************************************** * COPYRIGHT NOTICE * * * + * * + * Parts of code based on the original m3pi library, Copyright (c) 2010 cstyles * + * * * 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 *