설치 · 빌드 · 개발자 정보

준비물

갤럭시 워치4 이상 — 실기기여야 합니다. 에뮬레이터로는 심박이 안 잡힙니다.
안드로이드 폰 — 워치와 블루투스로 페어링된 상태.
macOS + Android Studio(Koala 이상).
JDK 17+. 번들 JBR(JDK 21)을 씁니다. 시스템 java가 JDK 8이면 빌드가 깨집니다.
삼성 헬스 센서 SDK .aar 하나(아래 2단계). 비공개 레포엔 이미 들어 있습니다.

API 키·서버·로그인 설정은 없습니다. 지도 타일도 키가 필요 없습니다.

1. 소스 받기

비공개 레포입니다. 접근 권한이 있는 계정으로 인증합니다.

# HTTPS
git clone https://github.com/atelainc/kict-hr-sensor.git
cd kict-hr-sensor

# SSH
git clone git@github.com:atelainc/kict-hr-sensor.git
cd kict-hr-sensor

Android Studio로 루트 폴더를 엽니다(Open). Gradle Sync는 알아서 돌아갑니다. local.properties의 sdk.dir은 Studio가 만들어 줍니다. CLI만 씁니다면 ANDROID_HOME을 잡아 둡니다.

2. 삼성 센서 SDK(.aar) 넣기

심박 수집엔 Samsung Health Sensor SDK v1.4.1 파일 하나가 필요합니다. 공개 배포가 막힌 proprietary SDK라, 경로·파일명을 그대로 맞춰야 :wear가 컴파일됩니다.

wear/libs/samsung-health-sensor-api-1.4.1.aar

빌드 스크립트가 fileTree("libs") { include("*.aar") }로 링크합니다. 비공개 레포엔 이미 커밋돼 있어 클론만 하면 보통 바로 빌드됩니다. 버전을 바꿀 때만 이 파일을 덮어씁니다.

공개로 전환할 때

proprietary SDK라 레포를 공개로 돌리면 .aar를 git 추적에서 빼야 합니다. :wear는 이 파일 없이는 컴파일되지 않고(정상), Samsung SDK를 참조하는 파일은 HeartRateSensorManager.kt 하나뿐입니다.

3. 워치 개발자 모드 (두 가지)

용도가 다른 개발자 모드가 둘 있고, 둘 다 켜야 합니다.

3-A. Health Platform 개발자 모드 — 1초 측정

1초 간격으로 찍으려면 이걸 켜야 합니다.

워치 → 설정 → 앱 → Health Platform.
정보 화면 맨 위 “Health Platform” 제목을 빠르게 10번쯤 탭합니다.
제목 옆/아래에 [Dev mode]가 뜨면 성공.

버전 숫자 말고 ‘제목’을 탭

버전 숫자가 아니라 “Health Platform” 제목을 연타하는 게 공식 방법입니다. 안 되면 탭을 더 빠르게 하거나 워치를 재부팅하고 다시 합니다. 메뉴 위치는 One UI 버전마다 조금씩 다릅니다.

3-B. Wear OS 개발자 옵션 + 무선 디버깅 — 앱 설치

워치엔 USB 포트가 없어 adb 무선 디버깅으로 설치합니다. Wi-Fi가 있어야 합니다.

워치에서:

설정 → 워치 정보 → 소프트웨어 정보.
소프트웨어 버전을 7번 연타 → “개발자 모드” 토스트.
뒤로 나가면 설정 → 개발자 옵션이 생깁니다.
거기서 ADB 디버깅과 무선 디버깅을 둘 다 켭니다.
무선 디버깅 화면에 IP·포트가 뜹니다 (예: 192.168.0.91:40763).

PC에서 — Wear OS 3+ / Watch4+ 는 처음 한 번 페어링이 필요합니다.

# 1) PC를 워치와 같은 Wi-Fi에 둡니다

# 2) (최초 1회) 페어링 — 무선 디버깅의 "새 기기로 페어링"을 열면
#    페어링 전용 IP·포트 + 6자리 코드가 나옵니다 (연결 포트와 다름!)
adb pair 192.168.0.91:<페어링포트>
#    → 6자리 코드 입력

