diff --git a/docs/reference/pins.md b/docs/reference/pins.md
index 74ddf3c6..d9a9e1f5 100644
--- a/docs/reference/pins.md
+++ b/docs/reference/pins.md
@@ -13,6 +13,7 @@ pins.onPulsed(DigitalPin.P0, PulseValue.High, () => {
     
 });
 pins.pulseDuration();
+pins.pulseIn(DigitalPin.P0, PulseValue.High);
 pins.servoWritePin(AnalogPin.P0, 180);
 pins.servoSetPulse(AnalogPin.P0, 1500);
 pins.i2cReadNumber(0, NumberFormat.Int8LE);
@@ -25,4 +26,4 @@ pins.analogSetPitchPin(AnalogPin.P0);
 
 ### See Also
 
-[digitalReadPin](/reference/pins/digital-read-pin), [digitalWritePin](/reference/pins/digital-write-pin), [analogReadPin](/reference/pins/analog-read-pin), [analogWritePin](/reference/pins/analog-write-pin), [analogSetPeriod](/reference/pins/analog-set-period), [map](/reference/pins/map), [onPulsed](/reference/pins/on-pulsed), [pulseDuration](/reference/pins/pulse-duration), [servoWritePin](/reference/pins/servo-write-pin), [servoSetPulse](/reference/pins/servo-set-pulse), [i2cReadNumber](/reference/pins/i2c-read-number), [i2cWriteNumber](/reference/pins/i2c-write-number), [setPull](/reference/pins/set-pull), [analogPitch](/reference/pins/analog-pitch), [analogSetPitchPin](/reference/pins/analog-set-pitch), [spiWrite](/reference/pins/spi-write)
+[digitalReadPin](/reference/pins/digital-read-pin), [digitalWritePin](/reference/pins/digital-write-pin), [analogReadPin](/reference/pins/analog-read-pin), [analogWritePin](/reference/pins/analog-write-pin), [analogSetPeriod](/reference/pins/analog-set-period), [map](/reference/pins/map), [onPulsed](/reference/pins/on-pulsed), [pulseDuration](/reference/pins/pulse-duration), [pulseIn](/reference/pins/pulse-in), [servoWritePin](/reference/pins/servo-write-pin), [servoSetPulse](/reference/pins/servo-set-pulse), [i2cReadNumber](/reference/pins/i2c-read-number), [i2cWriteNumber](/reference/pins/i2c-write-number), [setPull](/reference/pins/set-pull), [analogPitch](/reference/pins/analog-pitch), [analogSetPitchPin](/reference/pins/analog-set-pitch), [spiWrite](/reference/pins/spi-write)
diff --git a/docs/reference/pins/i2c-read-number.md b/docs/reference/pins/i2c-read-number.md
index b2d47f5e..bbd7df7b 100644
--- a/docs/reference/pins/i2c-read-number.md
+++ b/docs/reference/pins/i2c-read-number.md
@@ -27,6 +27,12 @@ format from the 7-bit I2C address `32`.
 pins.i2cReadNumber(32, NumberFormat.UInt16BE);
 ```
 
+#### ~hint
+
+This function is not supported in the simulator.
+
+#### ~
+
 ### See also
 
 [I2C](https://en.wikipedia.org/wiki/I%C2%B2C)
diff --git a/docs/reference/pins/i2c-write-number.md b/docs/reference/pins/i2c-write-number.md
index 703db722..b386b257 100644
--- a/docs/reference/pins/i2c-write-number.md
+++ b/docs/reference/pins/i2c-write-number.md
@@ -27,6 +27,13 @@ address `32` in big-endian 32-bit integer format.
 ```blocks
 pins.i2cWriteNumber(32, 2055, NumberFormat.Int32BE);
 ```
+
+#### ~hint
+
+This function is not supported in the simulator.
+
+#### ~
+
 ### See also
 
 [I2C](https://en.wikipedia.org/wiki/I%C2%B2C)
diff --git a/docs/reference/pins/pulse-in.md b/docs/reference/pins/pulse-in.md
new file mode 100644
index 00000000..8d7ae83e
--- /dev/null
+++ b/docs/reference/pins/pulse-in.md
@@ -0,0 +1,53 @@
+# Pulse In
+
+Returns the duration of a pulse (high or low) from a [pin](/device/pins) on
+the micro:bit board in microseconds.
+
+```sig
+pins.pulseIn(DigitalPin.P0, PulseValue.High)
+```
+
+### ~avatar
+
+Some pins are also used by the [LED screen](/device/screen).
+Please read the [page about pins](/device/pins) carefully.
+
+### ~
+
+### Parameters
+
+* ``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``
+
+### Returns
+
+* a [number](/reference/types/number) that represents the pulse duration in micro-seconds
+
+### Example: football score keeper
+
+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.
+
+```blocks
+basic.forever(() => {
+    // send pulse
+    pins.digitalWritePin(DigitalPin.P0, 0)
+    control.waitMicros(2)
+    pins.digitalWritePin(DigitalPin.P0, 1)
+    control.waitMicros(10)
+    pins.digitalWritePin(DigitalPin.P0, 0)
+
+    // read pulse
+    led.plotBarGraph(pins.pulseIn(DigitalPin.P1, PulseValue.High) / 58, 0)
+    basic.pause(100)
+})
+```
+
+#### ~hint
+
+This function is not supported in the simulator.
+
+#### ~
+
+### See also
+
+[digital write pin](/reference/pins/digital-write-pin),
diff --git a/libs/microbit/pins.cpp b/libs/microbit/pins.cpp
index efd9ee08..262bf2ef 100644
--- a/libs/microbit/pins.cpp
+++ b/libs/microbit/pins.cpp
@@ -160,11 +160,32 @@ namespace pins {
     */
     //% help=pins/pulse-duration
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
-    //% weight=21
+    //% weight=21 blockGap=8
     int pulseDuration() {
         return pxt::lastEvent.timestamp;
     }
 
+    /**
+    * 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)
+    */    
+    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name"
+    //% weight=20
+    int pulseIn(DigitalPin name, PulseValue value) {
+        MicroBitPin* pin = getPin((int)name);
+        if (!pin) return 0;
+
+        int pulse = value == PulseValue::High ? 1 : 0;
+        while(pin->getDigitalValue() != pulse);
+
+        uint64_t start =  system_timer_current_time_us();       
+        while(pin->getDigitalValue() == pulse);
+        uint64_t end =  system_timer_current_time_us();       
+        
+        return end - start;         
+    }
+
     /**
      * 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).
      * @param name pin to write to
diff --git a/libs/microbit/pins.ts b/libs/microbit/pins.ts
index 61fda293..53f4e54a 100644
--- a/libs/microbit/pins.ts
+++ b/libs/microbit/pins.ts
@@ -11,7 +11,7 @@ namespace pins {
      * @param toLow the lower bound of the value's target range
      * @param toHigh the upper bound of the value's target range, eg: 4
      */
-    //% help=pins/map weight=22
+    //% help=pins/map weight=23
     //% blockId=math_map block="map %value|from low %fromLow|from high %fromHigh|to low %toLow|to high %toHigh"
     export function map(value: number, fromLow: number, fromHigh: number, toLow: number, toHigh: number): number {
         return ((value - fromLow) * (toHigh - toLow)) / (fromHigh - fromLow) + toLow;
diff --git a/libs/microbit/shims.d.ts b/libs/microbit/shims.d.ts
index f5fc5727..df13cb6d 100644
--- a/libs/microbit/shims.d.ts
+++ b/libs/microbit/shims.d.ts
@@ -514,9 +514,18 @@ declare namespace pins {
      */
     //% help=pins/pulse-duration
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
-    //% weight=21 shim=pins::pulseDuration
+    //% weight=21 blockGap=8 shim=pins::pulseDuration
     function pulseDuration(): number;
 
+    /**
+     * 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)
+     */
+    //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name"
+    //% weight=20 shim=pins::pulseIn
+    function pulseIn(name: DigitalPin, value: PulseValue): 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).
      * @param name pin to write to
diff --git a/sim/libmbit.ts b/sim/libmbit.ts
index 333f63f1..eea09175 100644
--- a/sim/libmbit.ts
+++ b/sim/libmbit.ts
@@ -592,6 +592,13 @@ namespace pxsim.pins {
         // TODO
     }
 
+    export function pulseIn(name: number, value: number) : number {
+        let pin = getPin(name);
+        if (!pin) return 0;
+
+        return 5000;
+    }
+
     export function spiWrite(value: number): number {
         // TODO
         return 0;