unsigned long pulseIn(uint8_t pin, uint8_t state, unsigned long timeout)
pulseIn() is used to measure the duration of a digital pulse on an I/O pin. pulseIn() will wait up timeout microseconds for a pulse to start, then again timeout microseconds for the pulse to complete. The duration of the pulse, in microseconds, is returned. A pulse is characterised as either a rising edge followed by a falling edge, or a falling edge followed by a rising egde. The state parameter is used to select which combination is identified as a pulse. A HIGH as the state waits first for a rising edge then measures the time to the next falling edge. A LOW waits for a falling edge then measures the time to the next rising edge.
If a pulse is detected the duration of the pulse in microseconds is returned. If no pulse is detected and the timeout limit is reached the function returns 0.
pulseIn() conforms to the Arduino 1.6.x API.
// Wait up to 10ms for a pulse to start and get its duration unsigned long us = pulseIn(7, HIGH, 10000);