Garmin 워치페이스 직접 만들어보기 ①|Connect IQ SDK 설치부터 실제 시계 실행까지
Garmin 시계를 사용하다 보면 한 번쯤 이런 생각이 들 수 있습니다.
“내가 원하는 화면을 직접 만들어서 Garmin 시계에 넣을 수 있을까?”
저도 처음에는 단순한 호기심에서 시작했습니다.
평소 웹 개발을 하면서 PHP와 JavaScript를 사용했고, 최근에는 React와 Next.js까지 공부하면서 자연스럽게 다른 개발 환경에도 관심을 갖게 되었습니다.
그러다 Garmin 워치페이스를 직접 만들어볼 수 있다는 것을 알게 되었고, 실제로 Garmin Connect IQ와 Monkey C를 이용해 워치페이스를 만들어 보기로 했습니다.
처음부터 거창한 앱을 만들려고 한 것은 아닙니다.
일단 가장 중요한 목표를 하나 정했습니다.
“개발환경을 설치하고, 아주 간단한 워치페이스를 만들어서 실제 Garmin 시계에서 실행해 보자.”
이번 글에서는 그 첫 번째 과정을 기록해 보려고 합니다.
아직 복잡한 기능을 구현하는 단계는 아닙니다. 오히려 처음 Garmin 개발을 시작하는 분들이 그대로 따라올 수 있도록 Connect IQ SDK 설치부터 프로젝트 생성, 빌드, 실제 시계에 설치하는 과정까지 하나씩 정리해 보겠습니다.
Garmin 워치페이스 개발은 무엇으로 할까?
Garmin 웨어러블용 앱을 개발하려면 Garmin에서 제공하는 Connect IQ SDK를 사용합니다.
Connect IQ는 Garmin의 스마트워치와 다양한 웨어러블 기기에서 실행되는 앱을 개발하기 위한 개발 플랫폼입니다.
워치페이스뿐만 아니라 디바이스 앱, 위젯, 데이터 필드, 오디오 관련 앱 등 여러 종류의 프로그램을 만들 수 있습니다.
제가 이번에 만들어보려고 한 것은 그중에서도 가장 접근하기 쉬운 Watch Face, 즉 워치페이스입니다.
Garmin 개발을 처음 접했을 때 가장 먼저 눈에 들어온 것은 개발 언어였습니다.
Garmin은 Monkey C라는 프로그래밍 언어를 사용합니다.

처음 이름을 봤을 때는 조금 낯설었습니다.
“Monkey C라는 이름의 언어가 실제로 Garmin 개발에 사용되는구나.”라는 생각부터 들었습니다.
그런데 실제 코드를 조금 살펴보니 완전히 새로운 방식의 언어라기보다는 기존 프로그래밍 언어를 사용해 본 사람이라면 접근하기 어렵지 않은 구조였습니다.
저 역시 PHP와 JavaScript를 사용해 왔기 때문에 처음부터 언어 자체가 가장 큰 장벽은 아니었습니다.
오히려 처음에는 SDK와 개발환경을 어떻게 구성해야 하는지가 더 궁금했습니다.
처음에는 Connect IQ SDK부터 준비했다
Garmin 개발을 시작하기 위해 먼저 필요한 것은 Connect IQ SDK였습니다.
Garmin에서는 Connect IQ SDK를 관리할 수 있도록 Connect IQ SDK Manager를 제공합니다.
https://developer.garmin.com/connect-iq/sdk

이 프로그램을 통해 설치할 SDK 버전을 확인하고, 개발에 사용할 SDK와 지원 기기 정보를 관리할 수 있습니다.
설치하지 않으신 분은, Accpet & Download (본인 컴퓨터) 를 클릭하시고 다운 받은 zip을 압축풀기 하신 후에 SDKManger를 클릭하시면 됩니다.
저도 기존에 설치해 놓았던 SDK Manager를 다시 실행해 봤습니다.
그런데 여기서 재미있는 일이 하나 있었습니다.
제가 이 컴퓨터에서 Garmin 개발환경을 예전에 설치했던 기억은 있었는데, 정확히 어디에 설치했는지 바로 떠오르지 않았습니다.
다운로드 폴더를 찾아보니 예전에 받아놓은 Connect IQ SDK Manager 관련 파일이 남아 있었습니다.
확인해 보니 2024년에 설치했던 흔적이 있었습니다.
결국 개발환경을 완전히 처음부터 설치하는 것은 아니었지만, 이번에는 블로그에 과정을 남길 생각이었기 때문에 현재 환경을 다시 확인하면서 진행했습니다.

