Skip to content

CLAUDE.md

Latest commit

 

History

History
79 lines (55 loc) · 2.92 KB

CLAUDE.md

File metadata and controls

79 lines (55 loc) · 2.92 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is gexporter, an Android companion app that serves GPX/FIT files to Garmin devices via HTTP. It works with the gimporter Garmin ConnectIQ app in the parent directory's gimporter/ folder.

Build Commands

./gradlew build              # Build the app
./gradlew test               # Run unit tests
./gradlew assembleDebug      # Build debug APK
./gradlew assembleRelease    # Build release APK

# Run a single test class
./gradlew test --tests "org.surfsite.gexporter.TestPlay"

# Run a single test method
./gradlew test --tests "org.surfsite.gexporter.TestPlay.test10"

Local Development Server

Run TestRunServer.main() to start a standalone HTTP server on localhost:22222 that serves files from ~/Downloads/. Use this with the ConnectIQ simulator for development.

Architecture

HTTP Server (WebServer.java)

NanoHTTPD-based server on port 22222 with endpoints:

  • GET /dir.json - JSON list of available tracks with query params:
    • ?type=GPX - only return GPX files
    • ?short=1 - return relative URLs instead of full URLs
    • ?longname=1 - preserve full filename (otherwise truncated to 15 chars)
  • GET /{filename} - Download file; GPX files are converted to FIT on-the-fly unless ?type=GPX

GPX to FIT Conversion (Gpx2Fit.java)

Parses GPX 1.0/1.1 files and converts to Garmin FIT course format:

  • Extracts <trk>, <rte>, and <wpt> elements
  • Applies grade-adjusted pace using Minetti walking energy cost model
  • Writes FIT messages: FileId, Course, Lap, Event, Record, CoursePoint

Conversion Options (Gpx2FitOptions.java)

  • speed - Default pace in m/s
  • forceSpeed - Override timestamps with calculated speed
  • use3dDistance - Include elevation in distance calculations
  • walkingGrade - Apply grade-adjusted pace
  • injectCoursePoints - Add course points along the track
  • maxPoints - Limit number of route points (for device compatibility)
  • minRoutePointDistance / minCoursePointDistance - Point density control

ConnectIQ Integration (MainActivity.java)

Communicates with Garmin devices via ConnectIQ SDK:

  • App ID: 9B0A09CF-C89E-4F7C-A5E4-AB21400EE424
  • Widget ID: B5FD4C5F-E0F8-48E8-8A03-E37E86971CEB
  • Responds to GET_PORT messages to tell the device which port to connect to

Testing

  • TestPlay.java: GPX parsing and FIT conversion tests using sample files in src/test/resources/
  • TestRunServer.java: Standalone development server (not a test, despite the name)

Key Dependencies

  • NanoHTTPD 2.3.1: HTTP server
  • Garmin FIT SDK 21.176.0: FIT file format
  • Garmin ConnectIQ Companion SDK 2.2.0: Device communication
  • geodesy 1.1.3: GPS distance calculations

Environment

  • Java 11 source/target compatibility
  • Android SDK 36 (min SDK 21)
  • Nix flake available for reproducible environment (nix develop)