Diff: sensors.h

Revision:

10:e58323951c08

Parent:

6:b340a527add9

Child:

15:be92991621b4

--- a/sensors.h	Sun Oct 16 14:12:49 2016 +0000
+++ b/sensors.h	Sun Oct 16 16:00:20 2016 +0000
@@ -1,11 +1,11 @@
 /* University of York Robotics Laboratory PsiSwarm Library: Sensor Functions Header File
- * 
+ *
  * Copyright 2016 University of York
  *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and limitations under the License.
  *
  * File: sensors.h
@@ -13,46 +13,151 @@
  * (C) Dept. Electronics & Computer Science, University of York
  * James Hilder, Alan Millard, Alexander Horsfield, Homero Elizondo, Jon Timmis
  *
- * PsiSwarm Library Version: 0.7
+ * PsiSwarm Library Version: 0.8
  *
  * October 2016
  *
  */
- 
+
 #ifndef SENSORS_H
 #define SENSORS_H
 
-float get_battery_voltage ( void );
-float get_current ( void );
-float get_dc_voltage ( void );
+/**
+ * Sensors class
+ * Functions to read values from the Psi Swarm infrared, ultrasonic, temperature and power sensors
+ *
+ * Example:
+ * @code
+ * #include "psiswarm.h"
+ *
+ * int main() {
+ *     init();
+ *
+ * }
+ * @endcode
+*/
+class Sensors
+{
+public:
+
+    /** Returns the current battery voltage for the robot
+     * @return The voltage (in V); this should range between 3.5V for a discharged battery and 4.2V for a fully charged battery
+     */
+    float get_battery_voltage ( void );
+
+    /** Returns the current being used by the robot
+     * @return The current (in A)
+     */
+    float get_current ( void );
+
+    /** Returns the voltage sensed from the DC input (post rectification)
+     * @return The voltage (in V); note some back-voltage from the battery is expected even when no DC input is detected
+     */
+    float get_dc_voltage ( void );
+
+    /** Returns the temperature sensed by the digital thermometer placed near the front of the MBED socket
+     * @return The temperature (in degrees C)
+     */
+    float get_temperature ( void );
+
+    /** Enables a 10Hz ticker that automatically takes readings from the SRF-02 ultrasonic sensor (if fitted)
+     */
+    void enable_ultrasonic_ticker( void );
+
+    /** Disables the ultrasonic ticker
+     */
+    void disable_ultrasonic_ticker( void );
 
-float get_temperature ( void );
-void enable_ultrasonic_ticker( void );
-void disable_ultrasonic_ticker( void );
-void update_ultrasonic_measure ( void );
-void IF_read_ultrasonic_measure ( void );
-float read_reflected_ir_distance ( char index );
-float get_reflected_ir_distance ( char index );
-unsigned short get_background_raw_ir_value ( char index );
-unsigned short get_illuminated_raw_ir_value ( char index );
-void store_reflected_ir_distances ( void );
-void store_background_raw_ir_values ( void );
-void store_illuminated_raw_ir_values ( void );
-float calculate_reflected_distance ( unsigned short background_value, unsigned short illuminated_value );
-unsigned short read_illuminated_raw_ir_value ( char index ) ;
- 
-unsigned short get_background_base_ir_value ( char index );
-unsigned short get_illuminated_base_ir_value ( char index );
-unsigned short calculate_base_ir_value ( char index );
-unsigned short calculate_side_ir_value ( char index );
+    /** Sends a message to SRF-02 ultrasonic sensor (if fitted) to instruct it to take a new reading.  The result is available approx 70ms later
+     */
+    void update_ultrasonic_measure ( void );
+    void IF_read_ultrasonic_measure ( void );
+    
+    /** Stores the raw ADC values for all 8 IR side-facing sensors without enabling IR emitters
+    */
+    void store_background_raw_ir_values ( void );
+    
+    /** Stores the raw ADC values for all 8 IR side-facing sensors after enabling IR emitters
+    */
+    void store_illuminated_raw_ir_values ( void );
+    
+    /** Stores the raw ADC values for all 8 IR side-facing sensors both before and after enabling IR emitters
+    * Calls store_background_raw_ir_values() then store_illuminated_raw_ir_values()
+    */   
+    void store_ir_values ( void );
+    
+    /** Returns the stored value of the non-illuminated side-facing IR sensor value based on last call of store_background_raw_ir_values
+    * Call either store_ir_values() or store_background_raw_ir_values() before using this function to update reading
+    * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
+    * @return Unsigned short of background IR reading (range 0 to 4095)
+    */
+    unsigned short get_background_raw_ir_value ( char index );
+    
+    /** Returns the stored value of the illuminated side-facing IR sensor value based on last call of store_illuminated_raw_ir_values
+    * Call either store_ir_values() or store_illuminated_raw_ir_values() before using this function to update reading
+    * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
+    * @return Unsigned short of illuminated IR reading (range 0 to 4095)
+    */
+    unsigned short get_illuminated_raw_ir_value ( char index );
+
+    /** Returns the subtraction of the background side IR value from the reflection based on last call of store_ir_values()
+    * For most purposes this is the best method of detected obstacles etc as it mitigates for varying background levels of IR
+    * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
+    * @return Unsigned short of compensated ir value (illuminated value - background value) (range 0 to 4095)
+    */
+    unsigned short calculate_side_ir_value ( char index );
+    
+    /** Enables the IR emitter then returns the value of the given side-facing IR sensor
+    * This function is used when just one sensor is needed to be read; in general using store_ir_values() and get_illuminated_raw_ir_value(index) is preferable
+    * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
+    * @return Unsigned short of illuminated IR reading (range 0 to 4095)
+    */
+    unsigned short read_illuminated_raw_ir_value ( char index ) ;
 
-int get_bearing_from_ir_array ( unsigned short * ir_sensor_readings);
-void store_ir_values ( void );
-void store_base_ir_values ( void );
-void store_background_base_ir_values ( void );
-void store_illuminated_base_ir_values ( void );
+    /** Stores the raw ADC values for all 5 base IR sensors without enabling IR emitters
+    */
+    void store_background_base_ir_values ( void );
+    
+    /** Stores the raw ADC values for all 5 base IR sensors after enabling IR emitters
+    */
+    void store_illuminated_base_ir_values ( void );
 
-void store_line_position ( void );
-void calibrate_base_ir_sensors ( void );
+    /** Stores the raw ADC values for all 5 base IR sensors both before and after enabling IR emitters
+    * Calls store_background_base_ir_values() then store_illuminated_base_ir_values()
+    */   
+    void store_base_ir_values ( void );
+    
+    /** Returns the stored value of the non-illuminated base IR sensor value based on last call of store_background_base_ir_values
+    * Call either store_base_ir_values() or store_background_base_ir_values() before using this function to update reading
+    * @param index - The index of the sensor to read (range 0 to 4, sensor from left to right viewed from above - 2 is in middle of front)
+    * @return Unsigned short of background IR reading (range 0 to 4095)
+    */
+    unsigned short get_background_base_ir_value ( char index );
+    
+    /** Returns the stored value of the illuminated base IR sensor value based on last call of store_illuminated_base_ir_values
+    * Call either store_base_ir_values() or store_illuminated_base_ir_values() before using this function to update reading
+    * @param index - The index of the sensor to read (range 0 to 4, sensor from left to right viewed from above - 2 is in middle of front)
+    * @return Unsigned short of illuminated IR reading (range 0 to 4095)
+    */
+    unsigned short get_illuminated_base_ir_value ( char index );
+    
+    
+    /** Returns the subtraction of the background base IR value from the reflection based on last call of store_base_ir_values()
+    * For most purposes this is the best method of getting values from the base IR sensor as it mitigates for background levels of IR
+    * @param index - The index of the sensor to read (range 0 to 4, sensor from left to right viewed from above - 2 is in middle of front)
+    * @return Unsigned short of compensated ir value (illuminated value - background value) (range 0 to 4095)
+    */
+    unsigned short calculate_base_ir_value ( char index );
+    
+    // The following functions are used for special programs or to retain backwards compatability but are not documented as part of the API
+    
+    void store_reflected_ir_distances ( void );
+    float read_reflected_ir_distance ( char index );
+    float get_reflected_ir_distance ( char index );
+    float calculate_reflected_distance ( unsigned short background_value, unsigned short illuminated_value );
+    int get_bearing_from_ir_array ( unsigned short * ir_sensor_readings);
+    void store_line_position ( void );
+    void calibrate_base_ir_sensors ( void );
 
+};
 #endif
\ No newline at end of file