Skip to main content


Returns the current value of the imp’s free-running microsecond timer




Integer — the number of microseconds counted


This method provides access to a free-running microsecond ticker: a counter that starts off at 0 when the imp boots up and increments every microsecond. The value returned is a Squirrel integer: a signed 32-bit value. This means that the value will overflow (become negative) after 231μs, or about 36 minutes, and then count back up to zero in 232μs, about 72 minutes. However, this does mean that calculations of the form (a - b) > 0 correctly give the ordering of times a and b even if one or both is negative — provided a and b are less than 36 minutes apart.

The counter is set to zero on both a cold boot (power-on) and on a warm boot (wake from deep sleep).

For calendar (absolute) time, use one of the Squirrel built-in calendar-time functions: time(), which returns Unix time (integer, UTC seconds since 1 January 1970), or date(), which returns a table containing UTC year, date, month, hours, minutes and seconds values. Both time() and date() use the imp’s RTC timebase, which has a one-second resolution.

Example Code

The following code applies a state-change callback to an imp001 or imp002’s pin 1. When the value on the pin is high, the callback starts the microsecond clock. When the value of the pin changes again, the callback uses hardware.micros() again to calculate the duration of the pulse.