MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Using heartbeat

Applications that perform periodic activities after periods in sleep mode use system heartbeat to synchronise their activities, that is, applications that need periodic wake-up calls. Usually the activities they perform involve network operations, for example, sending "alive" messages to the network, retrieving emails automatically or updating location data. The purpose of synchronisation is to reduce power consumption by giving all applications their wake-up calls simultaneously, instead of one application at a time. This way the device can, for example, switch off WLAN radios and reduce the CPU clock frequency for longer periods.

The MeeGo 1.2 Harmattan API library provides two possible classes to use the heartbeat feature:

If you are only targetting Harmattan, you can use either. If you are also targetting the Symbian platform, use QSystemAlignedTmer as QmSystem API is Harmattan-specific.

Regardless of whether you use the Qt Mobility API or the QmSystem API, specify a time window that defines the following:

  • Minimum interval between wake-ups
  • Maximum interval between wake-ups

Now you have a time window that tells the heartbeat to occur, for example, every 10-30 minutes. The time window can range between some seconds and several hours, depending on the application. It is recommended to use as long a time window as possible so that the heartbeat feature can reach its full effectiveness in power saving.

Qt 4.7 API contains also a QtTimer class which provides a timer feature for applications. The difference between the timer and the heartbeat is that the heartbeat uses a time window (defined in seconds) for scheduling the wake-ups of different applications, whereas the timer triggers the action at exact intervals (defined in milliseconds), regardless of other applications. Use the timer for wake-ups at fixed or very short intervals, for example, animations triggered in every 50 milliseconds, and the heartbeat when it is not crucial to do the wake-up in very short or in strictly fixed intervals, for example, checking emails in the server approximately once in 10 to 20 minutes.

Example application

This is a simple example QML application which shows how the heartbeat feature can be used. The application shows the time of two latest heartbeats on the device screen.

import QtQuick 1.1
import com.nokia.meego 1.0
import QtMobility.systeminfo 1.2

Page {

    AlignedTimer {
        id: heartbeat
        maximumInterval: 15
        minimumInterval: 5
        onTimeout: {
            var timestamp = Qt.formatDateTime(new Date(), "hh:mm:ss") + qsTr(" - heartbeat!")
            console.log(timestamp)
            prevLabel.text = lastLabel.text
            lastLabel.text = timestamp
        }
    }

    Label {
        id: prevLabel
        anchors.horizontalCenter: parent.horizontalCenter
        y: 100
        text: qsTr("no heartbeat")
    }
    Label {
        id: lastLabel
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.top: prevLabel.bottom
        text: qsTr("no heartbeat")
    }

    Button {
        anchors.horizontalCenter: parent.horizontalCenter
        y: 300
        text: qsTr("Heartbeat on/off")
        checkable: true
        checked: false
        onClicked: {
            if (checked) {
                var timestamp = Qt.formatDateTime(new Date(), "hh:mm:ss") + qsTr(" - start")
                console.log(timestamp)
                lastLabel.text = timestamp
                heartbeat.start()
            }
            else {
                heartbeat.stop()
            }
        }
    }
}