non blocking commands, 3. Party libs and updates

Author: ArminJo

.github/workflows/TestCompile.yml

@@ -76,7 +76,7 @@ jobs:
         uses: actions/checkout@master
 
       - name: Checkout new BlueDisplay library
-        uses: actions/checkout@v3
+        uses: actions/checkout@master
         with:
           repository: ArminJo/Arduino-BlueDisplay
           ref: master
@@ -85,7 +85,7 @@ jobs:
 
 # Currently included in source directory
 #      - name: Checkout new PWMMotorControl library
-#        uses: actions/checkout@v3
+#        uses: actions/checkout@master
 #        with:
 #          repository: ArminJo/PWMMotorControl
 #          ref: master

README.md

@@ -24,11 +24,13 @@ Requires the Arduino library [BlueDisplay](https://github.com/ArminJo/Arduino-Bl
 
 #### If you find this program useful, please give it a star.
 
+🌎 [Google Translate](https://translate.google.com/translate?sl=en&u=https://github.com/ArminJo/Arduino-RobotCar)
+
 <br/>
 
 # Features
 - Obstacles avoidance by a HC-SR04 ultrasonic sensor mounted on a SG90 Servo which continuously scans the environment.
-- To overcome the drawbacks of ultrasonic sensors, an additional IR or TOF (TimeOfFlight) sensor can be mounted to the servo.
+- To overcome the drawbacks of ultrasonic sensors, an additional Sharp 430/1080/20150/100550 (GP2Y0A21YK0F) IR or VL53L1X TOF (TimeOfFlight) sensor can be mounted to the servo.
 - Manual control implemented by a GUI using a Bluetooth HC-05 Module and the [BlueDisplay library](https://github.com/ArminJo/Arduino-BlueDisplay).
 
 **Just overwrite the function doUserCollisionAvoiding() to test your own skill**.
@@ -101,10 +103,10 @@ Compile options for the used **PWMMotorControl library** like `USE_ENCODER_MOTOR
 | `CAR_HAS_TOF_DISTANCE_SENSOR` | disabled | Use VL53L1X TimeOfFlight distance sensor. |
 | `CAR_HAS_DISTANCE_SERVO` | disabled | Distance sensor is mounted on a pan servo (default for most China smart cars). |
 | `DISTANCE_SERVO_IS_MOUNTED_HEAD_DOWN` | disabled | Distance.h | The distance servo is mounted head down to detect even small obstacles. The Servo direction is reverse then. |
-| `CAR_HAS_PAN_SERVO` | disabled | Enables the pan slider for the `PanServo` at the `PIN_PAN_SERVO` pin. |
-| `CAR_HAS_TILT_SERVO` | disabled | Enables the tilt slider for the `TiltServo` at the `PIN_TILT_SERVO` pin. |
-| `CAR_HAS_CAMERA` | disabled | Enables the `Camera` button for the `PIN_CAMERA_SUPPLY_CONTROL` pin. |
-| `CAR_HAS_LASER` | disabled | Enables the `Laser` button for the `PIN_LASER_OUT` / `LED_BUILTIN` pin. |
+| `CAR_HAS_PAN_SERVO` | disabled | Enables the pan slider for the `PanServo` at the `PAN_SERVO_PIN` pin. |
+| `CAR_HAS_TILT_SERVO` | disabled | Enables the tilt slider for the `TiltServo` at the `TILT_SERVO_PIN` pin. |
+| `CAR_HAS_CAMERA` | disabled | Enables the `Camera` button for the `CAMERA_SUPPLY_CONTROL_PIN` pin. |
+| `CAR_HAS_LASER` | disabled | Enables the `Laser` button for the `LASER_OUT_PIN` / `LED_BUILTIN` pin. |
 | `ENABLE_RTTTL_FOR_CAR` | undefined | Plays melody after initial timeout has reached. Enables the Melody button, which plays a random melody. |
 | `MONITOR_VIN_VOLTAGE` | disabled | Shows VIN voltage and monitors it for undervoltage. VIN/11 at A2, 1 M&ohm; to VIN, 100 k&ohm; to ground. |
 | `ENABLE_EEPROM_STORAGE` | disabled | Activates the buttons to store compensation values. Normally they are stored after calibration. |

src/ADCUtils.h

@@ -112,8 +112,47 @@
 #error "No temperature channel definitions specified for this AVR CPU"
 #endif
 
-extern float sVCCVoltage;
-extern uint16_t sVCCVoltageMillivolt;
+/*
+ * Thresholds for OVER and UNDER voltage and detection of kind of power supply (USB or Li-ion)
+ *
+ * Default values are suitable for Li-ion batteries.
+ * We normally have voltage drop at the connectors, so the battery voltage is assumed slightly higher, than the Arduino VCC.
+ * But keep in mind that the ultrasonic distance module HC-SR04 may not work reliable below 3.7 volt.
+ */
+#if !defined(LI_ION_VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define LI_ION_VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT             3400 // Do not stress your battery and we require some power for standby
+#endif
+#if !defined(LI_ION_VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define LI_ION_VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT   3000 // Many Li-ions are specified down to 3.0 volt
+#endif
+
+#if !defined(VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT            LI_ION_VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT
+#endif
+#if !defined(VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT  LI_ION_VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT
+#endif
+#if !defined(VCC_OVERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define VCC_OVERVOLTAGE_THRESHOLD_MILLIVOLT             5250 // + 5 % operation voltage
+#endif
+#if !defined(VCC_EMERGENCY_OVERVOLTAGE_THRESHOLD_MILLIVOLT)
+#define VCC_EMERGENCY_OVERVOLTAGE_THRESHOLD_MILLIVOLT   5500 // +10 %. Max recommended operation voltage
+#endif
+#if !defined(VCC_CHECK_PERIOD_MILLIS)
+#define VCC_CHECK_PERIOD_MILLIS                         10000L // 10 seconds period of VCC checks
+#endif
+#if !defined(VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP)
+#define VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP     6 // Shutdown after 6 times (60 seconds) VCC below VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT or 1 time below VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT
+#endif
+
+#if !defined(VOLTAGE_USB_POWERED_LOWER_THRESHOLD_MILLIVOLT)
+#define VOLTAGE_USB_POWERED_LOWER_THRESHOLD_MILLIVOLT   4300 // Assume USB powered above this voltage
+#endif
+
+#if !defined(VOLTAGE_USB_POWERED_UPPER_THRESHOLD_MILLIVOLT)
+#define VOLTAGE_USB_POWERED_UPPER_THRESHOLD_MILLIVOLT   4950 // Assume USB powered below this voltage, because of the loss in USB cable. If we have > 4950, we assume to be powered by VIN.
+// In contrast to e.g. powered by VIN, which results in almost perfect 5 volt supply
+#endif
 
 extern long sLastVCCCheckMillis;
 extern uint8_t sVCCTooLowCounter;
@@ -124,7 +163,6 @@ uint16_t waitAndReadADCChannelWithReference(uint8_t aADCChannelNumber, uint8_t a
 uint16_t waitAndReadADCChannelWithReferenceAndRestoreADMUXAndReference(uint8_t aADCChannelNumber, uint8_t aReference);
 uint16_t readADCChannelWithOversample(uint8_t aADCChannelNumber, uint8_t aOversampleExponent);
 void setADCChannelAndReferenceForNextConversion(uint8_t aADCChannelNumber, uint8_t aReference);
-uint16_t readADCChannelWithReferenceOversample(uint8_t aADCChannelNumber, uint8_t aReference, uint8_t aOversampleExponent);
 uint16_t readADCChannelWithReferenceOversampleFast(uint8_t aADCChannelNumber, uint8_t aReference, uint8_t aOversampleExponent);
 uint16_t readADCChannelWithReferenceMultiSamples(uint8_t aADCChannelNumber, uint8_t aReference, uint8_t aNumberOfSamples);
 uint16_t readADCChannelWithReferenceMax(uint8_t aADCChannelNumber, uint8_t aReference, uint16_t aNumberOfSamples);
@@ -139,9 +177,7 @@ uint8_t checkAndWaitForReferenceAndChannelToSwitch(uint8_t aADCChannelNumber, ui
  */
 float getVCCVoltageSimple(void);
 void readVCCVoltageSimple(void);
-uint16_t getVCCVoltageMillivoltSimple(void);
 void readVCCVoltageMillivoltSimple(void);
-float getVCCVoltage(void);
 void readVCCVoltage(void);
 uint16_t getVCCVoltageMillivolt(void);
 void readVCCVoltageMillivolt(void);
@@ -156,11 +192,27 @@ float getCPUTemperatureSimple(void);
 float getCPUTemperature(void);
 float getTemperature(void) __attribute__ ((deprecated ("Renamed to getCPUTemperature()"))); // deprecated
 
-bool isVCCTooLowMultipleTimes();
-void resetVCCTooLowMultipleTimes();
-bool isVCCTooLow();
-bool isVCCTooHigh();
-bool isVCCTooHighSimple();
+bool isVCCUSBPowered();
+bool isVCCUSBPowered(Print *aSerial);
+bool isVCCUndervoltageMultipleTimes();
+void resetCounterForVCCUndervoltageMultipleTimes();
+bool isVCCUndervoltage();
+bool isVCCEmergencyUndervoltage();
+bool isVCCOvervoltage();
+bool isVCCOvervoltageSimple();
 
 #endif //  defined(__AVR__) ...
+
+/*
+ * Variables and functions defined as dummies to allow for seamless compiling on non AVR platforms
+ */
+extern float sVCCVoltage;
+extern uint16_t sVCCVoltageMillivolt;
+
+uint16_t readADCChannelWithReferenceOversample(uint8_t aADCChannelNumber, uint8_t aReference, uint8_t aOversampleExponent);
+
+uint16_t getVCCVoltageMillivoltSimple(void);
+float getVCCVoltage(void);
+float getCPUTemperature(void);
+
 #endif // _ADC_UTILS_H

src/ADCUtils.hpp

@@ -58,7 +58,7 @@ union WordUnionForADCUtils {
  * Enable this to see information on each call.
  * Since there should be no library which uses Serial, it should only be enabled for development purposes.
  */
-#if defined(DEBUG)
+#if defined(DEBUG) && !defined(LOCAL_DEBUG)
 #define LOCAL_DEBUG
 #else
 //#define LOCAL_DEBUG // This enables debug output only for this file
@@ -481,7 +481,7 @@ void readAndPrintVCCVoltageMillivolt(Print *aSerial) {
 void readVCCVoltageSimple(void) {
     // use AVCC with (optional) external capacitor at AREF pin as reference
     float tVCC = readADCChannelWithReferenceMultiSamples(ADC_1_1_VOLT_CHANNEL_MUX, DEFAULT, 4);
-    sVCCVoltage = (1023 * 1.1 * 4) / tVCC;
+    sVCCVoltage = (1023 * (((float) ADC_INTERNAL_REFERENCE_MILLIVOLT) / 1000) * 4) / tVCC;
 }
 
 /*
@@ -540,33 +540,37 @@ uint16_t getVoltageMillivoltWith_1_1VoltReference(uint8_t aADCChannelForVoltageM
 }
 
 /*
- * Default values are suitable for Li-ion batteries.
- * We normally have voltage drop at the connectors, so the battery voltage is assumed slightly higher, than the Arduino VCC.
- * But keep in mind that the ultrasonic distance module HC-SR04 may not work reliable below 3.7 volt.
+ * Return true if sVCCVoltageMillivolt is > 4.3 V and < 4.95 V
  */
-#if !defined(VCC_STOP_THRESHOLD_MILLIVOLT)
-#define VCC_STOP_THRESHOLD_MILLIVOLT    3400 // Do not stress your battery and we require some power for standby
-#endif
-#if !defined(VCC_EMERGENCY_STOP_MILLIVOLT)
-#define VCC_EMERGENCY_STOP_MILLIVOLT    3000 // Many Li-ions are specified down to 3.0 volt
-#endif
-#if !defined(VCC_TOO_HIGH_STOP_MILLIVOLT)
-#define VCC_TOO_HIGH_STOP_MILLIVOLT    5250 // + 5 % operation voltage
-#endif
-#if !defined(VCC_TOO_HIGH_EMERGENCY_STOP_MILLIVOLT)
-#define VCC_TOO_HIGH_EMERGENCY_STOP_MILLIVOLT    5500 // +10 %. Max recommended operation voltage
-#endif
-#if !defined(VCC_CHECK_PERIOD_MILLIS)
-#define VCC_CHECK_PERIOD_MILLIS        10000 // Period of VCC checks
-#endif
-#if !defined(VCC_CHECKS_TOO_LOW_BEFORE_STOP)
-#define VCC_CHECKS_TOO_LOW_BEFORE_STOP     6 // Shutdown after 6 times (60 seconds) VCC below VCC_STOP_THRESHOLD_MILLIVOLT or 1 time below VCC_EMERGENCY_STOP_MILLIVOLT
-#endif
+bool isVCCUSBPowered() {
+    readVCCVoltageMillivolt();
+    return (VOLTAGE_USB_POWERED_LOWER_THRESHOLD_MILLIVOLT < sVCCVoltageMillivolt
+            && sVCCVoltageMillivolt < VOLTAGE_USB_POWERED_UPPER_THRESHOLD_MILLIVOLT);
+}
 
 /*
- * @ return true only once, when VCC_CHECKS_TOO_LOW_BEFORE_STOP (6) times voltage too low -> shutdown
+ * Return true if sVCCVoltageMillivolt is > 4.3 V and < 4.95 V
  */
-bool isVCCTooLowMultipleTimes() {
+bool isVCCUSBPowered(Print *aSerial) {
+    readVCCVoltageMillivolt();
+    aSerial->print(F("USB powered is "));
+    bool tReturnValue;
+    if (VOLTAGE_USB_POWERED_LOWER_THRESHOLD_MILLIVOLT
+            < sVCCVoltageMillivolt && sVCCVoltageMillivolt < VOLTAGE_USB_POWERED_UPPER_THRESHOLD_MILLIVOLT) {
+        tReturnValue = true;
+        aSerial->print(F("true "));
+    } else {
+        tReturnValue = false;
+        aSerial->print(F("false "));
+    }
+    printVCCVoltageMillivolt(aSerial);
+    return tReturnValue;
+}
+
+/*
+ * @ return true only once, when VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP (6) times voltage too low -> shutdown
+ */
+bool isVCCUndervoltageMultipleTimes() {
     /*
      * Check VCC every VCC_CHECK_PERIOD_MILLIS (10) seconds
      */
@@ -580,33 +584,35 @@ bool isVCCTooLowMultipleTimes() {
         readVCCVoltageMillivolt();
 #  endif
 
-        if (sVCCTooLowCounter < VCC_CHECKS_TOO_LOW_BEFORE_STOP) {
+        if (sVCCTooLowCounter < VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP) {
             /*
              * Do not check again if shutdown has happened
              */
-            if (sVCCVoltageMillivolt > VCC_STOP_THRESHOLD_MILLIVOLT) {
+            if (sVCCVoltageMillivolt > VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT) {
                 sVCCTooLowCounter = 0; // reset counter
             } else {
                 /*
-                 * Voltage too low, wait VCC_CHECKS_TOO_LOW_BEFORE_STOP (6) times and then shut down.
+                 * Voltage too low, wait VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP (6) times and then shut down.
                  */
-                if (sVCCVoltageMillivolt < VCC_EMERGENCY_STOP_MILLIVOLT) {
+                if (sVCCVoltageMillivolt < VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT) {
                     // emergency shutdown
-                    sVCCTooLowCounter = VCC_CHECKS_TOO_LOW_BEFORE_STOP;
+                    sVCCTooLowCounter = VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP;
 #  if defined(INFO)
-                    Serial.println(F("Voltage < " STR(VCC_EMERGENCY_STOP_MILLIVOLT) " mV detected -> emergency shutdown"));
+                    Serial.println(
+                            F(
+                                    "Voltage < " STR(VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT) " mV detected -> emergency shutdown"));
 #  endif
                 } else {
                     sVCCTooLowCounter++;
 #  if defined(INFO)
-                    Serial.print(F("Voltage < " STR(VCC_STOP_THRESHOLD_MILLIVOLT) " mV detected: "));
-                    Serial.print(VCC_CHECKS_TOO_LOW_BEFORE_STOP - sVCCTooLowCounter);
+                    Serial.print(F("Voltage < " STR(VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT) " mV detected: "));
+                    Serial.print(VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP - sVCCTooLowCounter);
                     Serial.println(F(" tries left"));
 #  endif
                 }
-                if (sVCCTooLowCounter == VCC_CHECKS_TOO_LOW_BEFORE_STOP) {
+                if (sVCCTooLowCounter == VCC_UNDERVOLTAGE_CHECKS_BEFORE_STOP) {
                     /*
-                     * 6 times voltage too low -> shutdown
+                     * 6 times voltage too low -> return signal for shutdown etc.
                      */
                     return true;
                 }
@@ -617,13 +623,22 @@ bool isVCCTooLowMultipleTimes() {
 }
 
 /*
- * Return true if VCC_EMERGENCY_STOP_MILLIVOLT (3 V) reached
+ * Return true if VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT (3 V) reached
  */
-bool isVCCTooLow() {
-    return (sVCCVoltageMillivolt < VCC_EMERGENCY_STOP_MILLIVOLT);
+bool isVCCUndervoltage() {
+    readVCCVoltageMillivolt();
+    return (sVCCVoltageMillivolt < VCC_UNDERVOLTAGE_THRESHOLD_MILLIVOLT);
 }
 
-void resetVCCTooLowMultipleTimes() {
+/*
+ * Return true if VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT (3 V) reached
+ */
+bool isVCCEmergencyUndervoltage() {
+    readVCCVoltageMillivolt();
+    return (sVCCVoltageMillivolt < VCC_EMERGENCY_UNDERVOLTAGE_THRESHOLD_MILLIVOLT);
+}
+
+void resetCounterForVCCUndervoltageMultipleTimes() {
     sVCCTooLowCounter = 0;
 }
 
@@ -636,13 +651,13 @@ void resetVCCTooLowMultipleTimes() {
  * Raw reading of 1.1 V is 204 at 5.5 V (+10 %).
  * @return true if 5 % overvoltage reached
  */
-bool isVCCTooHigh() {
+bool isVCCOvervoltage() {
     readVCCVoltageMillivolt();
-    return (sVCCVoltageMillivolt > VCC_TOO_HIGH_STOP_MILLIVOLT);
+    return (sVCCVoltageMillivolt > VCC_OVERVOLTAGE_THRESHOLD_MILLIVOLT);
 }
-bool isVCCTooHighSimple() {
+bool isVCCOvervoltageSimple() {
     readVCCVoltageMillivoltSimple();
-    return (sVCCVoltageMillivolt > VCC_TOO_HIGH_STOP_MILLIVOLT);
+    return (sVCCVoltageMillivolt > VCC_OVERVOLTAGE_THRESHOLD_MILLIVOLT);
 }
 
 /*
@@ -688,22 +703,27 @@ float getCPUTemperature(void) {
 #endif
 }
 
-#elif defined(ARDUINO_ARCH_APOLLO3) // defined(ADC_UTILS_ARE_AVAILABLE)
-    void ADCUtilsDummyToAvoidBFDAssertions(){
-        ;
-    }
-
 #else // defined(ADC_UTILS_ARE_AVAILABLE)
 // Dummy definition of functions defined in ADCUtils to compile examples without errors
+/*
+ * Persistent storage for VCC value
+ */
+float sVCCVoltage;
+uint16_t sVCCVoltageMillivolt;
+
+uint16_t getVCCVoltageMillivoltSimple(void){
+    return 3300;
+}
+
 uint16_t readADCChannelWithReferenceOversample(uint8_t aChannelNumber __attribute__((unused)),
         uint8_t aReference __attribute__((unused)), uint8_t aOversampleExponent __attribute__((unused))) {
     return 0;
 }
 float getCPUTemperature() {
-    return 0.0;
+    return 20.0;
 }
 float getVCCVoltage() {
-    return 0.0;
+    return 3.3;
 }
 #endif // defined(ADC_UTILS_ARE_AVAILABLE)