How to use Software Timers

In this KB we will demonstrate an example of using a Software Timer to perform a temperature and humidity sensor reading once every second.

It is documented in KB Z-Wave 700: How to implement I2C into the Z-Wave Embedded Framework how to readout the temperature and humidity sensor reading using I2C.

This KB will be using the AppTimer module from the Z-Wave Framework. This module is further documented in document INS14259 - Z-Wave Plus V2 Application Framework SDK7 (available in Simplicity Studio).

All software timers are essentially FreeRTOS timers. Using the AppTimer module, you ensure that timer callback functions are executed in the context of the application task.

Step 1: Continuing on an example

This KB continues on the I2C example. It is suggested to complete that exercise in order to see the full effect of implementing the timer – it is however not required and this guide will instruct how to continue if not using I2C in the relevant steps.

Step 2: SSwTimer instance

To start using application timers, you need a SSwTimer instance. In the PRIVATE DATA section, add a SSwTimer instance.

// ACTION: SSwTimer instance

static SSwTimer CheckTemperatureTimer;

Step 3: Initialize timer

In ApplicationTask() register a timer and add a callback. In this example we start the timer and configure it to 1000 ms.

AppTimerSetReceiverTask(g_AppTaskHandle);

// ACTION: Register timer
AppTimerRegister(&CheckTemperatureTimer, true, TemperatureTimerCallback);

// ACTION: Start timer
TimerStart(&CheckTemperatureTimer, 1000);

Step 4: Add a new event

When the timer fires, we want our callback function to enqueue an event to our state machine. Thus we need to add a new event in the _EVENT_APP_ typdedef. We call this event EVENT_APP_TEMPERATURE.

typedef enum _EVENT_APP_
{
  EVENT_EMPTY = DEFINE_EVENT_APP_NBR,
  EVENT_APP_INIT,
  EVENT_APP_REFRESH_MMI,
  EVENT_APP_FLUSHMEM_READY,
  EVENT_APP_TEMPERATURE,				// ACTION: Add new event
} EVENT_APP;

Step 5: Create the callback function

In the PRIVATE FUNCTIONS section create the callback function TemperatureTimerCallback() and enqueue the event EVENT_APP_TEMPERATURE when called.

// ACTION: Add event on timer callback
void TemperatureTimerCallback(SSwTimer *pTimer)
{
  UNUSED(pTimer);

  DPRINTF("\r\nTemperatureTimerCallback!");

  ZAF_EventHelperEventEnqueue(EVENT_APP_TEMPERATURE);
}

Step 6: Update the state machine to listen for the event

In the AppStateManager(), find the state called STATE_APP_IDLE. In this state, create a new if-case and perform the temperature measurement if EVENT_APP_TEMPERATURE event is received.

// ACTION: Perform temperature measurement on timer event
if (EVENT_APP_TEMPERATURE)
{
   uint32_t rhData;
   int32_t tempData;

   // Get temperature and humidity reading from on-board sensor
   performMeasurements(i2cInit.port, &rhData, &tempData);
   DPRINTF("\r\nHumidity: %d", rhData);
   DPRINTF("\r\nTemperature: %i\r\n", tempData);
}

Note: In this step, we are calling performMeasurements(). This function is part of the I2C example. You can leave out this function call, and just verify in the debug log that the event is called once every second.

Step 7: Build solution and test

Build the solution and flash the new firmware image to the device.

If you enable serial debug output, you should now see that we get the TemperatureTimerCallback() and that results in a temperature and humidity reading.

Z-Wave 700 End-device framework KBs

Z-Wave 700: How to implement I2C into the Z-Wave Embedded Framework

Z-Wave 700: How to use Software Timers (this guide)

Z-Wave 700: How to implement SPI into the Z-Wave Embedded Framework

Z-Wave 700: How to implement UART with interrupt into the Z-Wave Embedded Framework 

Linked documentation (found in Simplicity Studio)

• INS14280 - Getting Started for End Device
  This document also describes how to setup the Z-Wave region and serial debug, which is not covered by this KB.
   
• INS14259 - Z-Wave Plus V2 Application Framework SDK7
  Refer to section 7.7 for more information on the Timer module.
   
• UG381: ZGM130S Zen Gecko Wireless Starter Kit User's Guide