Diff: m3pi.h

Revision:

1:5523d6d1feec

Parent:

0:56320ef879a6

Child:

2:26bf14f4dc84

--- a/m3pi.h	Tue Apr 04 08:08:16 2017 +0000
+++ b/m3pi.h	Wed Apr 05 10:25:42 2017 +0000
@@ -6,7 +6,7 @@
 /** m3pi Class
 @brief Library to control m3pi robot from Polulu running the serial slave code
 @brief Revision 1.0
-@author Craig A. Evans <C.A.Evans@leeds.ac.uk> 
+@author Craig A. Evans <C.A.Evans@leeds.ac.uk>
 @date   April 2017
 
 */
@@ -28,7 +28,8 @@
     void write_leds(int val);
 
     /** Initialisation function
-    * @details should be called at the start of the program
+    * @details Should be called at the start of the program to interrupt demo
+    * @details code and start 3pi in serial slave mode
     */
     void init();
 
@@ -36,18 +37,18 @@
     * @param signature - array of size 7 to store signature
     */
     void get_signature(char *signature);
-    
+
     /** Read raw sensor values from IR sensors (0 - 2000)
     * @param values - array of size 5 to store values
     */
-    void get_raw_values(unsigned int *values);      
+    void get_raw_values(unsigned int *values);
 
     /** Read calibrated sensor values from IR sensors (0 - 1000)
     * @param values - array of size 5 to store values
     */
     void get_calibrated_values(unsigned int *values);
-    
-    /** Read user potentiometer values
+
+    /** Read user potentiometer values (0.0 - 1.0)
     * @returns float in range  0.0 to 1.0
     */
     float get_trimpot_value();
@@ -56,53 +57,113 @@
     * @returns battery voltage in volts
     */
     float get_battery_voltage();
-    
+
     /** Play music
     * @param notes - const array containing Pololu notes
+    * @param length - number of notes in array
     */
     void play_music(const char notes[],int length);
-    
+
+    /** Calibrate
+    * @details manual calibration of sensors. Should be called repeatedly.
+    */
     void calibrate();
 
+    /** Reset previous calibration values
+    */
     void reset_calibration();
 
+    /** Returns estimate of line position
+    * @returns int in the range -2000 to 2000
+    * @details -2000 for line under sensor 0, -1000 for line under sensor 1
+    * @details 0 for line under sensor 2, 1000 for line under sensor 3 etc.
+    */
     int get_line_position();
-    
+
+    /** Returns estimate of normalised line position
+    * @returns float in the range -1.0 to 1.0
+    * @details -1.0 for line under sensor 0, -0.5 for line under sensor 1
+    * @details 0.0 for line under sensor 2, 0.5 for line under sensor 3 etc.
+    */
     float get_normalised_line_position();
 
+    /** Clear LCD
+    */
     void lcd_clear();
-    
+
+    /** Print text on LCD
+    * @param text[] - string of max size 8
+    * @param - length of string
+    */
     void lcd_print(char text[],int length);
-    
+
+    /** Move cursor on LCD
+    * @param x - x position
+    * @param y - line number
+    */
     void lcd_goto_xy(int x, int y);
-    
+
+    /** Call automatic calibration function
+    */
     void auto_calibrate();
-    
+
+    /** Move left motor
+    * @param speed - value in range -1.0 (full-speed backward) to 1.0 (full-speed forward)
+    */
     void left_motor(float speed);
-    
+
+    /** Move right motor
+    * @param speed - value in range -1.0 (full-speed backward) to 1.0 (full-speed forward)
+    */
     void right_motor(float speed);
-    
-    //////
-    
+
+    /** Move both motors
+    * @param left speed - value in range -1.0 (full-speed backward) to 1.0 (full-speed forward)
+    * @param right speed - value in range -1.0 (full-speed backward) to 1.0 (full-speed forward)
+    */
     void motors(float left_speed,float right_speed);
-    
+
+    /** Stop both motors
+    */
     void stop();
-    
+
+    /** Move buggy forward
+    * @param speed - value in range 0.0 to 1.0 (full-speed forward)
+    */
     void forward(float speed);
-    
+
+    /** Reverse buggy
+    * @param speed - value in range 0.0 to 1.0 (full-speed forward)
+    */
     void reverse(float speed);
-    
+
+    /** Spin right
+    * @param speed - value in range 0.0 to 1.0
+    */
     void spin_right(float speed);
-    
+
+    /** Spin left
+    * @param speed - value in range 0.0 to 1.0
+    */
     void spin_left(float speed);
-    
+
+    /** Read button on m3pi expansion shield (p21)
+    * @returns int - active-low - 0 for pressed/ 1 for not pressed
+    */
     int read_button();
-    
+
+    /** Display battery voltage on LCD
+    * @param x - x position on LCD to display
+    * @param y - line on LCD to display
+    */
     void display_battery_voltage(int x,int y);
-    
+
+    /** Display slave firmware signature on LCD
+    * @param x - x position on LCD to display
+    * @param y - line on LCD to display
+    */
     void display_signature(int x,int y);
 
-
 private:
 
     Serial* _serial;