Technical documentation for developers who want to show CGM data in their own watchfaces.
The app provides 3 complications that you can read with Garmin's complication system.
The current value in human-readable form. You can display it directly.
For progress bars, trend icons and range coloring.
• ranges: Array of Floats (use toNumber() to convert)
| Index | Description |
|---|---|
| 0 | Unit (0 = mg/dL, 1 = mmol/L) |
| 1 | Trend Arrow (0-9, see below) |
| 2 | Low Target (for yellow coloring) |
| 3 | High Target (for yellow coloring) |
| 4 | Very Low (for red coloring) |
| 5 | Very High (for red coloring) |
| 6 | Timestamp of the sample from your CGM |
| 7 | Timestamp when sample should be considered old (add "-" to the value) |
| 8 | Timestamp when sample is too old and should not be shown |
Important for developers: You must use the "old" and "too old" timestamps (indices 7 and 8). On most watch models, complications don't update when the watch loses connection. Your watchface has to check these timestamps and handle stale data, so it doesn't show outdated glucose values.
For drawing a graph of up to 24 hours of glucose readings.
• ranges: Array of 288 Floats
• Contains last 24 hours of readings (288 total if available)
• Each reading is 5 minutes apart
• First value = most recent reading
• A value of 0 means no data at that time
The trend arrow value (index 1 in the Complication 2 ranges array) shows the direction and rate of glucose change.
| Value | Direction | Arrow |
|---|---|---|
| 0 | None/Unknown | - |
| 1 | Double Up | ⇈ |
| 2 | Single Up | ↑ |
| 3 | Forty Five Up | ↗ |
| 4 | Flat | → |
| 5 | Forty Five Down | ↘ |
| 6 | Single Down | ↓ |
| 7 | Double Down | ⇊ |
| 8 | Not Computable | - |
| 9 | Out of Range | - |
To show CGM data in your watchface:
import Toybox.System;
import Toybox.Lang;
import Toybox.Complications;
module gbDexcomConsumer {
var complicationId as Complications.Id?;
// Find the complication by longLabel.
function getComplicationId() as Complications.Id or Null {
var i = Complications.getComplications();
var c = i.next();
while (c != null) {
if ("CGM-GB-value".equals(c.longLabel)) {
return c.complicationId;
}
c = i.next();
}
// Not installed?
return null;
}
function getData() as String {
if (!(complicationId instanceof Complications.Id)) {
complicationId = getComplicationId();
if (!(complicationId instanceof Complications.Id)) {
return "--";
}
}
// Get the complication and return the value as string.
var complication = Complications.getComplication(complicationId) as Complications.Complication?;
return complication == null || complication.value == null ? "--" : complication.value + "";
}
}
// In your onUpdate method:
function onUpdate(dc as Dc) {
System.println(gbDexcomConsumer.getData());
}
This example handles stale data with the timestamps from Complication 2. You need this, because complications don't update when the watch loses connection.
import Toybox.System;
import Toybox.Lang;
import Toybox.Time;
import Toybox.Complications;
module gbDexcomConsumer {
var complicationId as Complications.Id?;
// Find the complication by longLabel for extended data
function getComplicationId() as Complications.Id or Null {
var i = Complications.getComplications();
var c = i.next();
while (c != null) {
if ("CGM-GB-data".equals(c.longLabel)) {
return c.complicationId;
}
c = i.next();
}
return null;
}
// Get glucose value with proper stale data handling
function getValue() as Number {
if (!(complicationId instanceof Complications.Id)) {
complicationId = getComplicationId();
if (!(complicationId instanceof Complications.Id)) {
return -1; // Not installed
}
}
var complication = Complications.getComplication(complicationId);
if (complication == null || complication.value == null) {
return -1; // No data
}
var val = complication.value.toNumber();
// Check if ranges array has stale data timestamps
if (complication.ranges instanceof Array && complication.ranges.size() >= 9) {
var oldTimestamp = complication.ranges[7];
var tooOldTimestamp = complication.ranges[8];
if (oldTimestamp instanceof Float && tooOldTimestamp instanceof Float) {
var nowTimestamp = Time.now().value();
// Data is too old - show -1
if (nowTimestamp > tooOldTimestamp) {
val = -1;
}
// Data is stale - negate value (adds minus prefix)
else if (nowTimestamp > oldTimestamp && val > 0) {
val = -val;
}
}
}
return val;
}
// Get trend arrow value
function getTrendArrow() as Number {
if (!(complicationId instanceof Complications.Id)) {
return 0;
}
var complication = Complications.getComplication(complicationId);
if (complication != null && complication.ranges instanceof Array && complication.ranges.size() >= 2) {
return complication.ranges[1].toNumber();
}
return 0;
}
// Get target ranges for color coding
function getTargetRanges() as [Number, Number, Number, Number]? {
if (!(complicationId instanceof Complications.Id)) {
return null;
}
var complication = Complications.getComplication(complicationId);
if (complication != null && complication.ranges instanceof Array && complication.ranges.size() >= 6) {
return [
complication.ranges[2].toNumber(), // Low Target
complication.ranges[3].toNumber(), // High Target
complication.ranges[4].toNumber(), // Very Low
complication.ranges[5].toNumber() // Very High
];
}
return null;
}
}
// In your onUpdate method:
function onUpdate(dc as Dc) {
var glucoseValue = gbDexcomConsumer.getValue();
var trendArrow = gbDexcomConsumer.getTrendArrow();
var ranges = gbDexcomConsumer.getTargetRanges();
System.println("Glucose: " + glucoseValue);
System.println("Trend: " + trendArrow);
System.println("Ranges: " + ranges);
}
Key Implementation Notes: