Figure 2 Attachment of cycle monitor

For those of you who are mechanically minded small magnets on both the crank and the rear wheel spokes activate the sensor strapped to the frame. The sensor maintains the counts and timings and will report them to a suitable Bluetooth LE device such as a BlackBerry 10 smartphone.

The application that we developed based on this is actually very similar in structure to the Heart Rate Monitor application that was described in a previous blog and article. The basic logic is the same:

1. Pair the Bluetooth LE device with the BlackBerry 10 handset before using the application.
2. Launch the application which:
   1. Discovers devices that support the CSC Service (UUID 0×1816)
   2. Connects to a discovered device selected by the user
   3. Requests the device to notify our application as changes are made to the CSC Measurement characteristic (UUID 0x2A5B) which contains the wheel and crank data that we’re interested in.
   4. Receive, parse and display in numerical (RPM) and historical graphical form the CSC Measurement data as they are received.

Here are some screenshots showing what the application looks like:

Figure 3 The CscMonitor Application

Instantaneous values of the wheel and crank readings in revolutions per minute (RPM) are shown in the upper part of the screen whilst historical RPM data are plotted on the lower half of the display. Wheel and crank historical data displays can be toggled by touching the screen. Mapping RPM values to distance or energy expended would require additional information to be provided, such as the wheel circumference or radius of the crank — we’ll leave this for a possible later iteration of the application and focus on the Bluetooth LE aspects for now.

If we inspect the GATT services the CSC device supports using a tool like BTool we can see (Figure 4) that the CSC Measurement Characteristic (UUID 0x2A5B) is exposed at handle 0×0023. Handles are the references to entries in the GATT that our application will discover and use to access the value associated with a characteristic. We’ve used handles before in both our previous examples.

Figure 4 GATT showing CSC Characteristics

Associated with the CSC Measurement Characteristic is a “Client Characteristic Configuration” characteristic (UUID 0×2902) exposed at handle 0×0024. The value of this field determines whether our application will receive Notifications or Indications for the CSC Measurement Characteristic. We’ve used these before as well in our previous examples. In this case this characteristic will be set to enable Notifications using the BlackBerry 10 Bluetooth LE API.

So, how do we manage the data that is notified to us from the CSC device? The CSC data received is managed by a class called “CscDataContainer” … here’s part of its definition:

class CscDataContainer: public QObject {
       Q_OBJECT
private:
       CscDataContainer();
...
       // notification data
       QQueue<csc_notification_t> _csc_notifications;
       // CSC values
       QQueue<csc_values_t> _csc_values;
       int _min_wheel_rpm;
       int _max_wheel_rpm;
       int _avg_wheel_rpm;
       long _total_wheel_rpm;
...
}

At its core are a couple of queues that maintain the data that is received. The queue has a maximum length that can accommodate one notification per second for an 8 hour period. A future version might persist these data in a database but this is sufficient to demonstrate the principle in this case.

Once again the excellent little JavaScript library called “Flot” is used to plot these data in a WebView component in QML.

As notifications are received by our application the addNotification() method of the CscDataContainer class is called with the CSC Measurement data passed as a (uint8_t *) and a length (uint16_t) — that is an array of bytes.

Parsing this data is the first task and it’s instructive to see how this works – the main points are highlighted in the code fragment below:

void CscDataContainer::addNotification(const uint8_t *val, uint16_t len) {
       // parse value, paying attention to the bit settings in the FLAGS field
       bool wheel_revolution_data_present = false; // bit 0 of Flags field
       bool crank_revolution_data_present = false; // bit 1 of Flags field
       uint32_t cumulative_wheel_revolutions = 0;
       uint16_t cumulative_crank_revolutions = 0;
       uint16_t last_wheel_event_time = 0;
       uint16_t last_crank_event_time = 0;
       int index = 0;
       uint8_t flags = val[index];
       wheel_revolution_data_present = ((
flags & WHEEL_REVOLUTION_DATA_PRESENT) == WHEEL_REVOLUTION_DATA_PRESENT);
       crank_revolution_data_present = ((
flags & CRANK_REVOLUTION_DATA_PRESENT) == CRANK_REVOLUTION_DATA_PRESENT);
       // Fields are in the order of LSO to MSO.
       // Where LSO = Least Significant Octet and MSO = Most Significant Octet.
       index++;
       if (wheel_revolution_data_present) {
              // Cumulative Wheel Revolutions, 4 bytes.
             // Field exists if the key of bit 0 of the Flags field is set to 1.
              cumulative_wheel_revolutions =
(val[index + 3] << 24) | (val[index + 2] << 16) |
(val[index + 1] << 8)  |  val[index];
index += 4;
              // Last Wheel Event Time, 2 bytes. 
              // Field exists if the key of bit 0 of the Flags field is set to 1.
              last_wheel_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
...
}
       if (crank_revolution_data_present) {
// Cumulative Crank Revolutions, 2 bytes. 
// Field exists if the key of bit 1 of the Flags field is set to 1.
              cumulative_crank_revolutions =
(val[index + 1] << 8) | val[index];
              index += 2;
              // Last Crank Event Time, 2 bytes. 
              // Field exists if the key of bit 1 of the Flags field is set to 1.
              last_crank_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
    ...
    }
...
}

The first byte of data contains an 8-bit flag field (see Figure 1 for details). This indicates whether crank or wheel data is present in the following data.  If these are present they are represented in Little-endian form and need to be extracted by shifting them out a byte at a time.

The rest of the application is more focussed on the display of this data using QML so I’ll leave that for you to look at yourself since the main learning points are to do with how to interface to the Bluetooth Low Energy device itself.

We made a video which has Martin (@mdwrim) showing the application in action and explaining the code. Here it is:

If you want to know more then check out the following resources:

• The complete source code for this application on Git Hub;
  • https://github.com/blackberry/Cascades-Community-Samples
• If you’re completely new to Bluetooth LE then we recommend you read our “BlackBerry 10 Bluetooth LE Primer for Developers”  which you’ll find in our knowledge base. This and all other Bluetooth LE related developer resources that we’ve created, are listed in a single resource index page:
  • http://supportforums.blackberry.com/t5/Native-Development/BlackBerry-10-Bluetooth-LE-resource-index/ta-p/2326147

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.