.. highlight:: cpp

Timer
=====
A MetaWear timer can be thought of as an event that is fired at fixed intervals.  These timers are represented by the 
`MblMwTimer <https://mbientlab.com/docs/metawear/cpp/latest/timer__fwd_8h.html#ac32a834c8b7bc7230ce6947425f43926>`_ struct and can be safely typcased to a 
`MblMwEvent <https://mbientlab.com/docs/metawear/cpp/latest/event__fwd_8h.html#a569b89edd88766619bb41a2471743695>`_ struct.  Timers can be used to schedule periodic tasks 
or setup a delayed task execution.

Task Scheduling
---------------
Before you can schedule tasks, you first need to create a timer, by calling either 
`mbl_mw_timer_create <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#a749457dc6c8a181990367d8b1f92284c>`_ or 
`mbl_mw_timer_create_indefinite <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#ae6a58f97ba8e443aec84769a9cc84453>`_.  These functions are asynchronous and 
will pass a pointer to the caller when the timer is created.  When you have a valid 
`MblMwTimer <https://mbientlab.com/docs/metawear/cpp/latest/timer__fwd_8h.html#ac32a834c8b7bc7230ce6947425f43926>`_, you can use the command recording system outlined in 
:doc:`mblmwevent` section to program the board to respond to the periodic events.  Upon recording timer task commands, call 
`mbl_mw_timer_start <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#a90455d9e29548c1332ef7ad9db46c50e>`_ to start the timer.

When you are done using a timer, you can remove it with 
`mbl_mw_timer_remove <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#a96d102b4f39a46ccbaf8ee5a37a2a55e>`_. ::

    #include "metawear/core/event.h"
    #include "metawear/core/timer.h"
    
    #include "metawear/sensor/gpio.h"
    
    void timer_setup(MblMwMetaWearBoard* board) {
        static auto cmds_recorded = [](void) -> void {
            printf("timer task setup\n");
        };
        static auto timer_created = [](MblMwTimer* timer) -> void {
            auto owner = mbl_mw_event_get_owner((MblMwEvent*) timer);
    
            // read gpio adc data every time the timer fires an event
            mbl_mw_event_record_commands((MblMwEvent*) timer);
            mbl_mw_gpio_read_analog_input(owner, 0, MBL_MW_GPIO_ANALOG_READ_MODE_ADC);
            mbl_mw_event_end_record((MblMwEvent*) timer, cmds_recorded);
    
            mbl_mw_timer_start(timer);
        };
    
        // create a timer that indefinitely fires events every 500ms
        mbl_mw_timer_create_indefinite(board, 500, 0, timer_created);
    }