.. 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.

ID
--
MblMwTiimer objects are identified by a numerical id; you can retrieve the id by calling 
`mbl_mw_timer_get_id <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#a695e95e035825b626b78416b5df5611e>`_.  The id is used to retrieve 
existing timers from the API with the 
`mbl_mw_timer_lookup_id <https://mbientlab.com/docs/metawear/cpp/latest/timer_8h.html#a84d84562f66090e61061b67321c22961>`_ function.

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);
    
            auto adc_signal= mbl_mw_gpio_get_analog_input_data_signal(board, 0, 
                    MBL_MW_GPIO_ANALOG_READ_MODE_ADC);
            // read gpio adc data every time the timer fires an event
            mbl_mw_event_record_commands((MblMwEvent*) timer);
            mbl_mw_datasignal_read(adc_signal);
            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);
    }

