James Hilder
Unfinished v0.7, added bearing detection
Fork of
Pi_Swarm_Library_v06_alpha
by 
piswarm
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 *