Meshtastic-Android/specs/005-tak-v2-protocol/quickstart.md

Quickstart: TAK v2 Protocol Integration

Prerequisites

• JDK 21
• Android Studio (latest stable)
• ANDROID_HOME environment variable set
• Git submodule initialized: git submodule update --init
• local.properties exists: cp secrets.defaults.properties local.properties

Build & Test

# Full verification
./gradlew spotlessApply spotlessCheck detekt assembleDebug :core:takserver:allTests :feature:settings:allTests

# TAK module tests only
./gradlew :core:takserver:allTests

# Quick compile check (no tests)
./gradlew :core:takserver:compileKotlinJvm

Module Overview

The TAK v2 implementation lives primarily in core/takserver/:

Layer	Location	Purpose
Business Logic	core/takserver/src/commonMain/	All conversion, compression, parsing, server management
Platform (JVM)	core/takserver/src/jvmAndroidMain/	TLS server, zstd compression, cert loading
Platform (Android)	core/takserver/src/androidMain/	File writer (SAF)
Platform (iOS)	core/takserver/src/iosMain/	Stubs (uncompressed mode)
UI	feature/settings/.../TAKConfigItemList.kt	Config screen
Wake Lock	core/service/.../MeshService.kt	CPU keepalive
Version Gate	core/model/.../Capabilities.kt	supportsTakV2 flag

Key Entry Points

Starting the TAK Server

The TAK server is started via TAKMeshIntegration.start(scope) which is called from MeshService when a device connects. The lifecycle:

1. MeshService.onStartCommand() → acquires wake lock
2. TAKMeshIntegration.start(scope) → wires up three collection jobs:
   • Inbound: TAK client → mesh
   • Outbound: mesh → TAK clients
   • Config: team/role sync
3. TAKServerManager.start(scope) → starts TLS listener on port 8089

Adding a New CoT Type

1. Add enum value to TakV2TypeMapper bidirectional map
2. Add test fixture XML in src/jvmAndroidMain/resources/tak_test_fixtures/
3. Verify round-trip in TAKPacketV2RawDetailTest or CoTConversionTest
4. Run: ./gradlew :core:takserver:allTests

Testing with ATAK

1. Enable TAK server in Settings → Module Configuration → TAK
2. Tap "Export Data Package" → share to ATAK
3. In ATAK: Settings → Network → TAK Servers → Import
4. Verify connection count shows 1 in Meshtastic UI

Architecture Flow

ATAK Client ──TLS──▶ TAKServer (port 8089)
                         │
                         ▼
                  TAKServerManager
                         │
                         ▼ inboundMessages
                  TAKMeshIntegration
                    │            │
          ┌─────────┘            └──────────┐
          ▼                                 ▼
   sendCoTToMeshV2()              sendCoTToMeshV1()
   (fw ≥ 2.8.0)                  (fw < 2.8.0)
          │                                 │
          ▼                                 ▼
   TakV2Compressor                 TAKPacketConversion
   (zstd + dict)                   (raw protobuf)
          │                                 │
          ▼                                 ▼
   Port 78 (ATAK_PLUGIN_V2)       Port 72 (ATAK_PLUGIN)
          │                                 │
          └────────────┬────────────────────┘
                       ▼
                  Mesh Network (LoRa)

Test Fixtures

38 XML fixture files in src/jvmAndroidMain/resources/tak_test_fixtures/ covering:

• PLI: 6 variants (basic, full, itak, stationary, takaware, webtak)
• GeoChat: 3 variants (broadcast, DM, simple)
• Markers: 6 variants (2525, goto, goto-itak, icon-set, spot, tank)
• Drawings: 7 variants (circle, ellipse, freeform, polygon, rectangle, rectangle-itak, telestration)
• Routes: 2 variants (3wp, itak-3wp)
• Aircraft: 2 variants (ADSB, hostile)
• Ranging: 3 variants (bullseye, circle, line)
• Others: casevac (2), emergency (2), alert (1), delete (1), chat-receipt (2), task (1), waypoint (1)

Dependency Graph

core:takserver
├── core:repository (mesh packet access)
├── core:common (dispatchers, utilities)
├── core:di (Koin module registration)
├── core:model (Capabilities, domain models)
├── core:proto (protobuf definitions)
├── xmlutil (XML parsing/serialization)
├── TAKPacket-SDK v0.1.3 (zstd compression, JVM only)
├── zstd-jni 1.5.7-7 (native zstd, platform-specific)
├── okio (I/O)
├── ktor-network (TCP)
├── kotlinx-datetime
└── kermit (logging)