이 과정을 기록해 두는 이유는 간단합니다.
나중에 다른 사람이 제 글을 보고 Garmin 개발을 시작한다면 “그래서 대체 뭘 설치해야 하지?”라는 부분에서 막히지 않았으면 했기 때문입니다.
Connect IQ SDK Manager에서 SDK를 확인했다
Connect IQ SDK Manager를 실행하면 SDK와 Devices를 확인할 수 있습니다.
처음 실행했을 때 저는 설치되어 있는 SDK와 다운로드할 수 있는 SDK 목록을 확인했습니다.
SDK Manager에는 여러 Connect IQ 버전이 표시되고, 각 버전에 해당하는 릴리스 날짜와 다운로드 용량도 확인할 수 있습니다.
현재 개발환경에서는 최신 SDK를 비롯해 여러 버전을 선택할 수 있었고, 저는 실제 개발에 사용할 환경을 확인하면서 진행했습니다.
여기서 중요한 것은 SDK 버전과 API Level을 같은 개념으로 생각하지 않는 것이었습니다.
처음에는 저도 조금 헷갈렸습니다.
SDK는 개발에 사용하는 전체 개발 도구의 버전이고, API Level은 애플리케이션이 어느 수준의 Connect IQ 기능을 요구하는지를 판단하는 기준에 가깝습니다.
따라서 “최신 SDK를 설치했으니 모든 기기를 지원할 수 있다”라고 단순하게 생각하면 안 됩니다.
실제로 어떤 기기를 지원할 수 있는지는 프로젝트의 최소 API Level과 매니페스트에 설정된 지원 제품 등에 따라 달라집니다.
여기서는 가장 최신 버전인 API 6.0을 설치하시기를 권해드립니다.
Devices에서 지원 기기를 확인했다
SDK Manager에는 Devices 탭도 있습니다.
이 부분이 생각보다 중요했습니다.
Garmin은 워치 종류가 굉장히 많고, 제품마다 지원하는 Connect IQ 기능과 API 수준이 다를 수 있기 때문입니다.
Devices 화면을 확인해 보니 API Level별로 지원 기기를 확인할 수 있었습니다.
제가 사용하는 기기는 Garmin Forerunner 265입니다.
이번 첫 번째 테스트에서는 복잡한 기능을 사용하는 것이 아니라 아주 기본적인 워치페이스를 실행하는 것이 목적이기 때문에, 우선 개발환경에서 제 기기를 사용할 수 있도록 준비했습니다.

저 같은 경우는 포러너 265이기 때문에.. 이걸 설치했습니다.
Visual Studio Code에 Monkey C를 설치했다
SDK를 준비했다고 해서 바로 코드를 작성할 수 있는 것은 아니었습니다.
저는 개발 편의를 위해 Visual Studio Code를 사용했습니다.
그리고 VS Code의 Extensions Marketplace에서 Monkey C를 검색했습니다.
검색 결과 Garmin에서 제공하는 Monkey C 확장이 나타났습니다.


여기서 한 가지 재미있었던 부분이 있습니다.
Monkey C라는 이름을 검색했더니 비슷한 이름의 확장 프로그램들이 상당히 많이 나왔습니다.
처음 시작하는 입장에서는 “이 중에서 어떤 것을 설치해야 하지?”라는 생각이 들 수 있습니다.
제가 사용한 것은 Garmin에서 제공하는 Monkey C Language Support 확장입니다.
설치가 완료되면 VS Code의 명령 팔레트에서 Monkey C 관련 명령을 사용할 수 있게 됩니다.
예를 들어 VS Code에서 Ctrl + Shift + P를 누르면 다음과 같은 명령들이 나타납니다.

