Psi Swarm robot library version 0.9
Fork of PsiSwarmV9 by
sensors.h@20:1bc6c6dc477b, 2018-05-14 (annotated)
- Committer:
- jah128
- Date:
- Mon May 14 15:35:38 2018 +0000
- Revision:
- 20:1bc6c6dc477b
- Parent:
- 18:9204f74069b4
Updated?
Who changed what in which revision?
User | Revision | Line number | New 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 |