TAKPacket-SDK

0.7.0indexed

Converts Cursor-on-Target XML into TAKPacketV2 protobufs, compresses with zstd using dual dictionaries for LoRa, sanitizes mesh XML, and encodes compact structured payloads with delta geometry.

JSJVMNativeWasm·meshtastic/TAKPacket-SDK

Stars

—

Used by

dependents

Health

/ 100

TAKPacket-SDK

Shared libraries for converting ATAK Cursor-on-Target (CoT) XML to Meshtastic's TAKPacketV2 protobuf format and compressing it for LoRa transport using zstd dictionary compression.

This SDK is the single source of truth for CoT conversion and compression across all Meshtastic client platforms. Each language implementation produces interoperable compressed payloads, validated by 47 shared test fixtures and 1,000+ cross-platform tests.

Documentation

📚 Browse the full API reference at meshtastic.github.io/TAKPacket-SDK — generated per language from the in-source doc comments (Dokka, DocC, TypeDoc, pdoc, DocFX).

For the wire contract see WIRE_FORMAT.md; to build, test, and release see CONTRIBUTING.md.

Architecture

flowchart TD
    subgraph send ["Sending App"]
        A["CoT XML<br/>(~400-2300 B)"]
        B["TAKPacketV2<br/>Protobuf"]
        C["Wire Payload<br/>(median 87B,<br/>max 184B)"]
        A -->|"CotMeshSanitizer<br/>→ CotXmlParser"| B
        B -->|TakCompressor| C
    end
    C -->|"LoRa / Meshtastic<br/>(≤237 B MTU)"| D
    subgraph recv ["Receiving App"]
        D["Wire Payload"]
        E["TAKPacketV2<br/>Protobuf"]
        F["CoT XML"]
        D -->|TakCompressor| E
        E -->|CotXmlBuilder| F
    end

How It Works

1. CoT XML Parsing

CotXmlParser extracts structured fields from a CoT XML event and maps them into a TAKPacketV2 protobuf message. The parser recognizes all major CoT categories and decomposes each into a strongly-typed payload_variant case:

2. Compression Pipeline

flowchart TD
    A[TAKPacketV2 protobuf bytes] --> B{Classify CoT type}
    B -->|"Air domain\n(3rd atom = 'A')"| C["Aircraft dictionary\n(4KB) — dict ID 0x01"]
    B -->|"Ground / chat / shapes /\nmarkers / routes / alerts"| D["Non-aircraft dictionary\n(512KB) — dict ID 0x00"]
    C --> E["zstd compress with dictionary\n(dictID / contentSize / checksum off)"]
    D --> E
    E --> S["Strip 4-byte zstd magic\n(re-prepended on decode)"]
    S --> H{"Raw proto ≤\ncompressed body?"}
    H -->|"yes (tiny packet)"| I["Emit 0xFF flags\n+ raw protobuf"]
    H -->|no| F["Prepend 1-byte flags\n(dict ID in bits 0-5)"]
    I --> G["Wire payload"]
    F --> G

Two pre-trained zstd dictionaries are used because aircraft and non-aircraft CoT messages have fundamentally different structural patterns. Using the wrong dictionary degrades compression past the LoRa MTU on the worst-case fixtures. The classification result is encoded into the flags byte on the wire so the receiver knows which dictionary to use for decompression — see Wire Format below. On the bundled test set the pipeline achieves:

See testdata/compression-report.md for the per-fixture breakdown, regenerated on every Kotlin test run.

3. Wire Format

The sender's dictionary selection (step 2 above) is encoded into the flags byte so the receiver can pick the matching dictionary for decompression without re-parsing the CoT type:

The compressed body carries no zstd magic number: the encoder compresses each frame with dictID / contentSize / checksum disabled and then strips the 4-byte zstd magic (28 B5 2F FD), re-prepending it on decode. This is done uniformly in all five language bindings and saves ~8 bytes per packet. See WIRE_FORMAT.md for the full specification including error handling requirements and annotated examples.

4. CoT XML Reconstruction

CotXmlBuilder reconstructs a standards-compliant CoT XML event from a TAKPacketV2 protobuf, preserving every structured field extracted during parsing — including geometry vertices, stroke/fill colors, marker iconsets, and route waypoints.

Mesh Hygiene (`CotMeshSanitizer`)

ATAK and its plugins emit CoT XML that carries display-only <detail> children (map-rendering hints, geofences, archive flags, creator metadata, stroke styling, …) and is often pretty-printed with an <?xml?> prologue. None of that is needed by a receiver, and every byte competes for the 237-byte LoRa MTU. CotMeshSanitizer is the SDK's shared, golden-tested pre-processing pass that consumers run on raw CoT XML before handing it to CotXmlParser:

