microPebble

A small scrappy open source Pebble companion app, based on the libpebble3. It's not meant as a grand replacement for the original app, but as a small app with the functional UI and the features that I care about.

This is a Kotlin Multiplatform (KMP) project supporting both Android and iOS.

Supported features:

• Connecting to the LE watches
• Installing / uninstalling watch apps via PBW
• PebbleKit JS (including configuration pages)
• Basic notification config
• Music control
• Calendar sync
• PebbleKit Android (for Notification Center, Music Boss etc.), albeit it's slower on the Pre-P2 watches
• Developer connection
• Voice recognition (on Android 13+)
• Calendar filtering

---

Getting Started

Prerequisites

• macOS (required for iOS development)
• Xcode 16.2+ (for iOS)
• Android Studio (for Android and JDK 21)

Step 1: Clone the Repository

git clone <repository-url>
cd rebble_kmp_poc

Step 2: Initialize Submodules

The project has multiple submodules (including nested ones) that must be initialized:

# Initialize all submodules
git submodule update --init --recursive

# Initialize nested submodules in libpebble3
cd libs/libpebble3
git submodule update --init --recursive
cd ../..

# Initialize speex codec source
cd libs/kotlin-speex
git submodule update --init --recursive
cd ../..

Step 3: Configure JDK 21

The project requires JDK 21. The easiest way is to use Android Studio's bundled JDK.

Update gradle.properties:

# Configure Gradle to use Java 21 (Android Studio bundled JDK)
org.gradle.java.home=/Applications/Android Studio.app/Contents/jbr/Contents/Home

Step 4: Configure Android SDK

Create local.properties in the following directories with your Android SDK path:

Root project (local.properties):

sdk.dir=/Users/<your-username>/Library/Android/sdk

Also create the same file in:

• libs/libpebble3/local.properties
• libs/kotlin-speex/local.properties
• libs/libpebble3/PebbleKitAndroid2/local.properties

---

Building for Android

# Build debug APK
./gradlew :app:assembleDebug

# Install on connected device
./gradlew :app:installDebug

The APK will be at: app/build/outputs/apk/debug/micropebble-debug.apk

---

Building for iOS

Step 1: Build the Shared Framework

# For real device (arm64)
./gradlew :shared:linkDebugFrameworkIosArm64

# For simulator (Apple Silicon)
./gradlew :shared:linkDebugFrameworkIosSimulatorArm64

Step 2: Update Xcode Build Script (First Time Only)

The Xcode project has a build script that needs the correct JAVA_HOME.

In iosApp/iosApp.xcodeproj/project.pbxproj, find the shellScript section and ensure JAVA_HOME is set correctly:

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

Step 3: Build via Command Line

cd iosApp

# Build for real device (arm64)
xcodebuild -project iosApp.xcodeproj \
  -target iosApp \
  -configuration Debug \
  -sdk iphoneos \
  -arch arm64 \
  CODE_SIGN_IDENTITY="" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO

The app will be built at: iosApp/build/Debug-iphoneos/iosApp.app

Step 4: Run on Device via Xcode

1. Open iosApp/iosApp.xcodeproj in Xcode
2. Connect your iPhone via USB
3. Select your device in the top toolbar
4. Go to Signing & Capabilities and configure your Apple Developer Team
5. Click Run (⌘R)

Note: First time running on a device, you may need to trust the developer certificate in Settings > General > VPN & Device Management on your iPhone.

---

Troubleshooting

"JAVA_HOME is set to an invalid directory"

Update gradle.properties and the Xcode build script to point to a valid JDK 21 installation.

"SDK location not found"

Create local.properties files in all project directories (see Step 4 in Getting Started).

AGP Version Mismatch

If you see Android Gradle Plugin version conflicts, update libs/kotlin-speex/gradle/libs.versions.toml:

[versions]
agp = "8.13.0"  # Match the main project's version

Missing Speex Source Files (CMake errors)

cd libs/kotlin-speex
git submodule update --init --recursive

iOS Type Mismatch (LibPebbleSwift.CLLocation)

This is a type conflict in libpebble3 - cast LibPebbleSwift.CLLocation to platform.CoreLocation.CLLocation.

---

Project Structure

rebble_kmp_poc/
├── app/                       # Android app module
├── shared/                    # KMP shared module (iOS + Android)
├── iosApp/                    # iOS app (Xcode project)
├── libs/
│   ├── libpebble3/           # Core Pebble library (submodule)
│   │   └── PebbleKitAndroid2/ # PebbleKit (nested submodule)
│   └── kotlin-speex/         # Speex codec (submodule)
├── gradle.properties         # JDK configuration
└── local.properties          # Android SDK path (create this)

---

Contributing

Updating versions

Process for updating all library versions:

1. Update Gradle version
   1. Find latest version and the checksum for -all version from https://gradle.org/release-checksums/ (We use SHA to secure against wrapper attack, see https://blog.gradle.org/wrapper-attack-report)
   2. Run ./gradlew wrapper --gradle-version VERSION --gradle-distribution-sha256-sum SHA, where you substitute VERSION and SHA with the info found in the previous step.
2. Open libs.toml file and check if any versions marked with @pin have been unblocked and can now be updated
3. Run ./gradlew versionCatalogUpdate.
4. Sync the project, build the app and run all tests to make sure everything still works.
5. Run detektDebug gradle task to find any new deprecated code
6. For any new deprecated code found by the search:
   • If the fix is trivial, fix it immediately as part of the update commit
   • Otherwise, make a tech debt ticket and add a @Suppress with the ticket number (and/or discuss with the team how to address it)

Creating a new module

To easily add new modules, first enable project templates (you only need to do this once). Open Android Studio's Settings, go to "File and Code Templates" and set Scheme to "Project".

Then, to create a new module:

1. Right click on the root in the project window, select New and then the project type you want
2. Add module to settings.gradle.kts
3. Add module to app's build.gradle.kts as implementation(projects.newModule))
4. Remove leading space from all generated .gitignore files (workaround for the https://youtrack.jetbrains.com/issue/IJPL-2568)

Hierarchy of the feature modules

Every feature should contain following modules:

• feature-name
  • data - data module with all non-UI logic (such as repositories). No other data or ui module should depend on this (except for tests).
  • api - interfaces and data models exposed to other modules. This module should generally contain no logic to speed up builds.
  • ui - Module containing feature's ui (Screens / Fragments / ViewModels). No other data or ui module should depend on this (except for tests).
  • test (optional) - Module containing test helpers for faking stuff exposed in the api module

If your module contains instrumented tests, you must enable them with the following call:

custom {
   enableEmulatorTests.set(true)
}

---

Attribution

App icon is watch-variant by the GreenTurtwig.