- Monkey C: New Project
- Monkey C: Build for Device
- Monkey C: Build Current Project
- Monkey C: Verify Installation
- Monkey C: Open SDK Manager
- Monkey C: Configure Monkey Barrel
- Monkey C: Generate a Developer Key
처음 이 목록을 봤을 때는 생각보다 많은 기능이 있다는 느낌을 받았습니다.
하지만 첫 번째 목표는 아주 단순했습니다.
프로젝트 하나 만들고 실제 시계에 띄워보기.
Monkey C 설치 후 가장 먼저 확인한 것
확장 프로그램을 설치한 다음에는 개발환경이 정상적으로 연결되어 있는지 확인할 수 있습니다.
VS Code에서 Ctrl + Shift + P를 누르면 명령 팔레트를 열 수 있습니다.
여기에서 Monkey C: Verify Installation을 검색해서 실행하면 개발환경 설정을 확인할 수 있습니다.
처음 Garmin 개발을 시작한다면 이 단계는 건너뛰지 않는 것을 권합니다.
나중에 프로젝트를 만들고 빌드하는 단계에서 오류가 발생했을 때, SDK와 Monkey C 확장 자체가 정상적으로 연결되어 있는지 먼저 확인할 수 있기 때문입니다.
저 역시 기존에 설치했던 환경이 있었지만 이번에는 실제 과정을 다시 확인하면서 진행했습니다.
첫 번째 Garmin 워치페이스 프로젝트를 만들었다
이제 드디어 프로젝트를 만들 차례입니다.
VS Code에서 다시 Ctrl + Shift + P를 누르고 다음 명령을 찾았습니다.
Monkey C: New Project

이 명령을 실행하면 프로젝트 생성 과정이 시작됩니다.
프로젝트 이름을 입력하고, 어떤 종류의 Connect IQ 애플리케이션을 만들 것인지 선택합니다.
저는 이번 프로젝트를 워치페이스로 만들었기 때문에 Watch Face를 선택했습니다.
그리고 기본으로 제공되는 템플릿을 이용해 프로젝트를 생성했습니다.

프로젝트가 생성되고 나니 생각보다 구조가 단순했습니다.
처음 생성된 프로젝트에는 대략 다음과 같은 구조가 만들어집니다.
garmin_first_app/
├── bin/
├── resources/
├── source/
├── manifest.xml
└── monkey.jungle
처음에는 폴더가 몇 개 보이지 않을 수도 있지만, 각각 역할이 있습니다.
- source : Monkey C 소스 코드가 들어가는 곳
- resources : 이미지, 문자열 등 리소스를 관리하는 곳
- manifest.xml : 앱 종류, 지원 제품, API Level 등의 프로젝트 정보를 관리하는 파일
- bin : 빌드 과정에서 생성되는 결과물이 들어가는 곳
- monkey.jungle : 프로젝트 빌드 설정과 관련된 파일
처음에는 이 구조를 전부 이해할 필요는 없었습니다.
일단 “내가 만든 코드가 실제 Garmin 시계에서 실행되는 것”을 먼저 확인하는 것이 목표였습니다.
Minimum Supported API Level은 무엇을 선택할까?
프로젝트를 생성할 때 Minimum Supported API Level이라는 항목도 나옵니다.
처음 보면 조금 어렵게 느껴질 수 있습니다.
쉽게 말하면 애플리케이션이 요구하는 최소 Connect IQ API 수준이라고 생각하면 됩니다.
이 값이 높아질수록 해당 API를 지원하지 않는 오래된 기기는 프로젝트의 지원 대상에서 제외될 수 있습니다.
반대로 너무 낮게 설정한다고 해서 모든 최신 기능을 사용할 수 있는 것도 아닙니다.
사용하려는 API가 특정 버전 이상을 요구한다면 그에 맞춰 최소 API Level을 올려야 합니다.
이번 첫 번째 프로젝트에서는 특별히 최신 API 기능을 사용할 목적이 아니었기 때문에, 프로젝트 생성 과정에서 제공되는 기본 설정을 기준으로 시작했습니다.
중요한 것은 처음부터 무조건 가장 높은 API Level을 선택하는 것이 아니라 내가 만들 앱에서 실제로 필요한 API 수준을 기준으로 결정하는 것이라고 생각합니다.
저 같은 경우는 범용성을 위해서 3.2를 선택했습니다.
manifest.xml에서 프로젝트 설정을 확인했다
프로젝트를 만들고 나면 manifest.xml 파일을 확인할 수 있습니다.
이 파일은 Garmin Connect IQ 프로젝트에서 상당히 중요한 역할을 합니다.
앱의 이름이나 종류, 지원하는 제품, 최소 API Level, 권한 등의 정보를 관리하기 때문입니다.
제가 만든 프로젝트의 manifest를 열어보니 VS Code에서 단순한 XML 파일로만 보여주는 것이 아니라 편집 화면을 통해 여러 항목을 확인할 수 있었습니다.