Both are pure string transforms with no protobuf, compression, or platform dependencies. In Kotlin the object lives in commonMain, so KMP consumers (e.g. Meshtastic-Android's core:takserver) can call it from their own commonMain and reuse it on iOS. These rules previously lived as ad-hoc regex lists duplicated inside Meshtastic-Android and Meshtastic-Apple — they drifted and silently broke features (most recently TAK-Talk voice/marti stopped surfacing end-to-end). Centralizing them here, with byte-for-byte cross-binding fixtures under testdata/sanitizer/, keeps every consumer in lockstep. Regexes use (not the DOTALL flag) for identical behavior across all five bindings.

Structured Payload Types

TAKPacketV2.payload_variant is a proto oneof with twelve strongly-typed cases (tags 31–42) rather than a single opaque bytes field — plus an implicit thirteenth: a packet with no payload_variant set is a PLI position report (the old bool pli arm at tag 30 was removed because the boolean was pure overhead on the highest-frequency packet; tag 30 is now reserved). Decomposing the <detail> element into structured messages gives three concrete benefits:

Tighter compression — repeated field names collapse to varint tags. A circle that takes 933B of XML fits in 72B on the wire (13.0× ratio); a full 9-line MEDEVAC goes from 1045B of XML to 160B (6.5× ratio).
Schema evolution — adding a field to DrawnShape doesn't break older receivers, they just see an unknown varint and skip it.
Parse-side validation — geometry is a structured object, not a regex over XML text.

Every geometry variant delta-encodes vertices as sint32 offsets from the event anchor so a 32-vertex telestration clustered inside 100m encodes in ~60 bytes of vertex data instead of ~320 bytes with absolute coordinates. stores its vertices as two packed columns ( / ); single-endpoint geometry (, ) uses a delta sub-message. Color fields use a two-field encoding: a palette enum for the 14 ATAK-standard colors (2 bytes on the wire) plus a fallback for custom user-picked colors (5 bytes). Round-trip is byte-exact — custom colors are never quantized to the nearest palette entry.

DrawnShape

Covers ten tactical graphic kinds. The shape's anchor point lives on TAKPacketV2.latitude_i/longitude_i; geometry vertices are stored as two packed repeated sint32 columns (vertex_lat_deltas / vertex_lon_deltas), zigzag deltas from that anchor.

StyleMode discriminates StrokeOnly vs FillOnly vs StrokeAndFill, preserving the distinction between "this polyline has no fill" and "this shape has a transparent black fill".

KML Style Links: Circle and ellipse shapes include a <link type="b-x-KmlStyle"> element inside <shape> for iTAK compatibility. ATAK encodes colors in KML's ABGR hex format (not ARGB). The builder converts stroke_argb/fill_argb proto fields (ARGB int32) to ABGR hex strings automatically:

Kotlin — parse a drawing_circle and read its structured fields:

val parser = CotXmlParser()
val packet = parser.parse(drawingCircleXml)
val shape = packet.payload as TakPacketV2Data.Payload.DrawnShape

println("Kind: ${shape.kind}")                              // 1 = Circle
println("Radius: ${shape.majorCm / 100.0} meters")          
println(.format(shape.strokeArgb))      
println()                            
println()

Swift — extract a polygon's vertices:

Marker

Fixed markers with a Kind enum covering the common ATAK categories plus the mission-point set that ATAK CIV added in 4.x (GoTo / Initial Point / Contact Point / Observation Post) and standalone image markers. iconset holds the full iconset path verbatim (no prefix stripping) — round-trip works for COT_MAPPING_SPOTMAP/…, COT_MAPPING_2525B/…, and custom UUID/group/icon.png paths.

Python — classify a marker by kind:

packet = parser.parse(marker_2525_xml)
if packet.HasField("marker"):
    marker = packet.marker
    print(f"Kind: {marker.kind}")              # 5 = Symbol2525
    print(f"Iconset: {marker.iconset}")        # "COT_MAPPING_2525B/a-u/a-u-G"
    print(f"Parent UID: {marker.parent_uid}")
    print(f"Readiness: ")

RangeAndBearing

Single-leg range-and-bearing line. The anchor endpoint is a CotGeoPoint delta-encoded from the event point, so an anchor identical to the event (common for self-anchored RAB) encodes in zero bytes.

TypeScript — extract range, bearing, and reconstruct the anchor:

Route

Ordered waypoint sequence with travel method and direction. Link count caps at 16 — longer routes are truncated and the truncated flag is set.

C# — iterate a route's waypoints:

var packet = parser.Parse(route3wpXml);
if (packet.PayloadVariantCase == TAKPacketV2.PayloadVariantOneofCase.Route)
{
    var route = packet.Route;
    Console.WriteLine();
     ( link  route.Links)
    {
         lat = (packet.LatitudeI + link.Point.LatDeltaI) / ;
         lon = (packet.LongitudeI + link.Point.LonDeltaI) / ;
         kind = link.LinkType ==  ?  : ;
        Console.WriteLine();
    }
}

CasevacReport

9-line MEDEVAC request for CoT type b-r-f-h-c. Mirrors ATAK's MedLine <_medevac_> detail element: precedence, equipment flags bitfield, patient counts, HLZ marking method, zone marker, security at PZ, nationality counts, terrain obstacles bitfield, and comms frequency. Every field is optional so senders omit lines they don't have. The envelope carries Line 1 (location) and Line 2 (callsign).

Bitfield	Bit layout
`equipment_flags`	0=none, 1=hoist, 2=extraction, 3=ventilator, 4=blood
`terrain_flags`	0=slope, 1=rough, 2=loose, 3=trees, 4=wires, 5=other

A bare CASEVAC compresses to ~134B and a full 9-line MEDEVAC to ~160B — well under the 237B LoRa MTU even with all 9 lines populated.

Kotlin — build a CASEVAC request:

val packet = TakPacketV2Data(
    cotTypeId = CotTypeMapper.typeToEnum("b-r-f-h-c"),
    how = CotTypeMapper.howToEnum("h-g-i-g-o"),
    callsign = "MEDEVAC-1",
    uid = "medevac-01",
    latitudeI = ( * ).roundToInt(),
    longitudeI = ( * ).roundToInt(),
    payload = TakPacketV2Data.Payload.CasevacReport(
        precedence = CotXmlParser.PRECEDENCE_URGENT,
        litterPatients = ,
        ambulatoryPatients = ,
        equipmentFlags =  or ,       
        security = CotXmlParser.SECURITY_POSSIBLE_ENEMY,
        hlzMarking = CotXmlParser.HLZ_MARKING_SMOKE,
        zoneMarker = ,
        frequency = ,
    ),
)
 wire = TakCompressor().compress(packet)

EmergencyAlert

Small, high-priority structured record for emergency CoT types (b-a-o-*, b-a-g). The CoT type string is still set on cot_type_id so receivers that don't handle payload_variant can still display the alert; the typed fields let modern receivers show the authoring unit and handle cancel referencing without XML parsing.

Typical self-authored alert compresses to ~72B on the wire (911) / ~79B (cancel). Cancel events reference the original alert UID via cancel_reference_uid.

Swift — read an emergency alert:

let packet = parser.parse(emergency911Xml)
if case .emergency( emergency)  packet.payloadVariant {
     emergency.type {
     .alert911:
        ()
     .inContact:
        ()
     .cancel:
        ()
    :
        ()
    }
}

TaskRequest

Structured tasking record for CoT type t-s. Captures the target UID, assignee, priority, status, and a short note — everything the raw-detail fallback loses when flattening a task into remarks text. The envelope carries the requester UID (implicit) and creation time.

The task_type field is free-text (capped at 12 chars) to avoid proto churn when ATAK adds new task categories — common values are "engage", "observe", "recon", "rescue".

Python — inspect a task request:

GeoChat receipts

Delivered (b-t-f-d) and read (b-t-f-r) chat receipts ride on the same chat = 31 slot as regular chat messages. The CoT type string on cot_type_id distinguishes delivered vs read at the envelope level; two new fields on GeoChat carry the referenced message UID so receivers can match the receipt back to the outbound message without XML parsing.

Field	Values

TypeScript — handle an incoming chat or receipt:

Color encoding with AtakPalette

Every color field in DrawnShape, Marker, and RangeAndBearing uses two parallel fields:

A Team enum for the 14 ATAK palette colors (White, Yellow, Orange, Magenta, Red, Maroon, Purple, Dark Blue, Blue, Cyan, Teal, Green, Dark Green, Brown) — encodes in 2 bytes on the wire
A fixed32 _argb fallback for custom user-picked colors — encodes in 5 bytes

The AtakPalette helper (shipped in every SDK) does the bidirectional lookup: argbToTeam(0xFFFFFFFF) returns Team.White, teamToArgb(Team.Red) returns 0xFFFF0000. The parser sets both fields so receivers can pick whichever one suits them; the builder uses the palette's canonical ARGB when the team enum is set, otherwise the raw fallback bits so custom colors round-trip byte-for-byte.

Remarks-Aware Compression

compressWithRemarksFallback() preserves user-authored <remarks> text (shape descriptions, route notes, etc.) when the compressed packet fits under the LoRa MTU. If it doesn't fit, remarks are stripped and the packet is re-compressed. If it still doesn't fit, the method returns null and the caller drops the packet. This is the recommended entry point for mesh transmission — it subsumes the size guard that callers would otherwise need:

val wire = compressor.compressWithRemarksFallback(packet, maxWireBytes = 225)
    ?: return // packet too large even without remarks

Real-World Compression Examples

End-to-end walkthroughs showing actual CoT XML from ATAK/iTAK being compressed for LoRa mesh transmission. Each example shows the raw XML, what gets stripped before compression, the resulting proto structure, and the final compressed wire payload. The LoRa MTU is 237 bytes.

Note: The per-example compressed byte sizes in this section are illustrative — they predate the v0.4.0 wire changes (512KB proto-trained dictionary, magic-number strip, skip-compress) and are kept here only to show the shape of the reduction. For exact, regenerated per-fixture sizes see testdata/compression-report.md.

PLI — Position Report (`a-f-G-U-C`)

Raw CoT XML from TAK client (754 bytes)

After stripping (~400 bytes) — <takv>, <precisionlocation>, <_flow-tags_> removed

TAKPacketV2 proto fields

cot_type_id:  (a-f-G-U-C)    how:  (h-e)
         device_callsign: 
           longitude_i: 
 -                  speed:  (cm/s)      course:  (deg×)
                     team:  (Cyan)          role:  (TeamMember)
  (GPS)               alt_src:  (GPS)
  (normalized)       phone: 
(no payload_variant  → implicit PLI)

Stage	Size	Reduction
Raw XML

GeoChat — Broadcast Message (`b-t-f`)

Raw CoT XML from iTAK (1031 bytes)

TAKPacketV2 proto fields — chat.to omitted for broadcast (saves 16 bytes)

cot_type_id: 25 (b-t-f)       how: 3 (h-g-i-g-o)
callsign: "iPad"               uid: "GeoChat.23131970-...All Chat Rooms.08C6FA28"
chat {
  message: "Test"
  to_callsign: "iPad"          # to: null (broadcast = 0 bytes)
}

Stage	Size	Reduction
Raw XML

Rectangle — Drawn Shape (`u-d-r`)

Raw CoT XML from ATAK (945 bytes)

After stripping (~500 bytes) — <__shapeExtras>, <creator>, <tog>, <archive>, <remarks/>, <strokeStyle>, <precisionlocation> removed

TAKPacketV2 proto fields — vertices delta-encoded from anchor point

Stage	Size	Reduction
Raw XML

Circle — Drawn Shape (`u-d-c-c`)

Raw CoT XML from ATAK (851 bytes)

TAKPacketV2 proto fields — circle stored as major/minor radii in centimeters

cot_type_id: 42 (u-d-c-c)     how: 1 (h-e)
callsign: "Shape 324"
latitude_i: 347720486          longitude_i: -924584657
shape {
  kind: 1 (Circle)             style: 1 (StrokeOnly)
  major_cm: 39314              minor_cm: 39314         angle_deg: 360
  stroke_argb: 0xFFFF4245      fill_argb: 
   
}

Stage	Size	Reduction
Raw XML

Route — 3 Waypoints (`b-m-r`)

Raw CoT XML from iTAK (890 bytes)

After stripping (~380 bytes) — <precisionLocation>, <marti/>, ??? attrs, routetype, order, color, empty callsign, and waypoint attrs removed

TAKPacketV2 proto fields — waypoints delta-encoded, UIDs omitted (receiver derives)

Stage	Size	Reduction
Raw XML

Note: Routes are the tightest fit under the 237B LoRa MTU. The stripper removes waypoint uid attributes (~40 bytes each in proto wire format), routetype, order, color, and empty callsign attributes. Without UID stripping, a 5-waypoint route compresses to ~271 bytes (over the 237B limit); with it, even routes with 5-6 waypoints fit comfortably. The builder generates deterministic UIDs () on reconstruction so ATAK can create internal waypoint markers.

Route reconstruction details: The CotXmlBuilder emits route elements in the order ATAK expects:

waypoints first — each with , , , 3-component , and

The stale time for routes (and all static CoT types) is extended to a minimum of 15 minutes before mesh transmission to survive multi-hop LoRa delivery. iTAK uses a 2-minute stale for routes which expires before mesh delivery completes.

Marker — Spot Map (`b-m-p-s-m`)

Raw CoT XML from ATAK (721 bytes)

After stripping (~400 bytes) — <archive>, <remarks/>, <precisionlocation>, ??? removed

TAKPacketV2 proto fields — kind derived from CoT type, color as palette enum

cot_type_id: 8 (b-m-p-s-m)    how: 3 (h-g-i-g-o)
callsign: "R 1"
latitude_i: 100060600          longitude_i: 950036200
marker {
  kind: 1 (Spot)               readiness: true
  color: 4 (Red)               : xFFFF0000
  : 
  : 
  : 
  : 
}

Stage	Size	Reduction
Raw XML

Compression Summary

Median compression ratio across all 47 fixture types: 7.2× (400-2300 bytes XML → 42-184 bytes wire).

Wire Optimizations

The SDK applies several optimizations to minimize wire payload size:

Stripped elements and attributes are not needed for rendering — the SDK extracts all structurally meaningful data (coordinates, waypoints, colors, stroke weight, method, direction, prefix) into typed proto fields. The stripped metadata is display-only, UI-state, or redundant with proto fields.

Route Delivery via Data Package (ATAK)

ATAK silently ignores b-m-r route CoT events received over TCP streaming connections. Routes are only accepted from KML/GPX file import, TAK Server mission sync, or data packages auto-imported from /sdcard/atak/tools/datapackage/. iTAK does not have this limitation.

The Meshtastic Android app works around this by converting mesh-received routes into KML data packages:

Route arrives from mesh as a compressed TAKPacketV2
SDK decompresses and reconstructs the route XML with waypoint coordinates
RouteDataPackageGenerator extracts waypoints and generates a KML <LineString>
KML is packaged in a MissionPackageManifest v2 zip with manifest.xml
Zip is written to /sdcard/atak/tools/datapackage/{routeUid}.zip

Route over LoRa mesh (~122 bytes)
    ↓ TakCompressor.decompress()
Route CoT XML (waypoints, method, direction)
    ↓ RouteDataPackageGenerator.generateDataPackage()
{routeUid}.zip
├── {routeUid}.kml      ← KML LineString with lon,lat,hae coordinates
└── manifest.xml         ← MissionPackageManifest v2
    ↓ AtakFileWriter.writeToImportDir()
/sdcard/atak/tools/datapackage/{routeUid}.zip
    ↓ ATAK auto-import
Route rendered in ATAK Route Manager

Supported Platforms

Counts are source-declared test methods (current as of v0.5.1, including the new CotMeshSanitizer suites). Parametrized methods expand to more individual cases at run time — e.g. the Kotlin JVM suite executes 315 tests and Python's pytest 229.

Every platform is byte-interoperable: .pb and .bin golden files written by Kotlin's CompressionTest.generate compression report are consumed by the other four platforms for exact-match validation (within protobuf field-order tolerance) and full round-trip equivalence.

Quick Start

Kotlin

val parser = CotXmlParser()
val compressor = TakCompressor()

// Compress a CoT message for LoRa
// Pre-process raw ATAK CoT XML before parsing (see "Mesh Hygiene" above —
// the same helper exists in all five bindings)
var clean = CotMeshSanitizer.normalizeCotXml(cotXmlString)
clean = CotMeshSanitizer.stripNonEssentialForMesh(clean)
val packet = parser.parse(clean)
val wirePayload = compressor.compress(packet)

// Decompress a received payload
val received = compressor.decompress(wirePayload)
val cotXml = CotXmlBuilder().build(received)

Swift

let parser = CotXmlParser()
let compressor = TakCompressor()

// Compress
let packet = parser.parse(cotXmlString)
let wirePayload = try compressor.compress(packet)

// Decompress
 received   compressor.decompress(wirePayload)
 cotXml  ().build(received)

Python

from meshtastic_tak import CotXmlParser, CotXmlBuilder, TakCompressor

parser = CotXmlParser()
compressor = TakCompressor()

# Compress
packet = parser.parse(cot_xml_string)
wire_payload = compressor.compress(packet)

# Decompress
received = compressor.decompress(wire_payload)
cot_xml = CotXmlBuilder().build(received)

TypeScript

import { parseCotXml, buildCotXml, TakCompressor } from "@meshtastic/takpacket-sdk";

const compressor = new TakCompressor();

// Compress
const packet = parseCotXml(cotXmlString);
 wirePayload =  compressor.(packet);


 received =  compressor.(wirePayload);
 cotXml = (received);

C#

using Meshtastic.TAK;

var parser = new CotXmlParser();
var compressor = new TakCompressor();
var builder = new CotXmlBuilder();

// Compress
var packet = parser.Parse(cotXmlString);
var wirePayload = compressor.Compress(packet);

// Decompress
var received = compressor.Decompress(wirePayload);
var cotXml = builder.Build(received);

API Reference

📚 Browse the full generated API reference for each language at meshtastic.github.io/TAKPacket-SDK.

Each platform implements the same components with identical behavior:

Dictionary Management

Testing

All five language implementations share the same test vectors in testdata/:

Run tests for each platform:

cd kotlin && ./gradlew test
cd swift && swift test
cd csharp && dotnet test
cd typescript && npm test
cd python && pytest

Or run all five at once:

./build.sh test

The Kotlin CompressionTest.generate compression report test regenerates testdata/compression-report.md, testdata/protobuf/*.pb, and testdata/golden/*.bin — it's the canonical fixture generator for the entire SDK.

License

GPL-3.0 — see LICENSE for details.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

protobufs★ 168

meshtasticProtobuf message definitions for a mesh radio network, documented with API reference and prebuilt TypeScript, Rust and cross-language client packages for app and firmware integration.Shared: sdk

kotlin-sdk★ 1.4k

modelcontextprotocolImplements the Model Context Protocol, enabling client and server integration with LLM surfaces. Supports standard transports, handles protocol messages, and offers sample setups for server and client configurations.Shared: sdk

pbandk★ 296

streemGenerates and manages code for Protocol Buffers with features like clean data class generation, JSON serialization, oneof handling as sealed classes, and support for proto2 and proto3 syntaxes.Shared: sdk

WorldWindKotlin★ 174

WorldWindEarth3D virtual globe API for visualizing geographic or geo-located information in 3D and 2D. Enables customization of terrain and imagery, and interaction with various geometric shapes.Shared: sdk

kotlin-multiplatform-oidc★ 153

kalinjulLightweight implementation of OpenID Connect/OAuth 2.0 supporting Authorization Code Grant Flow, discovery, PKCE, and simple JWT parsing. Includes Android, iOS, desktop support, and OkHttp/Ktor integration.Shared: sdk

Alert-KMP★ 103

KhubaibKhan4Facilitates native notification displays across Android, iOS, Web, and Desktop using JetBrains Compose. Features customizable notifications, event handling, and local notifications support with a unified API.Shared: sdk

Kotlin / KMP	kotlin/README.md	Dokka
Swift	swift/README.md	DocC
Python	python/README.md	pdoc
TypeScript	typescript/README.md	TypeDoc
C# / .NET	csharp/README.md	DocFX

Total test messages	47
100% under 237B LoRa MTU	✅ YES
Median compressed size	87B
Median compression ratio	7.2×
Worst case	184B (77% of LoRa MTU — `route_itak_3wp`)

`stripNonEssentialForMesh(xml)`	Removes display-only `<detail>` content (e.g. `takv`, `__geofence`, `archive`, `creator`, stroke/precision-location styling, route-link UIDs, unknown `="???"` attributes) while preserving everything the receiver needs to render or route — including TAK-Talk `<voice>` and `<marti>` directed routing. Safe on any CoT XML; a no-op when there's nothing to strip.
`normalizeCotXml(xml)`	Drops the `<?xml …?>` declaration and collapses inter-tag whitespace (`> <` → `><`) so the event matches the single-line stream TAK TCP clients expect. Whitespace inside text nodes is left intact.

(none)	(implicit PLI)	—	`a-f-G-U-C`, `a-f-G-U-C-I`, …	Default ground-unit position — no `payload_variant` set
31	`chat`	`GeoChat`	`b-t-f`, `b-t-f-d`, `b-t-f-r`	Team chat message (plus delivered/read receipts via new fields)
32	`aircraft`	`AircraftTrack`	`a-n-A-C-F`, `a-h-A-M-F-F`, …	ADS-B / military air track
33	`raw_detail`	`bytes`	any	Raw `<detail>` fallback for callers that build a packet directly (no public compressor path)
34	`shape`	`DrawnShape`	`u-d-c-c`, `u-d-r`, `u-d-f`, `u-d-f-m`, `u-d-p`, `u-r-b-c-c`, `u-r-b-bullseye`, `u-d-c-e`, `u-d-v`, `u-d-v-m`	Tactical graphics
35	`marker`	`Marker`	`b-m-p-s-m`, `b-m-p-w`, `b-m-p-c`, `a-u-G`, `b-m-p-w-GOTO`, `b-m-p-c-ip`, `b-m-p-c-cp`, `b-m-p-s-p-op`, `b-i-x-i`, …	Fixed markers, 2525 symbols, icons, mission points
36	`rab`	`RangeAndBearing`	`u-rb-a`	Range-and-bearing measurement
37	`route`	`Route`	`b-m-r`	Waypoint + control point sequence
38	`casevac`	`CasevacReport`	`b-r-f-h-c`	9-line MEDEVAC request
39	`emergency`	`EmergencyAlert`	`b-a-o-tbl`, `b-a-o-pan`, `b-a-o-opn`, `b-a-g`, `b-a-o-c`, `b-a-o-can`	Emergency / 911 alert
40	`task`	`TaskRequest`	`t-s`	Tasking / engagement request
41	`taktalk`	`TakTalkMessage`	`m-t-t`	TAKTALK chat message (text envelope; voice rides UDP/RTP off-mesh)
42	`taktalk_room`	`TakTalkRoomData`	`y-`	TAKTALK room/membership broadcast (resolves room UUIDs to name + roster)

1	`Circle`	`major_cm`, `minor_cm`, `angle_deg`
2	`Rectangle`	4 vertices (corner points)
3	`Freeform`	N vertices (polyline)
4	`Telestration`	N vertices (may truncate at 32, sets `truncated=true`)
5	`Polygon`	N vertices (implicitly closed)
6	`RangingCircle`	`major_cm`, `minor_cm`, `angle_deg`, stroke only
7	`Bullseye`	Ellipse + `bullseye_distance_dm`, `bullseye_bearing_ref`, `bullseye_flags`, `bullseye_uid_ref`
8	`Ellipse`	`major_cm`, `minor_cm`, `angle_deg` (distinct major/minor, not a circle)
9	`Vehicle2D`	N vertices (footprint polygon)
10	`Vehicle3D`	N vertices (footprint polygon; receiver extrudes)

Kotlin	`CotMeshSanitizer.stripNonEssentialForMesh(xml)` / `.normalizeCotXml(xml)` — `object`, `commonMain`
Swift	`CotMeshSanitizer.stripNonEssentialForMesh(_:)` / `.normalizeCotXml(_:)` — `enum`
Python	`strip_non_essential_for_mesh(xml)` / `normalize_cot_xml(xml)` — module fns (also a `CotMeshSanitizer` static facade)
TypeScript	`stripNonEssentialForMesh(xml)` / `normalizeCotXml(xml)` — exported fns
C#	`CotMeshSanitizer.StripNonEssentialForMesh(xml)` / `.NormalizeCotXml(xml)` — `static class`

`0xFFFF0000` (opaque red)	`ff0000ff`	`<color>ff0000ff</color>`
`0x9F00FF00` (semi-transparent green)	`9f00ff00`	`<color>9f00ff00</color>`
`0x00000000` (transparent)	not emitted	PolyStyle omitted

1	`Spot`	`b-m-p-s-m`
2	`Waypoint`	`b-m-p-w`
3	`Checkpoint`	`b-m-p-c`
4	`SelfPosition`	`b-m-p-s-p-i`, `b-m-p-s-p-loc`
5	`Symbol2525`	`a-*-G` with `iconsetpath="COT_MAPPING_2525B/…"`
6	`SpotMap`	`iconsetpath="COT_MAPPING_SPOTMAP/…"`
7	`CustomIcon`	Any type with a `UUID/group/icon.png` iconset
8	`GoToPoint`	`b-m-p-w-GOTO`
9	`InitialPoint`	`b-m-p-c-ip`
10	`ContactPoint`	`b-m-p-c-cp`
11	`ObservationPost`	`b-m-p-s-p-op`
12	`ImageMarker`	`b-i-x-i`

`method`	`Driving`, `Walking`, `Flying`, `Swimming`, `Watercraft`
`direction`	`Infil`, `Exfil`
`prefix`	Short waypoint prefix (e.g. `"CP"`, `"RP"`)
`links[]`	Up to 16 waypoint/checkpoint entries, each with delta-encoded point, uid, callsign, and `link_type` (0=waypoint, 1=checkpoint)

`Precedence`	`Urgent` (A), `UrgentSurgical` (B), `Priority` (C), `Routine` (D), `Convenience` (E)
`HlzMarking`	`Panels`, `PyroSignal`, `Smoke`, `None`, `Other`
`Security`	`NoEnemy` (N), `PossibleEnemy` (P), `EnemyInArea` (E), `EnemyInArmedContact` (X)

`Type_Alert911`	1	`b-a-o-tbl`
`Type_RingTheBell`	2	`b-a-o-pan`
`Type_InContact`	3	`b-a-o-opn`
`Type_GeoFenceBreached`	4	`b-a-g`
`Type_Custom`	5	`b-a-o-c`
`Type_Cancel`	6	`b-a-o-can`

`Priority`	`Low`, `Normal`, `High`, `Critical`
`Status`	`Pending`, `Acknowledged`, `InProgress`, `Completed`, `Cancelled`

PLI (position)	754 B	98 B	7.7x	✅
GeoChat (text)	1,031 B	80 B	12.9x	✅
Rectangle (4 vertices)	945 B	101 B	9.4x	✅
Circle (ellipse)	851 B	90 B	9.5x	✅
Route (3 waypoints)	890 B	~80 B	11.1x	✅
Marker (spot)	721 B	81 B	8.9x	✅

Endpoint normalization	~20 B/msg	Default endpoints (`0.0.0.0:4242:tcp`, `*:-1:stcp`) normalized to empty; builder restores the default on reconstruction
Broadcast sentinel	~16 B/chat	`chat.to = "All Chat Rooms"` normalized to null (proto field omitted)
Element stripping	~100-200 B/msg	Non-essential XML elements (`<takv>`, `<voice>`, `<precisionLocation>`, `<__geofence>`, `<marti>`, `<__shapeExtras>`, `<creator>`, `<tog>`, `<archive>`, `<strokeStyle>`, empty `<remarks>`) stripped before SDK parsing
Attribute stripping	~30-80 B/msg	Display-only attributes stripped: `routetype`, `order`, `color` (from `<link_attr>`), `access`, empty `callsign`/`phone`, and all `"???"` placeholder values
Route waypoint UID stripping	~40 B/waypoint	UUID `uid` attributes stripped from route `<link>` elements before compression. Builder generates deterministic UIDs (`{eventUid}-{index}`) on reconstruction. Saves ~120 bytes proto for a 3-waypoint route
Stale time extension	0 B (metadata)	Static CoT types (routes `b-m-r`, shapes `u-d-`, markers `b-m-p-`) get a minimum 15-minute stale TTL before mesh transmission. Prevents iTAK's 2-min stale from expiring during multi-hop LoRa delivery
Delta vertex encoding	~50% vs abs	Shape/route vertices stored as deltas from the event anchor point. `DrawnShape` packs them into two `repeated sint32` columns (`vertex_lat_deltas` / `vertex_lon_deltas`) so field framing is paid once per column, not once per vertex
Remarks preservation	variable	Non-empty `<remarks>` text preserved for shapes, markers, routes, casevac, emergency, and task types via top-level `string remarks = 24` proto field. `compressWithRemarksFallback()` strips remarks automatically if the compressed packet exceeds the LoRa MTU, so annotations survive when there's room
zstd dictionaries (proto-trained)	~5-14x	Two pre-trained dictionaries — non-aircraft 512 KB + aircraft 4 KB — trained on serialized `TAKPacketV2` protobuf bytes (not raw CoT XML), at zstd level 19
zstd magic-number strip	~8 B/msg	The 4-byte zstd frame magic (`28 B5 2F FD`) is stripped on encode and re-prepended on decode; frames are compressed with `dictID` / `contentSize` / `checksum` disabled. Done identically in all five language bindings
Skip-compress for tiny packets	prevents expansion	When the raw protobuf is no larger than the compressed body, the encoder emits the `0xFF` uncompressed sentinel + raw protobuf instead, so small packets never expand on the wire

Android / ATAK Plugin	Kotlin	`kotlin/`	✅ 80
iOS / macOS	Swift	`swift/`	✅ 43
Windows / .NET	C#	`csharp/`	✅ 52
Web / Node.js	TypeScript	`typescript/`	✅ 57
CLI / Scripting	Python	`python/`	✅ 45

CotXmlParser	Parses a CoT XML event string into a `TAKPacketV2` protobuf with the appropriate typed payload variant
CotXmlBuilder	Builds a CoT XML event string from a `TAKPacketV2` protobuf (handles every typed variant including `raw_detail`)
TakCompressor	Compresses/decompresses `TAKPacketV2` using zstd dictionaries, with `compress()`, `compressWithRemarksFallback()`, and `compressWithStats()` entry points
CotTypeMapper	Maps CoT type strings to/from `CotType` enum values; classifies aircraft types for dictionary selection
AtakPalette	Bidirectional lookup between ATAK's 14-color palette and `Team` enum values, for color round-trip preservation
CotMeshSanitizer	CoT-XML mesh hygiene applied before parsing: `stripNonEssentialForMesh` (drop display-only `<detail>`, preserving TAK-Talk `<voice>`/`<marti>`) + `normalizeCotXml` (strip `<?xml?>`, collapse inter-tag whitespace). Pure regex, no protobuf/compression deps — see Mesh Hygiene

TAKPacket-SDK

TAKPacket-SDK

Documentation

Architecture

How It Works

1. CoT XML Parsing

2. Compression Pipeline

3. Wire Format

4. CoT XML Reconstruction

Mesh Hygiene (CotMeshSanitizer)

Structured Payload Types

DrawnShape

Marker

RangeAndBearing

Route

CasevacReport

EmergencyAlert

TaskRequest

GeoChat receipts

Color encoding with AtakPalette

Remarks-Aware Compression

Real-World Compression Examples

PLI — Position Report (a-f-G-U-C)

GeoChat — Broadcast Message (b-t-f)

Rectangle — Drawn Shape (u-d-r)

Circle — Drawn Shape (u-d-c-c)

Route — 3 Waypoints (b-m-r)

Marker — Spot Map (b-m-p-s-m)

Compression Summary

Wire Optimizations

Route Delivery via Data Package (ATAK)

Supported Platforms

Quick Start

Kotlin

Swift

Python

TypeScript

C#

API Reference

Dictionary Management

Testing

License

Related libraries

TAKPacket-SDK

Documentation

Architecture

How It Works

1. CoT XML Parsing

2. Compression Pipeline

3. Wire Format

4. CoT XML Reconstruction

Mesh Hygiene (CotMeshSanitizer)

Structured Payload Types

DrawnShape

Marker

RangeAndBearing

Route

CasevacReport

EmergencyAlert

TaskRequest

GeoChat receipts

Color encoding with AtakPalette

Remarks-Aware Compression

Real-World Compression Examples

PLI — Position Report (a-f-G-U-C)

GeoChat — Broadcast Message (b-t-f)

Rectangle — Drawn Shape (u-d-r)

Circle — Drawn Shape (u-d-c-c)

Route — 3 Waypoints (b-m-r)

Marker — Spot Map (b-m-p-s-m)

Compression Summary

Wire Optimizations

Route Delivery via Data Package (ATAK)

Supported Platforms

Quick Start

Kotlin

Swift

Python

TypeScript

C#

Mesh Hygiene (`CotMeshSanitizer`)

PLI — Position Report (`a-f-G-U-C`)

GeoChat — Broadcast Message (`b-t-f`)

Rectangle — Drawn Shape (`u-d-r`)

Circle — Drawn Shape (`u-d-c-c`)

Route — 3 Waypoints (`b-m-r`)

Marker — Spot Map (`b-m-p-s-m`)

Mesh Hygiene (`CotMeshSanitizer`)

PLI — Position Report (`a-f-G-U-C`)

GeoChat — Broadcast Message (`b-t-f`)

Rectangle — Drawn Shape (`u-d-r`)

Circle — Drawn Shape (`u-d-c-c`)

Route — 3 Waypoints (`b-m-r`)

Marker — Spot Map (`b-m-p-s-m`)