Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5ba4157
feat(garmin): frozen Phase-1 contract seams for issue #1391 packets B…
Nov 17, 2026
00258c5
feat(garmin): B1 shared seam + B7 watch app + B8 regressions for #1391
Nov 17, 2026
30a9d9b
feat(garmin): B3 phone UI — settings card + Arm strip for #1391
Nov 17, 2026
c0101f9
feat(garmin): B4/B5/B6 platform transports for #1391
Nov 17, 2026
28787ce
merge: B3 phone UI packet into feat/1391-garmin-watch-controls
Nov 17, 2026
ac22f58
merge: B4/B5/B6 platform transport packets into feat/1391-garmin-watc…
Nov 17, 2026
ceeb9fe
fix(test): TestScope receivers + enterSetReady reinitializeWarmups pa…
Nov 17, 2026
64e8c08
feat(garmin): B2 protocol + GarminSessionController internals for #1391
Nov 17, 2026
d503359
fix(garmin): PR #1407 follow-up — CI fixes for the #1391 Phase 1 branch
Nov 17, 2026
ecaf616
Merge remote-tracking branch 'origin/main' into feat/1391-garmin-watc…
Nov 17, 2026
988deaa
test(media): move Phase-1 schema gate baseline to 64.sqm (#1392 lande…
Nov 17, 2026
8a365ee
fix(garmin): type the watch app's SDK callbacks to the exact Monkey C…
Nov 17, 2026
f24ef43
fix(ci): unblock iOS test compile and garmin simulator dependencies
Nov 18, 2026
ce582b2
Merge remote-tracking branch 'origin/main' into feat/1391-garmin-watc…
Nov 18, 2026
cde79dd
fix(garmin-ci): use upstream simulator-dependency installer; raise si…
Nov 18, 2026
0485972
fix(ios): adopt current Connect IQ Mobile SDK names in GarminCompanio…
Nov 18, 2026
04289f6
fix(ios): finish porting GarminCompanionBridge/PhoenixApp to current …
Nov 18, 2026
301ef4d
fix(ios): add @executable_path/Frameworks rpath; dump MonkeyDo log on…
Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 134 additions & 0 deletions .github/workflows/garmin-ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Garmin Connect IQ watch app CI - issue #1391 B7 (watch button controls).
#
# Builds the Phoenix Remote watch app with monkeyc and runs the simulator
# protocol/input checks from garmin/tests/ per allowlisted product.
#
# - The Connect IQ SDK version is PINNED below (never "latest"), and device
# definitions come from the setup action's bundled archive for that exact
# SDK version, so builds are reproducible.
# - CI artifacts are unsigned/ephemeral-signed builds only. Release signing
# keys live in GitHub secrets (CONNECTIQ_DEVELOPER_KEY_BASE64) and are
# NEVER committed to the repository.
# - This workflow is intentionally standalone: the watch app is NOT wired
# into the Android/iOS Gradle build at all (no Gradle task here).

name: garmin-ci

on:
push:
paths:
- "garmin/**"
- ".github/workflows/garmin-ci.yml"
pull_request:
paths:
- "garmin/**"
- ".github/workflows/garmin-ci.yml"
workflow_dispatch:

permissions:
contents: read

env:
# Pinned Connect IQ SDK + device definitions (see garmin/README.md).
CIQ_SDK_VERSION: "9.2.0"

jobs:
static-checks:
name: Static checks (XML, contract strings, allowlist)
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4

- name: Install xmllint
run: sudo apt-get update && sudo apt-get install -y libxml2-utils

- name: Run static checks
run: bash garmin/tests/run-static-checks.sh

build-and-test:
name: Build + simulator checks (${{ matrix.device }})
needs: static-checks
runs-on: ubuntu-22.04 # required by the Linux simulator dependencies
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
# Product allowlist (five-button products, signoff correction 3).
# Keep in sync with garmin/manifest.xml (enforced by static checks).
device:
- fr255
- fr265
- fr965
- fenix7
steps:
- uses: actions/checkout@v4

- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "17"

# NOTE: DuckSoft/setup-connectiq-actions@v1 predates the
# install-simulator-dependencies input and silently ignores it, which left
# the simulator/monkeydo native deps (libsecret, libusb, libjpeg-turbo8,
# fonts, xauth ...) unresolved — monkeydo then hung until the outer
# timeout. Pin to the upstream main SHA that ships and validates the
# simulator dependency installer (ldd-checked for bin/simulator AND
# bin/shell); it requires runs-on: ubuntu-22.04 above.
- name: Set up ConnectIQ SDK + device definitions + simulator dependencies
uses: DuckSoft/setup-connectiq-actions@64f7145dcd1087c262d89f5f714fa03af27b3cba
with:
sdk-version: ${{ env.CIQ_SDK_VERSION }}
install-devices: "true"
install-simulator-dependencies: "true"

# Signing keys stay in GitHub secrets and are NEVER committed. If no
# secret is configured, an ephemeral key is generated: fine for CI-only
# unsigned test artifacts, useless for store submission.
- name: Restore developer key (or create ephemeral CI key)
shell: bash
env:
DEVELOPER_KEY_BASE64: ${{ secrets.CONNECTIQ_DEVELOPER_KEY_BASE64 }}
run: |
if [ -n "$DEVELOPER_KEY_BASE64" ]; then
printf '%s' "$DEVELOPER_KEY_BASE64" | base64 --decode > "$RUNNER_TEMP/developer_key.der"
echo "Using repository-secret developer key (not printed)."
else
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out "$RUNNER_TEMP/test-key.pem"
openssl pkcs8 -topk8 -inform PEM -outform DER -in "$RUNNER_TEMP/test-key.pem" \
-out "$RUNNER_TEMP/developer_key.der" -nocrypt
rm -f "$RUNNER_TEMP/test-key.pem"
echo "Using ephemeral CI-only developer key."
fi

- name: Build watch app (monkeyc)
run: |
mkdir -p build
monkeyc \
-f garmin/monkey.jungle \
-d "${{ matrix.device }}" \
-o "build/phoenix-app-${{ matrix.device }}.prg" \
-y "$RUNNER_TEMP/developer_key.der"

- name: Build Run No Evil tests (monkeyc -t)
run: |
monkeyc \
-f garmin/monkey.jungle \
-d "${{ matrix.device }}" \
-o "build/phoenix-tests-${{ matrix.device }}.prg" \
-y "$RUNNER_TEMP/developer_key.der" \
-t

- name: Run simulator protocol/input checks (monkeydo -t)
run: |
bash garmin/tests/run-simulator-tests.sh \
"build/phoenix-tests-${{ matrix.device }}.prg" \
"${{ matrix.device }}"

- name: Upload CI artifact
uses: actions/upload-artifact@v4
with:
name: phoenix-garmin-${{ matrix.device }}
path: build/*.prg
if-no-files-found: error
194 changes: 194 additions & 0 deletions garmin/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
# Phoenix Remote — Garmin watch app (issue #1391, packet B7, Phase 1)

Companion **watch app** for Project Phoenix workout control. Press physical
buttons on the watch while your hands are on the bar; the phone side (packets
B2–B5) does the real work. This tree is Monkey C for Connect IQ plus its
standalone GitHub Actions workflow.

**Phase 1 scope — deliberately minimal:**

- `START_NEXT`, `STOP_SET`, and *confirmed* `CANCEL_EXERCISE` commands over the
frozen v1 message protocol (below).
- Mandatory text feedback on every press: **pending**, **applied**, **stale**,
**UNKNOWN_RESULT**, and the **REJECTED reason code** verbatim.
- Display shows only the minimal current target + readiness
(`displayLabel` / `readiness` from `STATE`). The full exercise/set/rest
dashboard is **Phase 2 and forbidden here**.
- Haptic (buzz) **only** after `RESULT` stage=`APPLIED` — never on `ACCEPTED`
or on any rejection.

## Runtime requirements

- **The watch app must be OPEN during the workout.** Transport is Connect IQ
Mobile SDK *foreground* messaging — there is no background delivery and no
REST anywhere.
- **Garmin Connect Mobile must be installed and paired on the phone**, and the
Phoenix phone app must be running to exchange `HELLO` / `STATE` / `COMMAND` /
`RESULT` messages.

## Supported products (PROVISIONAL)

> The supported-models list is **provisional pending simulator verification**.
> Store submission is **release-time only** — nothing here is published yet.

| Product | Connect IQ id | Layout |
|---|---|---|
| Forerunner 255 | `fr255` | five-button |
| Forerunner 265 | `fr265` | five-button (acceptable per signoff correction 3) |
| Forerunner 965 | `fr965` | five-button |
| fēnix 7 | `fenix7` | five-button |

Touch-only or non-matching products are **excluded entirely**, not
half-supported. The allowlist is encoded as product entries in
`garmin/manifest.xml`; `garmin/tests/run-static-checks.sh` enforces that the
manifest, this list, and the CI matrix stay in sync.

## Button mapping (five-button products, signoff correction 3)

| Button | Action |
|---|---|
| top-right `START/ENTER` | Start/Next; **second** press confirms Cancel |
| bottom-right `BACK/LAP` | urgent `STOP_SET` — **always Stop, never confirms** |
| bottom-left `DOWN` | open Cancel confirmation |
| middle-left `UP` | dismiss confirmation |
| top-left `LIGHT` | **not intercepted** (system behaviour) |

Press/release is consumed exactly once (key-repeat and hold events are
suppressed). There is **no long-hold destructive action anywhere**.

Cancel confirmation names the exercise from `STATE.confirmationLabel`:

> **Cancel Bench Press?**
> Skip only Bench Press, not the whole routine. Previously saved sets stay
> saved.
> *Ergonomic remote, NOT an emergency stop.*

## Frozen v1 wire contract (Monkey C Dictionary, string keys)

Every message carries `v: 1` (int) and `type` (string).

- `HELLO` (watch→phone) = `{watchInstanceId:string, supportedVersions:[1]}` —
handshake only, **never Arm**. Sent on open/initial entry/reconnect and
before any gesture when no fresh grant exists. Never periodic.
- `STATE` (phone→watch) = `{controlEpoch, revision, contextId,
allowedActions:array<string>, readiness, phoneForeground, foregroundRequired,
backgroundStopSupported, displayLabel, actionLabel}` +
optional `{actionGrant, grantTtlMs, confirmationToken, confirmationTtlMs,
confirmationLabel}`.
- `COMMAND` (watch→phone) = `{controlEpoch, commandId, contextId,
expectedRevision, action, actionGrant}` — `CANCEL_EXERCISE` **additionally
requires `confirmationToken`**.
- `RESULT` (phone→watch) = `{commandId, controlEpoch, contextId,
stage: ACCEPTED|APPLIED|REJECTED}` + optional `reason` (**required** for
`REJECTED`).

Actions: `START_NEXT` | `STOP_SET` | `CANCEL_EXERCISE`.
Readiness: `DISABLED | UNAVAILABLE | SETUP | CONNECTED | ARMED_READY | ACTIVE |
RESTING | SUMMARY | PHONE_INPUT_REQUIRED | BUSY | ERROR | RECOVERY_REQUIRED`.
REJECTED reasons: `STALE_STATE | NOT_READY | DISCONNECTED |
UNSUPPORTED_VERSION | DISABLED | BUSY | RECOVERY_REQUIRED | SAVE_FAILED |
UNKNOWN_RESULT | INVALID_MESSAGE | PAYLOAD_TOO_LARGE | UNAUTHORIZED_DEVICE |
COMMAND_ID_CONFLICT | CONFIRMATION_EXPIRED | EPOCH_CAP_REACHED`.

Message limits (the watch validates all of these **before sending**):
≤ 2048 encoded bytes/message, ≤ 24 dictionary keys, ≤ 2 container levels
(root dict + scalar array), ≤ 3 array elements, ids/grants/tokens ≤ 64 ASCII
bytes, labels ≤ 80 UTF-8 bytes, enum strings ≤ 32 bytes.

Timing: grant TTL 3000 ms, confirmation TTL 10000 ms, result timeout 5000 ms
(displayed TTLs are advisory only; the phone is authoritative and answers
`STALE_STATE` / `CONFIRMATION_EXPIRED` when the watch oversteps).

Transport APIs (Connect IQ Mobile SDK foreground messaging):

```monkeyc
// phone -> watch
Communications.registerForPhoneAppMessages(method(:onPhoneMessage));
// watch -> phone
Communications.transmit(messageDict, {}, sendListener);
```

## Watch-side behaviour (contract)

- Requires a **fresh `STATE` before dispatching a `COMMAND`**; a `COMMAND`
always rides the phone-issued 3 s `actionGrant` in the same `contextId`.
- Retains **at most one gesture**, only inside that grant window; discards it
on disconnect / app background / epoch or context invalidation.
- A `STALE_STATE` rejection requires a **new press** — the watch never
resubmits the old command id and never auto-retries with a new one. On the
5 s result timeout it shows `UNKNOWN_RESULT` and waits for a fresh press.
- `watchInstanceId` is **untrusted metadata**; dedupe/replay protection is
phone-side.

## Building locally

Prerequisites: [Connect IQ SDK](https://developer.garmin.com/connect-iq/sdk)
(9.2.0 recommended to match CI) with device definitions for the allowlist, a
developer key (`openssl pkcs8 -topk8 -inform PEM -outform DER -in key.pem
-out key.der -nocrypt`), and a JRE 17+.

Exact `monkeyc` build invocation (run from the repo root):

```sh
monkeyc -f garmin/monkey.jungle -d fr255 -o build/phoenix-app-fr255.prg -y /path/to/developer_key.der
```

Exact `monkeydo` simulator invocation (start the simulator first with
`connectiq`; `-t` runs the Run No Evil protocol/input checks):

```sh
monkeyc -f garmin/monkey.jungle -d fr255 -o build/phoenix-tests-fr255.prg -y /path/to/developer_key.der -t
connectiq # launch simulator
monkeydo build/phoenix-tests-fr255.prg fr255 -t # run checks
```

On CI the same steps run headlessly via
`bash garmin/tests/run-simulator-tests.sh <tests.prg> <device>` (simulator
under Xvfb + D-Bus; adapted from DuckSoft/setup-connectiq-actions, MIT).

Static sanity checks (any machine with bash + xmllint):

```sh
bash garmin/tests/run-static-checks.sh
```

## CI (.github/workflows/garmin-ci.yml)

- Pins the Connect IQ SDK version (`CIQ_SDK_VERSION`) and installs the pinned
device-definition archive — never `latest`.
- Builds the watch app per allowlisted product with `monkeyc`, then builds and
runs the simulator protocol/input checks (`monkeyc -t` + `monkeydo -t`) from
`garmin/tests/`: button mapping, confirm/dismiss, one action per press with
no repeats, pending/applied/stale/unknown text, HELLO/fresh-STATE without
flooding.
- CI artifacts are unsigned/ephemeral-signed. **Signing keys live in GitHub
secrets (`CONNECTIQ_DEVELOPER_KEY_BASE64`) and are never committed.**
- There is **no Gradle Garmin task** — the watch app is not wired into the
Android/iOS build at all.

## Notes for the phone side

- `commandId` format generated by the watch: `<watchInstanceId>-<n>` where
`n` is a per-run monotonic counter starting at 1, and `watchInstanceId` is
`w<epochSeconds>-<msSinceBoot>` (untrusted metadata, ≤ 64 ASCII bytes).
- `expectedRevision` echoes `STATE.revision` from the most recent `STATE`.
- `HELLO` retry behaviour: sent once on open/initial entry/reconnect, and
before any gesture when no fresh grant exists (throttled to ≥ 500 ms
between HELLOs). There is no periodic heartbeat — if the phone wants a
re-handshake it must provoke a gesture or reconnect.
- On `RESULT` stage=`APPLIED` the watch buzzes once; `ACCEPTED` and rejections
are text-only.

## Tree

```
garmin/
manifest.xml product allowlist + permissions
monkey.jungle build definition
source/PhoenixApp.mc app shell, transport glue, haptics
source/PhoenixView.mc minimal target + readiness + feedback / confirm UI
source/PhoenixDelegate.mc five-button input (one action per press)
source/PhoenixProtocol.mc frozen v1 wire contract + control machine
resources/strings/ all user-facing copy
tests/ Run No Evil checks + CI scripts
```
43 changes: 43 additions & 0 deletions garmin/manifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Phoenix Remote watch app - issue #1391 packet B7 (Garmin watch button controls, Phase 1).

Product allowlist (signoff correction 3): five-button products only. Every
product below exposes the five-button layout/key events the button mapping
depends on (top-right START/ENTER, bottom-right BACK/LAP, bottom-left DOWN,
middle-left UP, top-left LIGHT not intercepted). Touch-only or non-matching
products are excluded entirely, not half-supported. The shortlist is
PROVISIONAL pending simulator verification - see garmin/README.md.

App id is a development UUID; store submission (release-time only) may
replace it with the registered store id.
-->
<iq:manifest xmlns:iq="http://www.garmin.com/xml/connectiq" version="3">
<iq:application id="996ea08a8af34f9e9702be9502394c9b"
type="watch-app"
name="@Strings.AppName"
entry="PhoenixApp"
launcherIcon="@Drawables.LauncherIcon"
minSdkVersion="3.2.0"
version="0.1.0">
<iq:products>
<!-- Forerunner 255 -->
<iq:product id="fr255"/>
<!-- Forerunner 265 (acceptable per signoff correction 3) -->
<iq:product id="fr265"/>
<!-- Forerunner 965 -->
<iq:product id="fr965"/>
<!-- fenix 7 -->
<iq:product id="fenix7"/>
</iq:products>
<iq:permissions>
<!-- Connect IQ Mobile SDK foreground messaging (transmit /
registerForPhoneAppMessages) with the Phoenix phone app. -->
<iq:uses-permission id="Communications"/>
</iq:permissions>
<iq:languages>
<iq:language>eng</iq:language>
</iq:languages>
<iq:barrels/>
</iq:application>
</iq:manifest>
10 changes: 10 additions & 0 deletions garmin/monkey.jungle
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Phoenix Remote (issue #1391 packet B7).
#
# Keep the build minimal: sources plus the Run No Evil test module. The
# (:test) annotation keeps test functions inert unless monkeyc -t / monkeydo -t
# runs them, so `tests` can safely sit on the base source path.

project.manifest = manifest.xml

base.sourcePath = source; tests
base.resourcePath = resources
4 changes: 4 additions & 0 deletions garmin/resources/drawables/drawables.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<drawables>
<bitmap id="LauncherIcon" filename="launcher_icon.png"/>
</drawables>
Binary file added garmin/resources/drawables/launcher_icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading