43 — Getting readings to Sukrara Aura on a Garmin
2026-11-16 · investigation report · Descent Mk3i 43 mm (Connect IQ 5.1), Connect IQ SDK 9.3.0, companion SDK 2.4.0 (inspected, not used)
Sukrara Aura (contracts/watchface/aura) must show what the phone’s Sukrara shows, a new reading within seconds when the watch is in reach (SPEC §13), right between messages (ages, countdowns, “No phone”), with nothing to switch on first. Today’s Garmin path (08) is a 5-minute poll of the xDrip+ server through Garmin Connect.
The person first
Section titled “The person first”When the link fails in real life, and what they see:
| Situation | What happens to the data | What the person sees | How it fixes itself / they fix it |
|---|---|---|---|
| Phone in another room, out of Bluetooth range | Nothing arrives | The value ages from its own time: late (reading time shown) → struck and grey → No reading since 10:09; Garmin’s No phone takes the first bottom field | Back in range: the phone sends the current reading on reconnect (checked every minute) |
| Garmin Connect stopped by battery saving (Samsung, Xiaomi; xDrip+ users report the same #3060, swissalpine FAQ) | Neither path works | Same aging; phone: Share with apps › Sukrara Aura “Garmin Connect isn’t answering · open it” | Open Garmin Connect; the footer says it must run in the background |
| Garmin Connect’s messaging bug (CIQQA-4631, acknowledged, open since mid-2026: messages silently vanish on some Garmin Connect / Android versions) | Push lost; the face’s 5-minute fetch still works | The face lags up to 5 min (late → shows the reading time); phone: “Garmin Connect loses messages · the face asked 3 min ago, so it updates every 5 minutes” | Nothing needed; restarting the watch / Garmin Connect may bring push back |
| Bluetooth off on the phone | Nothing arrives | Aging + No phone; phone: “ |
Bluetooth on: current within a minute |
| Phone or watch restart | Watch: the stored payload survives (it ages right away); phone: Sukrara’s service restarts | No blank face, an aging value | Next reading pushes (≤ 1 min), or the 5-minute fetch |
| Travel, time zones | Times are absolute epoch seconds: ages never jump; today’s time in range ends with the phone’s day | Correct ages; TIR disappears at the phone’s midnight until the next message | — |
| Swim, dive, shower | Bluetooth doesn’t cross water (docs/42 §1.4) | Aging, as expected; struck before it could mislead | Surfacing: current on reconnect |
| Another face selected | Only the active face’s background runs; Garmin queues messages for it (Pwb0186 notes) | — | The face takes the newest by sent and drops older ones (contract “Order”) |
| Watch clock behind the phone | A too-young age would be unsafe | — | The face adds the phone’s lead (sent − now on receipt) to its clock: never younger, only older |
What others do, and what people say:
- AAPS binds Garmin Connect’s Connect IQ service itself (still with Garmin’s AAR for the stubs), keeps one message in flight, retries up to 10 times and drops messages older than 30 s; its data path is HTTP on 127.0.0.1:28891, a pushed message mostly only wakes the watch’s long poll (GarminDeviceClient.kt, GarminPlugin.kt); its author calls native messaging “usually unreliable but good enough” (PR #3059).
- Juggluco → Kerfstok (a watch app, not a face) uses the SDK plus an experimental direct BLE transport it falls back to after 12 s without a reply: “the SDK’s sendMessage SUCCESS callback by itself is not an acknowledgement” (AllData.java, DirectGarminIQ.java).
- xDrip+, GlucoDataHandler: web server only (Local_Web_Services.md, GDH). CGM+: “up to 10 minutes behind” (FAQ). CGM Gauge: Garmin Connect “blocks HTTP after a certain time… synchronize your watch” (store text).
- Dexcom’s official Garmin app shows “NO DATA” whenever its phone path breaks (forum). Good: it never shows an old value; bad: no reason, no way to fix it from the phone. Sukrara keeps the aging value (struck once stale) and says on the phone why.
- A push-driven face works: buessow’s GlucoseWatchFace
registers
registerForPhoneAppMessageEvent; the Pwb0186 face reports “a few seconds” against up to 5 min, also sideloaded, with gotchas: delete before registering, messages pile up for an inactive face, noCommunicationsin a face’s foreground.
Transports compared
Section titled “Transports compared”| Latency | Battery | Reliability | Setup | Notes | |
|---|---|---|---|---|---|
Pull: the face’s background polls 127.0.0.1 via makeWebRequest |
≤ 5 min (temporal floor, Background) | One background run / 5 min | Good; Garmin Connect’s “HTTP blocked after a while” bug | None (http only to loopback on Android, forum) | Fails the “seconds” requirement alone |
Push: a Connect IQ message wakes the face’s background (registerForPhoneAppMessageEvent, 3.2.0) |
Seconds | One background run per message (1/min) | Garmin Connect’s open messaging bug; statuses not always sent | None; works for sideloaded faces (lookup by app id) | Background exit data ≤ ~8 KB; the payload is ~0.5 KB |
| Direct BLE | Seconds | Radio on both sides | Unproven: the API docs don’t list BluetoothLowEnergy for faces (API); the phone would be a GATT peripheral beside Garmin Connect’s own link |
Pairing | Juggluco’s reverse-engineered path is a different (legacy app) protocol |
| Hybrid: push + 5-minute fetch | Seconds; ≤ 5 min when push breaks | Both, small | Two independent paths through Garmin Connect | None | Chosen |
Companion SDK: com.garmin.connectiq:ciq-companion-app-sdk:2.4.0 (2026-03) is under Garmin’s proprietary SDK licence
(POM):
not linkable into a GPL app without an exception, and not allowed on F-Droid (Inclusion Policy).
What it does is small: bind com.garmin.android.apps.connectmobile/.connectiq.ConnectIQService, call its interface by
transaction number with plain parcels, serialize the message in Monkey C’s format, read the answers Garmin Connect
broadcasts back; in “tethered” mode the phone listens on 7381 and the simulator joins through adb forward.
Choice
Section titled “Choice”Hybrid: push on every change, plus the face’s own 5-minute fetch, both carrying the whole payload. Push gives seconds; the fetch covers Garmin Connect’s messaging bug, lost messages, a face just selected, and proves on the phone that the face runs (The face asking this phone). Both go through Garmin Connect (the only bridge), so a stopped Garmin Connect stops both: the phone says so. Sukrara speaks to Garmin Connect itself, no Garmin library.
Retry: a message Garmin Connect fails or never confirms (20 s) is sent again after 15 s, 30 s, 60 s, then every 2 min, until a newer payload replaces it; a watch that reconnects gets the current payload at once. One message at a time.
The payload is a versioned contract: contracts/watchface/payload.
- The Monkey C writer was checked against Garmin’s own serializer (the 2.4.0 AAR, in a throwaway test, never
committed): every value decodes the same;
cases.jsonkeeps a payload as Garmin’s bytes for every reader to decode. - Phone → payload:
AuraPayloadFixtureTest(16 cases). Link behaviour:AuraLinkTest,AuraStatusTest. - The face:
LinkTestruns every case on the watch side in the simulator (apps/garmin/tools/link-test.sh, 3 tests pass). - End to end, 2026-11-16: the debug build on an emulator (
GARMIN_SIM, synthetic readings) →adb forward→ the Connect IQ simulator (descentmk343mm, adb Connection › Start): a throwaway TEST face (its own app id, times and counts only) received each minute’s push (version 1, 10 keys, 12 history slots) and, on a temporal event, fetched the same payload from 127.0.0.1:17582 (HTTP 200); Sukrara Aura itself stored the pushed payload. The simulator’s fetch needs Use Device HTTPS Requirements off (its default mimics a phone that allows only https); Garmin Connect on Android allows http to loopback (08). - The owner’s phone and watch, 2026-11-16 (Garmin Connect 5.31, Android 17):
- Push reaches the watch: Garmin Connect confirmed every message 1–3 s after its reading (14:18–14:27, one or two a minute), and the face showed a value after each reconnect.
- Disconnections stop everything, as designed: the watch on the Mac’s USB (13:52–14:09, the phone link drops) and a Bluetooth toggle (14:11–14:19: the watch only came back when its Phone control was toggled) left the face aging from 13:52, then 14:19.
- The face applied the readings late: at 14:21:58 it still showed 14:19 though 14:20 and 14:21 were confirmed
delivered. The first guess, from forum reports, was a 5-minute limit on a face’s background
(staff,
AAPS push face). The face’s report disproved it
(14:36–14:43): the background ran within 0–3 s of every delivered message, once a minute, but each run got the
oldest waiting message: the three messages queued while the face was being installed stayed queued, so every
push gave the face the reading from 3 minutes before (runs at 14:39:47, 14:40:46, 14:41:51 got the payloads built
at 14:37:42, 14:38:22, 14:38:43). The 5-minute fetch (14:38:40, 14:43:41) brought the newest each time, which the
face kept over the older pushes. Fix: each push run takes every waiting message
(
Communications.registerForPhoneAppMessages, called at once per waiting message) and hands the face the newest. - With the fix (52dfb22fc, 14:56–15:01): the first run after the install took the 3 waiting messages with it
(
p3) and kept the newest; from then on every run got the message just sent, 1–7 s after the phone built it (14:56:48 → :50, 14:57:49 → :56, 14:58:49 → :50, 14:59:50 → :52, 15:00:52 → :53). The phone builds it 3–4 s after the reading (it waits for the payload to settle), so a reading reaches the watch in about 5–11 s. - The phone sent a second message a couple of seconds after each reading (the payload changing in two steps): gone, one message per reading.
- Not done on the device: the Bluetooth-off test (turning the phone’s Bluetooth off from the agent was refused by its permission check); the two unplanned disconnections above showed the aging and the page’s “isn’t connected”, but also that the watch may need its Phone control toggled to come back after the phone’s Bluetooth returns (Garmin’s link, not Sukrara’s).
- Seeing the watch without looking at it: Garmin’s ways are
System.printlntoGARMIN/APPS/LOGS/<app>.TXT(when that file exists) and crash reports inGARMIN/APPS/LOGS/CIQ_LOG.YML(FAQ, logging tips), both read over USB, which drops the phone link the check is about. Chosen instead: the face reports with its fetch what it got (each push and fetch, the watch’s time, which payload) and what it draws; the phone shows it (On the watch) and logs it (logcatSukrara.Aura). It costs nothing extra on the watch and is useful to the person too. The USB logs stay for crashes. - The screen (2026-11-16, the owner: “when I raise the wrist the brightness is down… open any menu, it increases…
back to the watchface it decreases again”): the report also carries the face’s last 12 screen events, after the
deliveries in
rand in their shape,<event>.<watch time>.<display mode>.0:SonShow,XonExitSleep (wrist raise, button),EonEnterSleep,ConDisplayModeChanged, andDa/Dn/Dwthe first draw in always-on / night / awake; the display mode isSystem.getDisplayMode()then (0 high power, 1 low power, 2 off). Times and modes only. The face used to decide always-on from the display mode alone on API 5 watches (Garmin staff advise it over the sleep callbacks, forum):onShowread it andonExitSleepwas ignored. Had the Descent said low power on the way back from a menu, or not calledonDisplayModeChangedon a wrist raise, the face drew its dimmer always-on look (outlined grey time, dimmer palette) while awake: both of the owner’s symptoms. Now the last callback decides:XandS→ awake (motion only afterX, #223),E→ always-on on an AMOLED,C→ the display mode. Reading a wake in logcat’s runs:X@<t>/sent 0thenDw@<t>/sent 0(Dnin the sleep window;sentis the display mode);S@<t>/sent 1or noC@<t>/sent 0afterXconfirms the old code’s mistake. What the device showed (a4962d408, 15:51 EET):X@1794837086/sent 0 … Dn@1794837086/sent 0 … E@1794837092/sent 2 … Da … X@1794837092/sent 0 … Dn@1794837093/sent 0: every wrist raise woke the face, into the night palette in the afternoon. In the watch-face picker every other face was bright and this one dimmer (the owner). Night came fromUserProfilesleepTime / wakeTime (documented as seconds since local midnight, Profile); on newer watches the Sleep Mode schedule is set per day and doesn’t reach those fields, which keep old or default values (forum). The per-dayupcomingSleepTimeneeds API 6 (the Descent has 5.1) andActivityMonitorisSleepModeis deprecated. Garmin’s own way of the night is Sleep Mode (hold MENU › System › Sleep Mode: Schedule per day, Watch Face, Display, Do Not Disturb, Mk3 manual) with its own During Sleep display settings, and Do Not Disturb “dims the screen”. So the face is in night whileDeviceSettings.doNotDisturbis on (Sleep Mode turns it on unless the person turned that off), and the report carries the raw facts once per change as aPentry,Ps<sleepTime>w<wakeTime>t<clock>d<doNotDisturb>z<isSleepMode> n<isNightModeEnabled>.<watch time>.<display mode>.0(seconds since midnight; 1 / 0, 9 not on the watch, -1 no value). The panel’s own brightness is the firmware’s: the ambient light sensor dims a wrist-raise wake in low light “by design” and a button gives full power (Garmin, fēnix 8), and always-on runs the panel dimmed, which a face can’t change (garmin-matrix-time #164).
In Sukrara
Section titled “In Sukrara”Added:
:integrationsgarmin/:AuraPayload(built from the hub’s state, THE trend, the alert runtime’s status, the sensor as the card decides it, the card’s last treatment, today’s time in range),MonkeyC(the wire format),ConnectIq(Garmin Connect’s service, no SDK),AuraLink(push, retry, reconnect, the fetch server on 127.0.0.1:17582), the page (Share with apps › Garmin since 2026-11-16’s redesign:GarminPage, en / es); settingapps.garmin(on).apps/garmin/source/link:AuraLinkService(the face’s background: the push, the 5-minute fetch) andAuraLink(the newest payload in storage, the inputs at every draw, THE SEAM’sAuraReading);LinkTestruns every case.- Debug:
GARMIN_SIMsends to the Connect IQ simulator (tethered mode). contracts/watchface/payload(README, schema, cases, Garmin’s bytes); parity groupwatchface-link.
Discarded, and why:
- Garmin’s companion SDK: proprietary; Sukrara is GPL and ships the same APK to F-Droid.
- Direct BLE: not documented for faces, would compete with Garmin Connect’s own connection, and Juggluco’s reverse-engineered protocol is for a different app type.
- A push that only says “fetch now” (Pwb0186, AAPS): it would make every update depend on the HTTP path, which has its own Garmin Connect bug; the whole payload in both keeps either path enough on its own.
- Watch → phone acknowledgements by message: that direction is the one CIQQA-4631 breaks first; the fetch is the acknowledgement.
- A secret for the fetch: the face has no channel to learn one when push is broken, which is when the fetch is needed. Instead the port is narrowed (the main session’s decision, 2026-11-16): it opens only while a watch is known to have the face (Garmin Connect says it is installed, or a push reached it), loopback only, and the switch closes it. Left exposed: while a watch has the face, any app on the phone can read the face’s payload (the last 3 hours, the pill, the last treatment, the sensor’s dates, today’s time in range) from 127.0.0.1:17582, as any app can read the xDrip+ server while that is on. A phone without the face, or with the link off, serves nothing. Cost: if Garmin Connect neither answers about the face nor delivers a push (its bug at its worst), the port stays closed and the face gets nothing until one of them works; the page shows “Closed until a watch has Sukrara Aura”.
- The xDrip+ server for the face: off by default, Juggluco’s port, and its format lacks the pill, the sensor and the treatments. It stays as it is for other Garmin faces.
The settings (redesign, 2026-11-16; the owner: xDrip+ isn’t a watch, its apps can’t be switched one by one, “Sukrara Aura” is one face of several, three “minutes ago” that look alike, Send now not looking like an action):
- Share with apps › Watches › Garmin, one row (the name says where, not which face), opening a page built like
stock Settings’ device pages: a main switch for Sukrara’s own link, because that is what can really be turned
off (
apps.garmin: push and fetch together, for every Sukrara app on every watch; a per-watch or per-app switch has no use: the person picks the face on the watch), the AOSP guidelines’ “main setting” for a feature that turns on or off as a whole; action buttons (Send now, Open Garmin Connect) as App info and Bluetooth device details draw them (SPAActionButtons), not rows; Watches with Garmin Connect’s own names, one line each with one clock time (“has the 14:21 reading”, comparable with the phone); Sukrara on your watch (the face now; the data field and app later), where the face’s fetch says whether it is the face in use. - The xDrip+ server is a local server for apps, not a watch: its row moves to Apps on this phone beside the Nightscout API, with its own page (main switch, Apps that read it as a plain list with app icons, like stock Location’s app list, no switches), and the Garmin page links to it for other faces and data fields.
- Compared: xDrip+ hides its server in Inter-app settings with a bare checkbox; GlucoDataHandler and Juggluco put a web-server toggle among their sources (GDH, xDrip+); none says which watch got which reading. Discarded: a details page per watch (one or two watches don’t need it; their line holds all the link knows), a watch icon per row (a list of things of one kind has none), Send now disabled when no watch is near (SPA draws a disabled button’s label at full contrast; a send then does no harm).
- Whether push works on the owner’s Garmin Connect / Android 17 (CIQQA-4631): the device check tells, and the page shows it.
- Whether a face’s phone-message registration survives a watch reboot on the Descent (the face registers again on every start).