Psi Swarm Robot / PsiSwarmV9

Psi Swarm robot library version 0.9

Dependents:   PsiSwarm_V9_Blank

Fork of PsiSwarmV9 by James Hilder

sensors.h@20:2b6ebe60929d, 2019-07-08 (annotated)

Committer:
richardredpath
Date:
Mon Jul 08 10:50:40 2019 +0000
Revision:
20:2b6ebe60929d
Parent:
18:9204f74069b4 
Fixed deprecated warnings for callbacks throughout the library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jah128 0:d6269d17c8cf 1 /* University of York Robotics Laboratory PsiSwarm Library: Sensor Functions Header File
jah128 10:e58323951c08 2 *
jah128 16:50686c07ad07 3 * Copyright 2017 University of York
jah128 6:b340a527add9 4 *
jah128 10:e58323951c08 5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
jah128 6:b340a527add9 6 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
jah128 6:b340a527add9 7 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS
jah128 10:e58323951c08 8 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
jah128 6:b340a527add9 9 * See the License for the specific language governing permissions and limitations under the License.
jah128 6:b340a527add9 10 *
jah128 0:d6269d17c8cf 11 * File: sensors.h
jah128 0:d6269d17c8cf 12 *
jah128 0:d6269d17c8cf 13 * (C) Dept. Electronics & Computer Science, University of York
jah128 0:d6269d17c8cf 14 * James Hilder, Alan Millard, Alexander Horsfield, Homero Elizondo, Jon Timmis
jah128 0:d6269d17c8cf 15 *
jah128 10:e58323951c08 16 * PsiSwarm Library Version: 0.8
jah128 0:d6269d17c8cf 17 *
jah128 16:50686c07ad07 18 * June 2017
jah128 0:d6269d17c8cf 19 *
jah128 0:d6269d17c8cf 20 */
jah128 10:e58323951c08 21
jah128 0:d6269d17c8cf 22 #ifndef SENSORS_H
jah128 0:d6269d17c8cf 23 #define SENSORS_H
jah128 0:d6269d17c8cf 24
jah128 10:e58323951c08 25 /**
jah128 10:e58323951c08 26 * Sensors class
jah128 10:e58323951c08 27 * Functions to read values from the Psi Swarm infrared, ultrasonic, temperature and power sensors
jah128 10:e58323951c08 28 *
jah128 10:e58323951c08 29 * Example:
jah128 10:e58323951c08 30 * @code
jah128 10:e58323951c08 31 * #include "psiswarm.h"
jah128 10:e58323951c08 32 *
jah128 10:e58323951c08 33 * int main() {
jah128 10:e58323951c08 34 * init();
jah128 10:e58323951c08 35 *
jah128 10:e58323951c08 36 * }
jah128 10:e58323951c08 37 * @endcode
jah128 10:e58323951c08 38 */
jah128 10:e58323951c08 39 class Sensors
jah128 10:e58323951c08 40 {
jah128 10:e58323951c08 41 public:
jah128 10:e58323951c08 42
jah128 10:e58323951c08 43 /** Returns the current battery voltage for the robot
jah128 10:e58323951c08 44 * @return The voltage (in V); this should range between 3.5V for a discharged battery and 4.2V for a fully charged battery
jah128 10:e58323951c08 45 */
jah128 10:e58323951c08 46 float get_battery_voltage ( void );
jah128 10:e58323951c08 47
jah128 10:e58323951c08 48 /** Returns the current being used by the robot
jah128 10:e58323951c08 49 * @return The current (in A)
jah128 10:e58323951c08 50 */
jah128 10:e58323951c08 51 float get_current ( void );
jah128 10:e58323951c08 52
jah128 10:e58323951c08 53 /** Returns the voltage sensed from the DC input (post rectification)
jah128 10:e58323951c08 54 * @return The voltage (in V); note some back-voltage from the battery is expected even when no DC input is detected
jah128 10:e58323951c08 55 */
jah128 10:e58323951c08 56 float get_dc_voltage ( void );
jah128 10:e58323951c08 57
jah128 10:e58323951c08 58 /** Returns the temperature sensed by the digital thermometer placed near the front of the MBED socket
jah128 10:e58323951c08 59 * @return The temperature (in degrees C)
jah128 10:e58323951c08 60 */
jah128 10:e58323951c08 61 float get_temperature ( void );
jah128 10:e58323951c08 62
jah128 10:e58323951c08 63 /** Enables a 10Hz ticker that automatically takes readings from the SRF-02 ultrasonic sensor (if fitted)
jah128 10:e58323951c08 64 */
jah128 10:e58323951c08 65 void enable_ultrasonic_ticker( void );
jah128 10:e58323951c08 66
jah128 10:e58323951c08 67 /** Disables the ultrasonic ticker
jah128 10:e58323951c08 68 */
jah128 10:e58323951c08 69 void disable_ultrasonic_ticker( void );
jah128 0:d6269d17c8cf 70
jah128 10:e58323951c08 71 /** 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
jah128 10:e58323951c08 72 */
jah128 10:e58323951c08 73 void update_ultrasonic_measure ( void );
jah128 10:e58323951c08 74 void IF_read_ultrasonic_measure ( void );
jah128 10:e58323951c08 75
jah128 10:e58323951c08 76 /** Stores the raw ADC values for all 8 IR side-facing sensors without enabling IR emitters
jah128 10:e58323951c08 77 */
jah128 10:e58323951c08 78 void store_background_raw_ir_values ( void );
jah128 10:e58323951c08 79
jah128 10:e58323951c08 80 /** Stores the raw ADC values for all 8 IR side-facing sensors after enabling IR emitters
jah128 10:e58323951c08 81 */
jah128 10:e58323951c08 82 void store_illuminated_raw_ir_values ( void );
jah128 10:e58323951c08 83
jah128 10:e58323951c08 84 /** Stores the raw ADC values for all 8 IR side-facing sensors both before and after enabling IR emitters
jah128 10:e58323951c08 85 * Calls store_background_raw_ir_values() then store_illuminated_raw_ir_values()
jah128 10:e58323951c08 86 */
jah128 10:e58323951c08 87 void store_ir_values ( void );
jah128 10:e58323951c08 88
jah128 10:e58323951c08 89 /** Returns the stored value of the non-illuminated side-facing IR sensor value based on last call of store_background_raw_ir_values
jah128 10:e58323951c08 90 * Call either store_ir_values() or store_background_raw_ir_values() before using this function to update reading
jah128 10:e58323951c08 91 * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
jah128 10:e58323951c08 92 * @return Unsigned short of background IR reading (range 0 to 4095)
jah128 10:e58323951c08 93 */
jah128 10:e58323951c08 94 unsigned short get_background_raw_ir_value ( char index );
jah128 10:e58323951c08 95
jah128 10:e58323951c08 96 /** Returns the stored value of the illuminated side-facing IR sensor value based on last call of store_illuminated_raw_ir_values
jah128 10:e58323951c08 97 * Call either store_ir_values() or store_illuminated_raw_ir_values() before using this function to update reading
jah128 10:e58323951c08 98 * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
jah128 10:e58323951c08 99 * @return Unsigned short of illuminated IR reading (range 0 to 4095)
jah128 10:e58323951c08 100 */
jah128 10:e58323951c08 101 unsigned short get_illuminated_raw_ir_value ( char index );
jah128 10:e58323951c08 102
jah128 10:e58323951c08 103 /** Returns the subtraction of the background side IR value from the reflection based on last call of store_ir_values()
jah128 10:e58323951c08 104 * For most purposes this is the best method of detected obstacles etc as it mitigates for varying background levels of IR
jah128 10:e58323951c08 105 * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
jah128 10:e58323951c08 106 * @return Unsigned short of compensated ir value (illuminated value - background value) (range 0 to 4095)
jah128 10:e58323951c08 107 */
jah128 10:e58323951c08 108 unsigned short calculate_side_ir_value ( char index );
jah128 10:e58323951c08 109
jah128 10:e58323951c08 110 /** Enables the IR emitter then returns the value of the given side-facing IR sensor
jah128 10:e58323951c08 111 * 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
jah128 10:e58323951c08 112 * @param index - The index of the sensor to read (range 0 to 7, clockwise around robot from front-right)
jah128 10:e58323951c08 113 * @return Unsigned short of illuminated IR reading (range 0 to 4095)
jah128 10:e58323951c08 114 */
jah128 10:e58323951c08 115 unsigned short read_illuminated_raw_ir_value ( char index ) ;
jah128 0:d6269d17c8cf 116
jah128 10:e58323951c08 117 /** Stores the raw ADC values for all 5 base IR sensors without enabling IR emitters
jah128 10:e58323951c08 118 */
jah128 10:e58323951c08 119 void store_background_base_ir_values ( void );
jah128 10:e58323951c08 120
jah128 10:e58323951c08 121 /** Stores the raw ADC values for all 5 base IR sensors after enabling IR emitters
jah128 10:e58323951c08 122 */
jah128 10:e58323951c08 123 void store_illuminated_base_ir_values ( void );
jah128 0:d6269d17c8cf 124
jah128 10:e58323951c08 125 /** Stores the raw ADC values for all 5 base IR sensors both before and after enabling IR emitters
jah128 10:e58323951c08 126 * Calls store_background_base_ir_values() then store_illuminated_base_ir_values()
jah128 10:e58323951c08 127 */
jah128 10:e58323951c08 128 void store_base_ir_values ( void );
jah128 10:e58323951c08 129
jah128 10:e58323951c08 130 /** Returns the stored value of the non-illuminated base IR sensor value based on last call of store_background_base_ir_values
jah128 10:e58323951c08 131 * Call either store_base_ir_values() or store_background_base_ir_values() before using this function to update reading
jah128 10:e58323951c08 132 * @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)
jah128 10:e58323951c08 133 * @return Unsigned short of background IR reading (range 0 to 4095)
jah128 10:e58323951c08 134 */
jah128 10:e58323951c08 135 unsigned short get_background_base_ir_value ( char index );
jah128 10:e58323951c08 136
jah128 10:e58323951c08 137 /** Returns the stored value of the illuminated base IR sensor value based on last call of store_illuminated_base_ir_values
jah128 10:e58323951c08 138 * Call either store_base_ir_values() or store_illuminated_base_ir_values() before using this function to update reading
jah128 10:e58323951c08 139 * @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)
jah128 10:e58323951c08 140 * @return Unsigned short of illuminated IR reading (range 0 to 4095)
jah128 10:e58323951c08 141 */
jah128 10:e58323951c08 142 unsigned short get_illuminated_base_ir_value ( char index );
jah128 10:e58323951c08 143
jah128 10:e58323951c08 144
jah128 10:e58323951c08 145 /** Returns the subtraction of the background base IR value from the reflection based on last call of store_base_ir_values()
jah128 17:bf614e28668f 146 * For most purposes this is the best method of getting uncalibrated values from the base IR sensor as it mitigates for background levels of IR
jah128 10:e58323951c08 147 * @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)
jah128 10:e58323951c08 148 * @return Unsigned short of compensated ir value (illuminated value - background value) (range 0 to 4095)
jah128 10:e58323951c08 149 */
jah128 10:e58323951c08 150 unsigned short calculate_base_ir_value ( char index );
jah128 10:e58323951c08 151
jah128 17:bf614e28668f 152 /** Returns the calibrated base IR value adjusted for light\dark calibration values
jah128 17:bf614e28668f 153 * Range is 0.0 to 1.0 where 0.1 is calibrated black value and 0.9 calibrated white value for given sensor
jah128 17:bf614e28668f 154 * If sensor calibration has not been performed and stored in EEPROM used pretested values stored in settings.h
jah128 17:bf614e28668f 155 * NB IR sensor is very material dependant (eg matt paper vs glossy paper): values tested using basic 80gsm copier paper
jah128 17:bf614e28668f 156 * @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)
jah128 17:bf614e28668f 157 * @return Float of compensated ir value (range 0-1, black value = 0.1, white value = 0.9)
jah128 17:bf614e28668f 158 */
jah128 17:bf614e28668f 159 float get_calibrated_base_ir_value ( char index );
jah128 17:bf614e28668f 160
jah128 17:bf614e28668f 161 /** Determines the position of a black line on a white surface using the base IR sensors
jah128 17:bf614e28668f 162 * Uses the calibrated sensor values
jah128 17:bf614e28668f 163 *
jah128 17:bf614e28668f 164 * Sets global variable 'line_found' to either 1 if line detected or 0 if line not found
jah128 17:bf614e28668f 165 * Sets global variable 'line_position' (float) to a value ranging from -1.0 (line fully left) to 1.0 (line fully right)
jah128 17:bf614e28668f 166 * [Should range from about -0.5 to 0.5 when center sensor can see line]
jah128 17:bf614e28668f 167 */
jah128 17:bf614e28668f 168 void store_line_position (float line_threshold);
jah128 17:bf614e28668f 169 void store_line_position ( void );
jah128 17:bf614e28668f 170
jah128 17:bf614e28668f 171
jah128 10:e58323951c08 172 // The following functions are used for special programs or to retain backwards compatability but are not documented as part of the API
jah128 10:e58323951c08 173
jah128 10:e58323951c08 174 void store_reflected_ir_distances ( void );
jah128 10:e58323951c08 175 float read_reflected_ir_distance ( char index );
jah128 10:e58323951c08 176 float get_reflected_ir_distance ( char index );
jah128 10:e58323951c08 177 float calculate_reflected_distance ( unsigned short background_value, unsigned short illuminated_value );
jah128 10:e58323951c08 178 int get_bearing_from_ir_array ( unsigned short * ir_sensor_readings);
jah128 17:bf614e28668f 179
jah128 17:bf614e28668f 180 void store_line_position_old ( void );
jah128 17:bf614e28668f 181 void calibrate_base_sensors ( void );
jah128 17:bf614e28668f 182 void IF_set_base_calibration_values(int bir1w, int bir2w, int bir3w, int bir4w, int bir5w, int bir1b, int bir2b, int bir3b, int bir4b, int bir5b);
jah128 18:9204f74069b4 183 const char * IF_get_base_calibration_values_string( void );
jah128 0:d6269d17c8cf 184
jah128 10:e58323951c08 185 };
jah128 0:d6269d17c8cf 186 #endif