Introduction

Many Garmin devices like heart rate monitors or bike computers support the download and execution of apps. These enable custom watch faces, additional data fields during activities, and stand-alone apps and widgets.

Garmin offers the Connect IQ SDK free of charge to develop your own apps. However, the SDK is only offered for Windows and Mac OS. Fortunately, it mostly relies on Java and two simple platform-dependent applications which are simple enough for Wine.

More Information

Installation

The shown installation instructions were used for Debian (sid) in October 2016 on an Intel Core i7 PC. If you have a different Linux distribution, your steps might differ.

1) Download the Connect IQ SDK

Use the version for Windows (!) from https://developer.garmin.com/connect-iq/sdk/. These instructions were tried with version 2.1.4.

2) As root, extract the package

su -
mkdir /opt/Garmin-ConnectIQ
cd /opt/Garmin-ConnectIQ
unzip /path/where/you/stored/connectiq-sdk-win-2.1.4.zip

This will result in an installation of 123M.

3) For Linux, a few minor adaptions are necessary

To start the two Windows .exe programs with Wine, the shell scripts "shell" and "simulator" are created. Further, all scripts are made executable and Unix line end convention is ensured.

cd bin/
echo -e '#!/bin/bash\n\nwine $(dirname "$0")/shell.exe "$@"' > shell
echo -e '#!/bin/bash\n\nwine $(dirname "$0")/simulator.exe "$@"' > simulator
chmod a+x monkeyc monkeydo monkeygraph connectiq connectiqpkg simulator shell
sed -i 's/\r//g' monkeygraph

4) Make the executables callable from everywhere

You have to add the bin directory to your path.

export PATH="$PATH:/opt/Garmin-ConnectIQ/bin"

Unfortunately, the scripts don't support to be symbol-linked from e.g., /usr/local/bin/, because they use $0 to determine their base directory.

5) Install Java and Wine

Debian Packages wine32:i386 and default-jre and their dependencies work fine.

6) As user, create a developer key

See the explanation at https://developer.garmin.com/connect-iq/programmers-guide/getting-started/

mkdir ~/.ciq
openssl genrsa -out ~/.ciq/developer_key.pem 4096
openssl pkcs8 -topk8 -inform PEM -outform DER \
    -in ~/.ciq/developer_key.pem \
    -out ~/.ciq/developer_key.der -nocrypt

Test

7) Test

Setup the path

export PATH="$PATH:/opt/Garmin-ConnectIQ/bin"

Copy and compile a sample program

mkdir /tmp/ciqtest
cd /tmp/ciqtest
cp -r /opt/Garmin-ConnectIQ/samples/ProgressBar/ .
cd ProgressBar/
monkeyc -y ~/.ciq/developer_key.der -o ProgressBar.prg \
    -m manifest.xml -z resources/resources.xml \
    -z resources/strings.xml -z resources/bitmaps.xml \
    source/ProgressBar.mc source/ProgressBarView.mc

Start the simulator in the background

connectiq &

Start your program

monkeydo ProgressBar.prg

This will upload the program and then execute it. You can stop the application using File → Kill App or by pressing the back button at the start screen of the app.

8) Another Test

Copy the source code of the example program

cd /tmp/ciqtest
cp -r /opt/Garmin-ConnectIQ/samples/Picker/ .
cd Picker/

Create a new file "build.sh" with the content:

#!/bin/bash

# result/output
OUT=Picker.prg

# developer key
DEVEL_KEY=~/.ciq/developer_key.der

# MonkeyC compiler
CC=monkeyc

# declare an array for all arguments
declare -a args

# developer key
args+=('-y' "$DEVEL_KEY")
# output
args+=('-o' "$OUT")
# manifest
args+=('-m' 'manifest.xml')
# resources
for i in resources*/*.xml resources*/*/*.xml ; do
  args+=('-z' "$i")
done
# sources
for i in $(find source -iname '*.mc') ; do
  args+=("$i")
done

# compile
$CC "${args[@]}"

Make it executeable and execute it

chmod a+x build.sh 
./build.sh

Finally run the program and click on the buttons

monkeydo Picker.prg fr920xt

If you press the back-button in the intro screen, the program exits.

The color picker doesn't work but crash because it can't find the resource. I don't know if this is my fault or theirs.

Additional Notes

Attention: The simulator will always use the extension ".prg", regardless of what you specify with "monkeydo". If it can't find your executable, "monkeydo" will display a "System Error" (very informative!)
The uploaded apps are placed in .wine/drive_c/users/<username>/Temp/GARMIN/APPS/
The upload and the start are executed in two steps, i.e., shell.exe is executed twice. See the script monkeydo for more details on the parameters of shell.exe.
The tool "connectiqpkg" doesn't work because the Java file pkgtool.jar is missing.
You can start "monkeydo" with a second parameter to specify the watch or watch type. Possible values are "square_watch", "round_watch", "semi_round_watch", "tall_watch", "fr920xt", "fr735xt", "fr230", ...
For a complete list, see the "id" attribute of the "device" entries in /opt/Garmin-ConnectIQ/bin/devices.xml
Attention: If you use an invalid watch type, nothing is displayed and "monkeydo" simply hangs. You have to kill "shell.exe".

Johann Glaser

Samstag, 29. Oktober 2016

Garmin Connect IQ on Linux