HCSR04 for 1 pin mode sensors

ArminJo · ArminJo · commit 98c5c207c77a · 2020-02-04T22:52:01.000+01:00
diff --git a/README.md b/README.md
@@ -4,35 +4,53 @@
 [![Build Status](https://travis-ci.org/ArminJo/Arduino-Utils.svg?branch=master)](https://travis-ci.org/ArminJo/Arduino-Utils)
 
 ## My utility collection for Arduino
-Contains utility files:
-### ADCUtils
+
+### ADCUtils.cpp
 - Fast and flexible ADC conversions.
 ### HCSR04
 - Blocking and **non-blocking** reading of HCSR04 US Sensors with timeouts and exact conversions.
-### BlinkLed
+- Supports also **1 Pin mode** available with the HY-SRF05 or Parallax PING modules. 
+#### You can modify the HCSR04 modules to 1 Pin mode by:
+1 Old module with 3 16 pin chips: Connect Trigger and Echo direct or use a resistor < 4.7 kOhm. 
+If you remove both 10 kOhm pullup resistor you can use a connecting resistor < 47 kOhm, but I suggest to use 10 kOhm which is more reliable.
+2 Old module with 3 16 pin chips but with no pullup resistors near the connector row: Connect Trigger and Echo with a resistor > 200 Ohm. Use 10 kOhm.
+3 New module with 1 16 pin and 2 8 pin chips: Connect Trigger and Echo by a resistor > 200 Ohm and < 22 kOhm.
+4 All modules: Connect Trigger and Echo by a resistor of 4.7 kOhm.
+
+### BlinkLed.cpp
 - Class for blinking one ore more LED's in different fashions.
 ### ShowInfo
 - Serial.print display of timer and other peripheral and system registers (to be extended :-)).
-### AVRUtils
+### AVRUtils.cpp
 - Sleep and sleep with watchdog functions.
 - Available Ram, Heap / Stack memory display.
-### MillisUtils
+### MillisUtils.cpp
 - Tweaking `millis()` after long running tasks in `noIterrupt()` context like NeoPixel output, ADC buffer reading etc.
-### DebugLevel
+### DebugLevel.h
 - Propagating debug levels for development. Supports level `TRACE, DEBUG, INFO, WARN and ERROR`. **Explains semantics of these levels**.
-### ATtinyUtils
+### ATtinyUtils.cpp
 - `changeDigisparkClock()` to use Digispark boards with standard ATtiny code like ATTinyCore by [Spence Konde](https://github.com/SpenceKonde/ATTinyCore). 
 It changes Digispark Bootloader clock settings to get the right CPU frequency and resets Digispark OCCAL tweak.
 - `toneWithTimer1PWM()`.
-- fuse reading function.
 - `isBODSFlagExistent()` -> checking for ATtiny85 revision C.
-### The very useful *digitalWriteFast.h* file from  [Watterott electronic](https://github.com/watterott/Arduino-Libs).
-
+- fuse reading function.
 
-### Trace. 
+### Trace.cpp.h
 **Tracing an Arduino program** by printing each program counter value after executing one instruction.
 
-## Utilities for serial output for ATtinies are contained in the [ATtinySerialOut](https://github.com/ArminJo/ATtinySerialOut) library available in Arduino.
+### [ATtinySerialOut.cpp](https://github.com/ArminJo/ATtinySerialOut/src)
+Minimal bit-bang send serial
+- 115200 baud for 1/8/16 MHz ATtiny clock.
+The utility for serial output for ATtinies is contained in the [ATtinySerialOut](https://github.com/ArminJo/ATtinySerialOut)
+library available as an Arduino library.
+
+### [EasyButtonAtInt01.cpp.h](https://github.com/ArminJo/EasyButtonAtInt01/src)
+- Arduino library for handling push buttons just connected between ground and INT0 and / or INT1 pin.
+- No external pullup, **no polling needed**.
+The utility for easy button handling for ATmegas or ATtinies is contained in the [EasyButtonAtInt01](https://github.com/ArminJo/EasyButtonAtInt01)
+library available as an Arduino library.
+
+### The very useful *digitalWriteFast.h* file from  [Watterott electronic](https://github.com/watterott/Arduino-Libs).
 
 # Modifying library properties
 To access the Arduino library files from a sketch, you have to first use *Sketch/Show Sketch Folder (Ctrl+K)* in the Arduino IDE.<br/>
@@ -52,8 +70,8 @@ The ArduinoUtils library examples are built on Travis CI for the following board
 
 - Arduino Uno
 - Arduino Leonardo
-- Arduino Mega 2560
-- Arduino cplayClassic
+- Digispark (using ATTiny85 @1MHz)
+- Generic ATTiny85 @1MHz
 
 ## Requests for modifications / extensions
 Please write me a PM including your motivation/problem if you need a modification or an extension.
diff --git a/keywords.txt b/keywords.txt
@@ -5,26 +5,48 @@
 #######################################
 # Datatypes (KEYWORD1)
 #######################################
-Talkie	KEYWORD1
+BlinkLed	KEYWORD1
 
 #######################################
 # Methods and Functions (KEYWORD2)
 #######################################
-say	KEYWORD2
-ptrAddr	KEYWORD3
-sayQ	KEYWORD2
-isTalking	KEYWORD2
-wait	KEYWORD2
-stop	KEYWORD2
-terminate	KEYWORD2
-doNotUseUseInvertedOutput	KEYWORD2
-doNotUseNonInvertedOutput	KEYWORD2
-getNumberOfWords	KEYWORD2
-sayQDigit	KEYWORD2
-sayQNumber	KEYWORD2
-sayQFloat	KEYWORD2
-sayQVoltageMilliVolts	KEYWORD2
-sayQPause	KEYWORD2
+
+# From HCSR04.cpp
+initUSDistancePins	KEYWORD2
+initUSDistancePin	KEYWORD3
+getUSDistance	KEYWORD2
+getCentimeterFromUSMicroSeconds	KEYWORD2
+getUSDistanceAsCentiMeter	KEYWORD2
+getUSDistanceAsCentiMeterWithCentimeterTimeout	KEYWORD2
+testUSSensor	KEYWORD2
+
+US_DISTANCE_DEFAULT_TIMEOUT_MICROS	LITERAL1
+US_DISTANCE_TIMEOUT_MICROS_FOR_1_METER	LITERAL1
+US_DISTANCE_TIMEOUT_MICROS_FOR_2_METER	LITERAL1
+US_DISTANCE_TIMEOUT_MICROS_FOR_3_METER	LITERAL1
+US_DISTANCE_DEFAULT_TIMEOUT_CENTIMETER	LITERAL1
+
+# From ADCUtils.cpp
+readADCChannel	KEYWORD2
+readADCChannelWithReference	KEYWORD2
+readADCChannelWithOversample	KEYWORD2
+readADCChannelWithReferenceOversample	KEYWORD2
+readADCChannelWithReferenceMultiSamples	KEYWORD2
+readADCChannelWithReferenceMax	KEYWORD2
+readADCChannelWithReferenceMaxMicros	KEYWORD2
+
+getVCCVoltageSimple	KEYWORD2
+getVCCVoltageMillivoltSimple	KEYWORD2
+getTemperatureSimple	KEYWORD2
+getVCCVoltage	KEYWORD2
+getVCCVoltageMillivolt	KEYWORD2
+printVCCVoltageMillivolt	KEYWORD2
+getTemperature	KEYWORD2
+
+ADC_PRESCALE	LITERAL1
+SHIFT_VALUE_FOR_REFERENCE	LITERAL1
+ADC_TEMPERATURE_CHANNEL_MUX	LITERAL1
+
 
 #######################################
 # Constants (LITERAL1)
diff --git a/src/HCSR04.cpp b/src/HCSR04.cpp
@@ -1,9 +1,16 @@
 /*
  *  HCSR04.cpp
  *
- *  US Sensor (HC-SR04) functions
+ *  US Sensor (HC-SR04) functions.
  *  The non blocking functions are using pin change interrupts and need the PinChangeInterrupt library to be installed.
  *
+ *  Supports also 1 Pin mode. You can modify the HCSR04 modules to 1 Pin mode by:
+ *  Old module with 3 16 pin chips: Connect Trigger and Echo direct or use a resistor < 4.7 kOhm.
+ *        If you remove both 10 kOhm pullup resistor you can use a connecting resistor < 47 kOhm, but I suggest to use 10 kOhm which is more reliable.
+ *  Old module with 3 16 pin chips but with no pullup resistors near the connector row: Connect Trigger and Echo with a resistor > 200 Ohm. Use 10 kOhm.
+ *  New module with 1 16 pin and 2 8 pin chips: Connect Trigger and Echo by a resistor > 200 Ohm and < 22 kOhm.
+ *  All modules: Connect Trigger and Echo by a resistor of 4.7 kOhm.
+ *
  *  Copyright (C) 2018-2020  Armin Joachimsmeyer
  *  Email: armin.joachimsmeyer@gmail.com
  *
@@ -27,45 +34,74 @@
 #include <Arduino.h>
 #include "HCSR04.h"
 
-#define DEBUG
+//#define DEBUG
 
-uint8_t sTriggerOutPin;
+uint8_t sTriggerOutPin; // also used as aTriggerOutEchoInPin for mode HCSR04_MODE_1_PIN
 uint8_t sEchoInPin;
-bool sHCSR04PinsAreInitialized = false;
 
+uint8_t sHCSR04Mode = HCSR04_MODE_UNITITIALIZED;
+
+/*
+ * @param aEchoInPin - If 0 then assume 1 pin mode
+ */
 void initUSDistancePins(uint8_t aTriggerOutPin, uint8_t aEchoInPin) {
     sTriggerOutPin = aTriggerOutPin;
-    sEchoInPin = aEchoInPin;
-    pinMode(aTriggerOutPin, OUTPUT);
-    pinMode(sEchoInPin, INPUT);
-    sHCSR04PinsAreInitialized = true;
+    if (aEchoInPin == 0) {
+        sHCSR04Mode = HCSR04_MODE_USE_1_PIN;
+    } else {
+        sEchoInPin = aEchoInPin;
+        pinMode(aTriggerOutPin, OUTPUT);
+        pinMode(sEchoInPin, INPUT);
+        sHCSR04Mode = HCSR04_MODE_USE_2_PINS;
+    }
+}
+
+void initUSDistancePin(uint8_t aTriggerOutEchoInPin) {
+    sTriggerOutPin = aTriggerOutEchoInPin;
+    sHCSR04Mode = HCSR04_MODE_USE_1_PIN;
 }
 
 /*
  * Start of standard blocking implementation using pulseInLong() since PulseIn gives wrong (too small) results :-(
  */
 unsigned int getUSDistance(unsigned int aTimeoutMicros) {
-    if (!sHCSR04PinsAreInitialized) {
+    if (sHCSR04Mode == HCSR04_MODE_UNITITIALIZED) {
         return 0;
     }
 
 // need minimum 10 usec Trigger Pulse
     digitalWrite(sTriggerOutPin, HIGH);
+
+    if (sHCSR04Mode == HCSR04_MODE_USE_1_PIN) {
+        // do it AFTER digitalWrite to avoid spurious triggering by just switching pin to output
+        pinMode(sTriggerOutPin, OUTPUT);
+    }
+
 #ifdef DEBUG
     delay(2); // to see it on scope
 #else
     delayMicroseconds(10);
 #endif
-// falling edge starts measurement
+// falling edge starts measurement after 400/600 microseconds (old/new modules)
     digitalWrite(sTriggerOutPin, LOW);
 
+    uint8_t tEchoInPin;
+    if (sHCSR04Mode == HCSR04_MODE_USE_1_PIN) {
+        delayMicroseconds(10); // allow for 10 us low before switching to input which is high because of the modules pullup resistor.
+        pinMode(sTriggerOutPin, INPUT);
+        tEchoInPin = sTriggerOutPin;
+    } else {
+        tEchoInPin = sEchoInPin;
+    }
+
     /*
      * Get echo length.
-     * Speed of sound at 20 degree is 343,46 m/s => 58,23 us per centimeter and 17,17 cm/ms (forth and back)
-     * Speed of sound at 10 degree is 337,54 m/s => 59,25 us per centimeter and 16,877 cm/ms (forth and back)
+     * Speed of sound is: 331.5 + (0.6 * TemperatureCelsius).
+     * Exact value at 20 degree is 343,46 m/s => 58,23 us per centimeter and 17,17 cm/ms (forth and back)
+     * Exact value at 10 degree is 337,54 m/s => 59,25 us per centimeter and 16,877 cm/ms (forth and back)
      * At 20 degree => 50cm gives 2914 us, 2m gives 11655 us
      */
-    unsigned long tUSPulseMicros = pulseInLong(sEchoInPin, HIGH, aTimeoutMicros);
+    unsigned long tUSPulseMicros = pulseInLong(tEchoInPin, HIGH, aTimeoutMicros);
     if (tUSPulseMicros == 0) {
 // timeout happened
         tUSPulseMicros = aTimeoutMicros;
diff --git a/src/HCSR04.h b/src/HCSR04.h
@@ -32,7 +32,8 @@
 #define US_DISTANCE_TIMEOUT_MICROS_FOR_3_METER 17475 // Timeout of 17475 is 3 meter
 #define US_DISTANCE_DEFAULT_TIMEOUT_CENTIMETER 343   // Timeout of 20000L is 3.43 meter
 
-void initUSDistancePins(uint8_t aTriggerOutPin, uint8_t aEchoInPin);
+void initUSDistancePins(uint8_t aTriggerOutPin, uint8_t aEchoInPin = 0);
+void initUSDistancePin(uint8_t aTriggerOutEchoInPin);
 unsigned int getUSDistance(unsigned int aTimeoutMicros = US_DISTANCE_DEFAULT_TIMEOUT_MICROS);
 unsigned int getCentimeterFromUSMicroSeconds(unsigned int aDistanceMicros);
 unsigned int getUSDistanceAsCentiMeter(unsigned int aTimeoutMicros = US_DISTANCE_DEFAULT_TIMEOUT_MICROS);
@@ -49,6 +50,11 @@ extern unsigned int sUSDistanceCentimeter;
 extern volatile unsigned long sUSPulseMicros;
 #endif
 
+#define HCSR04_MODE_UNITITIALIZED   0
+#define HCSR04_MODE_USE_1_PIN       1
+#define HCSR04_MODE_USE_2_PINS      2
+extern uint8_t sHCSR04Mode;
+
 #endif // HCSR04_H_
 
 #pragma once
