support for max-duration in pulse-in

docs/reference/pins/pulse-in.md

@@ -18,12 +18,13 @@ Please read the [page about pins](/device/pins) carefully.
 
 * ``name`` is a [string](/reference/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
 * ``value`` is the value of the pulse, ``high`` or ``low``
+* ``maxDuration``, maximum duration in micro-seconds. If no pulse is received 
 
 ### Returns
 
 * a [number](/reference/types/number) that represents the pulse duration in micro-seconds
 
-### Example: football score keeper
+### Example: Measuring distance with a sonar
 
 The following script sends a pulse on ``P0`` and reads the pulse returned by a HC-SR04 sonar to determine the distance of the object in front of the sensor.
 

libs/microbit/pins.cpp

@@ -169,20 +169,28 @@ namespace pins {
     * Returns the duration of a pulse in microseconds
     * @param name the pin which measures the pulse
     * @param value the value of the pulse (default high)
+    * @param maximum duration in micro-seconds
     */    
-    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name"
+    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
     //% weight=20
-    int pulseIn(DigitalPin name, PulseValue value) {
+    int pulseIn(DigitalPin name, PulseValue value, int maxDuration = 2000000) {
         MicroBitPin* pin = getPin((int)name);
         if (!pin) return 0;
 
         int pulse = value == PulseValue::High ? 1 : 0;
-        while(pin->getDigitalValue() != pulse);
+        uint64_t tick =  system_timer_current_time_us(); 
+        uint64_t maxd = (uint64_t)maxDuration;      
+        while(pin->getDigitalValue() != pulse) {
+            if(system_timer_current_time_us() - tick > maxd)
+                return 0;            
+        }
 
         uint64_t start =  system_timer_current_time_us();       
-        while(pin->getDigitalValue() == pulse);
+        while(pin->getDigitalValue() == pulse) {
+            if(system_timer_current_time_us() - tick > maxd)
+                return 0;            
+        }        
         uint64_t end =  system_timer_current_time_us();       
-        
         return end - start;         
     }
 

libs/microbit/shims.d.ts

@@ -521,10 +521,11 @@ declare namespace pins {
      * Returns the duration of a pulse in microseconds
      * @param name the pin which measures the pulse
      * @param value the value of the pulse (default high)
+     * @param maximum duration in micro-seconds
      */
-    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name"
+    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
-    //% weight=20 shim=pins::pulseIn
+    //% weight=20 maxDuration.defl=2000000 shim=pins::pulseIn
-    function pulseIn(name: DigitalPin, value: PulseValue): number;
+    function pulseIn(name: DigitalPin, value: PulseValue, maxDuration?: number): number;
 
     /**
      * Writes a value to the servo, controlling the shaft accordingly. On a standard servo, this will set the angle of the shaft (in degrees), moving the shaft to that orientation. On a continuous rotation servo, this will set the speed of the servo (with ``0`` being full-speed in one direction, ``180`` being full speed in the other, and a value near ``90`` being no movement).

sim/libmbit.ts

@@ -592,7 +592,7 @@ namespace pxsim.pins {
         // TODO
     }
 
-    export function pulseIn(name: number, value: number) : number {
+    export function pulseIn(name: number, value: number, maxDuration: number): number {
         let pin = getPin(name);
         if (!pin) return 0;