.. currentmodule:: machine .. _machine.Timer: class Timer -- control hardware timers ====================================== Hardware timers deal with timing of periods and events. Timers are perhaps the most flexible and heterogeneous kind of hardware in MCUs and SoCs, differently greatly from a model to a model. MicroPython's Timer class defines a baseline operation of executing a callback with a given period (or once after some delay), and allow specific boards to define more non-standard behaviour (which thus won't be portable to other boards). See discussion of :ref:`important constraints ` on Timer callbacks. .. note:: Memory can't be allocated inside irq handlers (an interrupt) and so exceptions raised within a handler don't give much information. See :func:`micropython.alloc_emergency_exception_buf` for how to get around this limitation. If you are using a WiPy board please refer to :ref:`machine.TimerWiPy ` instead of this class. Constructors ------------ .. class:: Timer(id, /, ...) Construct a new timer object of the given ``id``. ``id`` of -1 constructs a virtual timer (if supported by a board). ``id`` shall not be passed as a keyword argument. See ``init`` for parameters of initialisation. Methods ------- .. method:: Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None) Initialise the timer. Example:: def mycallback(t): pass # periodic with 100ms period tim.init(period=100, callback=mycallback) # one shot firing after 1000ms tim.init(mode=Timer.ONE_SHOT, period=1000, callback=mycallback) Keyword arguments: - ``mode`` can be one of: - ``Timer.ONE_SHOT`` - The timer runs once until the configured period of the channel expires. - ``Timer.PERIODIC`` - The timer runs periodically at the configured frequency of the channel. - ``period`` - The timer period, in milliseconds. - ``callback`` - The callable to call upon expiration of the timer period. The callback must take one argument, which is passed the Timer object. The ``callback`` argument shall be specified. Otherwise an exception will occurr upon timer expiration: ``TypeError: 'NoneType' object isn't callable`` .. method:: Timer.deinit() Deinitialises the timer. Stops the timer, and disables the timer peripheral. Constants --------- .. data:: Timer.ONE_SHOT Timer.PERIODIC Timer operating mode.