여기에서 제가 확인했던 항목은 크게 다음과 같습니다.
- App Type
- Minimum Supported API Level
- App Name
- Entry Point
- Launcher Icon
- App UUID
- 지원 제품
- Permissions
처음부터 이 항목들을 전부 수정할 필요는 없었습니다.
프로젝트를 생성하면서 기본값이 상당 부분 자동으로 만들어졌기 때문입니다.
특히 눈에 띄었던 것은 App UUID였습니다.
새 프로젝트를 생성하면서 고유한 UUID가 하나 생성되어 있었습니다.
앞으로 앱을 개발하면서 이 식별자가 어떤 역할을 하는지도 조금씩 알아볼 생각입니다.
source 폴더에는 실제 Monkey C 코드가 들어간다
프로젝트 구조를 확인한 다음 source 폴더를 열어봤습니다.
여기에 Monkey C 파일이 생성되어 있었습니다.
파일 확장자는 .mc입니다.

기본으로 만들어진 코드를 열어보니 생각보다 익숙한 구조였습니다.
import Toybox.Graphics;
import Toybox.Lang;
import Toybox.System;
import Toybox.WatchUi;
class garmin_first_appView extends WatchUi.WatchFace {
function initialize() {
WatchFace.initialize();
}
function onLayout(dc as Dc) as Void {
setLayout(Rez.Layouts.WatchFace(dc));
}
function onShow() as Void {
}
function onUpdate(dc as Dc) as Void {
View.onUpdate(dc);
}
function onHide() as Void {
}
function onExitSleep() as Void {
}
function onEnterSleep() as Void {
}
}
처음부터 코드를 완전히 이해할 필요는 없었습니다.
오히려 저는 이 단계에서 코드를 조금씩 읽어보면서 “아, 이 파일이 실제 워치페이스 화면을 담당하는구나” 정도로 접근했습니다.
앞으로 이어지는 글에서는 이 코드가 실제로 어떤 역할을 하는지 하나씩 파헤쳐 볼 생각입니다.
일단 복잡한 기능은 넣지 않았다
여기서 욕심을 내면 프로젝트가 금방 복잡해집니다.
날씨를 넣고 싶고, 심박수를 넣고 싶고, 걸음 수를 넣고 싶고, 배터리도 표시하고 싶고, 예쁜 그래픽도 넣고 싶어집니다.
하지만 저는 일단 전부 내려놓았습니다.
이번 1편에서 확인하고 싶었던 것은 딱 하나였습니다.
“내가 만든 Monkey C 프로젝트가 실제 Garmin 시계에서 실행되는가?”
그래서 우선 기본 프로젝트를 그대로 빌드해서 시계에 넣어보기로 했습니다.
VS Code에서 Build for Device를 실행했다
이제 실제 기기에서 실행할 파일을 만들어야 합니다.
VS Code에서 Ctrl + Shift + P를 누르고 다음 명령을 찾았습니다.
Monkey C: Build for Device
이 기능을 이용하면 실제 Garmin 기기에서 사용할 수 있는 PRG 파일을 만들 수 있습니다.
처음에는 이 부분이 조금 헷갈렸습니다.
일반적인 웹 개발에서는 코드를 수정하고 브라우저를 새로고침하면 바로 결과를 확인할 수 있지만, Garmin 워치페이스는 실제 기기에 넣어 실행하는 과정이 필요하기 때문입니다.
Build for Device를 실행하면 어떤 제품을 대상으로 빌드할 것인지 선택하는 과정이 나타납니다.
여기에서 제가 사용할 Forerunner 265를 선택했습니다.

그리고 빌드 결과물을 저장할 폴더를 선택했습니다.
빌드가 정상적으로 끝나자 .prg 파일이 생성되었습니다.
제가 만든 프로젝트에서는 다음과 같은 파일이 만들어졌습니다.

garmin_first_app.prg
여기까지 오고 나니 조금 실감이 났습니다.
지금까지는 VS Code 안에서만 존재하던 프로젝트였는데, 이제 실제 Garmin 기기에 넣을 수 있는 파일이 만들어진 것입니다.
PRG 파일을 Garmin 시계에 직접 넣어보기
이제 가장 재미있는 단계가 남았습니다.
Garmin Forerunner 265를 USB 케이블로 컴퓨터에 연결했습니다.
Windows 파일 탐색기에서 시계의 내부 저장소를 열었습니다.
그리고 다음 경로로 들어갔습니다.
GARMIN
└── Apps
Garmin 공식 개발 문서에서도 실제 기기에 앱을 사이드로드할 때 빌드된 PRG 파일을 기기의 GARMIN/APPS 디렉터리에 복사하는 방법을 안내하고 있습니다.
저도 여기에서 방금 만든 garmin_first_app.prg 파일을 복사했습니다.

처음에는 저도 GARMIN/Apps/DATA 폴더에 넣는 것인지 잠깐 헷갈렸습니다.
하지만 실제 앱 파일인 PRG는 DATA 폴더가 아니라 GARMIN/Apps 바로 아래에 넣어야 했습니다.
제가 실제로 확인한 경로는 다음과 같습니다.
Forerunner 265
└── Internal Storage
└── GARMIN
└── Apps
└── garmin_first_app.prg
파일을 넣고 시계를 컴퓨터에서 분리했습니다.
정말 시계에 설치가 될까?
이제 조금 긴장됐습니다.
파일 하나를 복사했다고 해서 정말 시계에서 실행될지 궁금했습니다.
잠시 후 Garmin 시계 화면에 다음과 같은 메시지가 나타났습니다.
“Connect IQ 앱을 확인하는 중”

이 순간 조금 재미있었습니다.
VS Code에서 작성한 프로젝트가 실제 시계에서 인식되고 있다는 뜻이었기 때문입니다.
그리고 잠시 후 화면이 바뀌었습니다.
“garmin_first_app이(가) 장치에 설치되었습니다.”

드디어 첫 번째 고비를 넘었습니다.
아직 대단한 워치페이스를 만든 것은 아닙니다.
하지만 적어도 Connect IQ 개발환경에서 만든 프로젝트를 실제 Garmin Forerunner 265에 설치하는 것까지는 성공했습니다.
그리고 실제 시계 화면에서 실행됐다
마지막으로 앱을 실행했습니다.
그리고 화면에 시간이 표시되었습니다.
12:09