# 3) 연결 — 무선 디버깅 메인 화면의 연결 포트로
adb connect 192.168.0.91:40763
#    → 워치 허용 팝업에서 허용

# 4) 확인
adb devices
#    192.168.0.91:40763   device   면 성공

페어링 포트 ≠ 연결 포트

adb pair의 포트와 adb connect의 포트는 다릅니다. 무선 디버깅을 껐다 켜면 포트가 바뀌니, 그때마다 새 포트로 다시 연결합니다.

4. 빌드

Studio에선 :wear를 워치에, :mobile을 폰에 각각 Run 합니다. 명령줄로는:

# 디버그 APK 두 개
./gradlew :mobile:assembleDebug :wear:assembleDebug

# 린트
./gradlew lint

산출물:

mobile/build/outputs/apk/debug/   # 폰
wear/build/outputs/apk/debug/     # 워치

검증된 빌드

Android SDK platform-34 / build-tools 34.0.0에서 :mobile:assembleDebug, :wear:assembleDebug 둘 다 APK까지 나오는 걸 확인했습니다. :wear는 .aar가 있을 때만 됩니다. SDK 사용 범위는 1.4.1 .aar에 javap로 대조했습니다.

5. 폰에 설치

둘 중 편한 쪽으로.

파일로 직접 (PC 없이)

폰용 APK를 폰으로 옮깁니다(USB·카톡·드라이브·메일 등).
내 파일에서 APK를 탭합니다.
“출처를 알 수 없는 앱”을 물으면 허용 → 설치.

PC에서 adb

먼저 폰 개발자 모드 + USB 디버깅을 켭니다.

설정 → 휴대폰 정보 → 소프트웨어 정보 → 빌드번호 7번 연타.
설정 → 개발자 옵션 → USB 디버깅 켜기.
USB 연결 시 팝업에서 “이 컴퓨터에서 항상 허용” 체크 후 허용.

adb devices                          # 폰이 device 로 보이는지
adb install atela-hr-mobile-v0.2.0.apk

6. 워치에 설치

3-B에서 연결을 마친 상태에서 합니다. 폰·워치가 같이 붙어 있을 수 있으니 -s로 대상을 지정합니다.

adb devices                          # 192.168.0.91:40763  device 확인
adb -s 192.168.0.91:40763 install atela-hr-wear-v0.2.0.apk

디버그 서명 APK라 별도 설정 없이 깔립니다.

7. 첫 실행

처음 열면 권한 창이 뜹니다. 심박 센서·신체 활동·알림을 모두 허용합니다. 거부하면 측정이 시작되지 않습니다. 권한 목록은 K. 기여 가이드 §권한에 있습니다.

트러블슈팅

증상	원인 · 해결
워치 앱이 빌드/설치 안 됨	`wear/libs/samsung-health-sensor-api-1.4.1.aar`가 있는지 봅니다. 없으면 `:wear`는 컴파일 자체가 안 됩니다.
USB 디버깅이 회색 + “보안 위협 자동 차단에서 차단함”	삼성 자동 차단(Auto Blocker)입니다. 설정 → 보안 및 개인정보 보호 → 자동 차단 → 끄기. 작업 끝나면 다시 켭니다.
`adb connect` 실패 / 기기 안 보임	PC·워치가 같은 Wi-Fi인지, 무선 디버깅 재시작으로 포트가 바뀌지 않았는지 봅니다. 처음엔 `adb pair`부터.
Gradle 빌드 실패(JDK)	시스템 `java`가 JDK 8일 수 있습니다. 번들 JBR을 씁니다: `/Applications/Android Studio.app/Contents/jbr/Contents/Home`.
Start 눌러도 측정 안 됨	① 권한을 다 허용했는지 ② Health Platform 개발자 모드(3-A)가 켜졌는지.
폰에 데이터 안 보임	워치-폰 블루투스 연결을 봅니다. 늦으면 잠시 뒤 뜹니다(워치엔 이미 저장됨, 재연결 시 동기화).

빌드 없이 쓰고 싶으면 사용 설명서 A. 시작하기의 Play 비공개 테스트 또는 배포 APK가 더 빠릅니다. 이 페이지는 소스에서 직접 빌드·수정하는 경우입니다.