Starter Garmin Watch App

Modern Garmin devices allow for custom applications to run on them. This ecosystem is known as Garmin Connect IQ.

In this exploration, we get an example application running using the Connect IQ SDK. Sadly, the SDK itself is non-free and requires an account to download. However, specific attention is paid to avoid to any other proprietry/non-free software. To this end, we won't be using VS code (and associated plugins), which is the usual way to develop on the platform.

Note that much of the below is summarised at https://developer.garmin.com/connect-iq/reference-guides/monkey-c-command-line-setup/, but this guide might still be of use to explain the end-to-end process of getting an app running.

Install the SDK

Download the SDK from the Connect IQ website (https://developer.garmin.com/connect-iq/sdk/). In this case, we'll be using the Linux version. Open the installer and create an account/login. Continue as per Garmin's guide: https://developer.garmin.com/connect-iq/connect-iq-basics/getting-started/. Be sure to install the latest SDK, as well as whatever device you'd like to target.

Add the SDK to your PATH

export PATH=$PATH:`cat $HOME/.Garmin/ConnectIQ/current-sdk.cfg`/bin

Add the same above line to ~/.bash_profile to persist the change.

Getting a sample application

Garmin provides sample applications. We'll be using one of these. Samples can be found at /home/username/.Garmin/ConnectIQ/Sdks/connectiq.../samples. Here we select SimpleDataField.

Copy an example to a directory (this directory will be our base directory).

Generating a private developer key

Garmin apps need to be signed by a private key (RSA, 4096 bit). This key needs to be stored safely and permanently since you will need it any time you want to update your app (particularly if you end up sharing your app through the app store). Usually this key is generated using IDE plugins, but here we use common unix CLI tools.

In our base directory, alongside the sample application folder, run the following to generate an RSA key with OpenSSL:

openssl genrsa -out garmin_priv_rsa.pem 4096

The above generates a PEM 4096 bit key. Note that it must be 4096; if 2048 is used you will get an 'Signature check failed' error later on. PEM is the common plaintext key format. However, Garmin requires the key as a binary (DER format). To convert to DER:

openssl pkcs8 -topk8 -inform PEM -outform DER -in garmin_priv_rsa.pem -out garmin_priv_rsa.der -nocrypt

Now our base directory looks like this (note that the public cert is not required):

Makefile

To build Connect IQ apps, a number of CLI tools are provided in the SDK. IDE plugins use these under the hood to build/run the app. However, a more IDE/environment agnostic method of calling these tools is to use a Makefile. In the sample application directory, we create a Makefile containing the following:

DEVICE = instinct2
PRIVATE_KEY = ../garmin_priv_rsa.der
APP_NAME = yourappname

build:
	monkeyc \
	--jungles ./monkey.jungle \
	--device $(DEVICE) \
	--output bin/$(APP_NAME).prg \
	--private-key $(PRIVATE_KEY) \
	--warn

run: build
	@monkeydo bin/$(APP_NAME).prg $(DEVICE)

Edit DEVICE to be one of the devices listed in your manifest.xml file (see info below).

A note on devices and the manifest file

Within the sample app folder, you will find a manifest.xml file. This contains the list of devices that your app is compatible with (amongst other app details). Edit this accordingly. Note that for whichever device you want to support, you will need those device profiles installed via the SDK manager.

Building, running on the simulator

In the sample directory, now run make build.

To run the app on the simulator, the simulator needs to be started first:

connectiq

Once the simulator is running, in another terminal, run make run in the sample app directory. The app will now be loaded into the simulator.

Installing onto device

Simply copy the .prg file in /bin to the APPS folder on your device (connected in mass storage mode).

Cardinal

Engineering Log