사진만 보면 너무 단순해 보일 수 있습니다.
그런데 개인적으로는 이 장면이 이번 과정에서 가장 의미 있었습니다.
처음에는 VS Code에 프로젝트 하나 만드는 것뿐이었습니다.
그런데 실제 과정은 다음과 같이 이어졌습니다.
- Connect IQ SDK 환경 확인
- SDK와 지원 기기 확인
- VS Code에 Garmin Monkey C 확장 설치
- Monkey C 개발환경 확인
- 새 Watch Face 프로젝트 생성
- manifest.xml과 프로젝트 구조 확인
- Monkey C 기본 코드 확인
- Build for Device 실행
- PRG 파일 생성
- Garmin 시계의 GARMIN/Apps 폴더에 PRG 복사
- 실제 Forerunner 265에서 앱 설치 확인
- 워치페이스 실행
결국 아주 단순한 화면이지만, 내가 작성한 코드가 실제 손목 위의 기기에서 실행되는 것까지 확인한 것입니다.
처음 해보니 생각보다 중요한 부분이 있었다
이번 작업을 하면서 느낀 것은 코드를 작성하는 것보다 처음 개발환경을 구성하는 과정에서 오히려 더 많은 질문이 생긴다는 것이었습니다.
SDK는 무엇을 설치해야 하는지, Devices에서는 무엇을 확인해야 하는지, VS Code에서는 어떤 확장을 설치해야 하는지, 프로젝트를 만들 때 어떤 앱 종류를 선택해야 하는지 하나씩 확인해야 했습니다.
특히 Garmin 개발을 처음 접하는 사람이라면 Connect IQ SDK, API Level, Monkey C, manifest.xml, 지원 제품, PRG 파일 같은 용어가 한꺼번에 등장하기 때문에 처음에는 상당히 복잡하게 느껴질 수 있습니다.
저 역시 기존에 여러 개발 경험이 있었지만 Garmin 개발환경은 처음 다시 구성하는 과정에서 하나씩 확인할 부분이 있었습니다.
그래서 이번 연작에서는 단순히 완성된 코드만 보여주기보다 제가 실제로 처음부터 따라가면서 확인한 과정을 그대로 남겨보려고 합니다.
이번 글에서 여기까지만 한 이유
사실 여기에서 바로 복잡한 기능을 넣을 수도 있습니다.
하지만 그렇게 하면 처음 시작하는 사람이 따라오기 어려워집니다.
그래서 이번 글에서는 일부러 아주 단순한 단계에서 멈췄습니다.
개발환경을 만들고, 프로젝트를 생성하고, 실제 기기에서 실행하는 것.
이것만 성공하면 다음부터는 훨씬 재미있어집니다.
이제 실제 화면을 수정하고, 시간 표시를 바꾸고, 글꼴과 색상을 바꾸고, 배터리나 걸음 수 같은 데이터를 추가하면서 하나씩 워치페이스를 만들어 볼 수 있기 때문입니다.
무엇보다 처음 만든 프로그램이 실제 시계에서 실행되는 것을 한 번 경험하고 나니, 그다음 단계가 훨씬 궁금해졌습니다.
다음 편에서는 무엇을 만들어볼까?
다음 글에서는 이번에 생성한 프로젝트의 코드를 조금 더 자세히 살펴볼 예정입니다.
특히 Monkey C의 기본 구조와 WatchFace 클래스가 어떤 역할을 하는지부터 하나씩 확인해 보려고 합니다.
현재 화면에는 단순하게 시간이 표시되고 있지만, 이 부분을 직접 수정하면 내가 원하는 디자인의 워치페이스로 발전시킬 수 있습니다.
처음부터 완성품을 만드는 것보다 작은 기능 하나씩 추가해 가면서 어디까지 만들 수 있는지 직접 확인해 보는 방식으로 진행해 보려고 합니다.
저 역시 처음부터 모든 것을 알고 시작한 것이 아니기 때문에, 앞으로 진행하면서 막히는 부분과 해결한 과정까지 함께 기록해 보겠습니다.
마무리
이번에는 Garmin Connect IQ 개발환경을 준비하고 첫 번째 Watch Face 프로젝트를 만들어 실제 Forerunner 265에서 실행해 봤습니다.
처음에는 단순히 “Garmin 워치페이스를 직접 만들어볼 수 있을까?”라는 궁금증에서 시작했습니다.
그런데 실제로 해보니 SDK를 준비하고, 개발환경을 구성하고, 프로젝트를 만들고, 빌드하고, PRG 파일을 시계에 넣는 과정까지 하나의 개발 과정으로 연결되어 있었습니다.
그리고 마지막에 실제 시계 화면에서 제가 만든 프로젝트가 실행되는 것을 확인하니 다음 단계가 궁금해졌습니다.
이번 글에서는 단순한 기본 화면까지만 만들었지만, 앞으로는 이 프로젝트를 조금씩 수정해 보려고 합니다.
Garmin 워치페이스를 처음 만들어보는 분이라면 다음 글부터는 실제 코드를 하나씩 따라 해보셔도 좋겠습니다.
저도 개발하면서 직접 확인한 내용을 기준으로 계속 기록해 보겠습니다.