TAK-protokolla avattuna: miten CoT XML ja protobuf kulkevat meshissä ja striimiyhteyksissä

TAK-protokolla on siirtosopimus, jolla ATAK, WinTAK, iTAK ja TAK Server vaihtavat Cursor on Target (CoT) -tapahtumia. Versio 0 lähettää tapahtuman tavallisena XML:nä; versio 1 pituuden etuliitteellä varustettuna protobuf-viestinä, suunnilleen puolet pienempänä. Sama hyötykuorma kulkee kolmella kuljetuksella: palvelimettomalla UDP-multicastilla paikallisessa meshissä, pysyvinä TCP/TLS-striimeinä TAK Serveriin (oletusportti 8089) ja palvelinten välisenä federaationa (9000/9001).

Jos integroit anturin, dronen tai C2-järjestelmän TAK-ekosysteemiin, tämä erottelu ratkaisee heti: CoT on tietomalli — <event>, <point>, <detail> — kun taas TAK-protokolla määrittää, miten nämä tavat kehystetään, versioidaan ja neuvotellaan kullakin kuljetuksella. Itse XML-skeema on käsitelty Cursor on Target -muodon oppaassamme ja CoT-skeeman syväsukelluksessa; tämä artikkeli on kysymyksen toinen puoli: siirtoyhteys.

CoT vs. TAK-protokolla: tietomalli vs. siirtosopimus

Pidä kolme kerrosta erillään — ekosysteemin dokumentaatio sekoittaa niitä jatkuvasti:

• CoT-tapahtumamalli. Yksi XML-dokumentti per tapahtuma: tyyppikoodi, UID, time/start/stale, WGS-84-piste ja laajennettava <detail>. Semanttinen sisältö, identtinen kaikilla kuljetuksilla.
• Koodaus (TAK-protokollan versio). Versio 0 koodaa tapahtuman XML-tekstinä; versio 1 protobuf-viestinä TakMessage. Molemmat kantavat samat tapahtumat.
• Kuljetus. UDP-multicast meshissä, pysyvä TLS-striimi TAK Serveriin tai federaatiolinkki palvelinten välillä — kukin kehystää hyötykuorman eri tavalla.

TAK-tuotteiden mukana jaettava protokollakuvaus asettaa kaksi perussääntöä: versio V lähettävä asiakas osaa myös dekoodata version V, ja jokaisen asiakkaan on yhä dekoodattava version 0 XML. Siksi sekalaiset kalustot toimivat edelleen — kaikki palautuu siististi XML:ään.

TAK-protokolla versio 0: puhdas CoT XML

Versio 0 kantoi ekosysteemiä ensimmäisen vuosikymmenen ja on yhä kaikkialla varatila. Se toimii eri tavoin kullakin kuljetuksella:

• Mesh SA (multicast). tilannekuulutukset ovat UDP-datagrammeja tunnettuun multicast-ryhmään 239.2.3.1:6969 — yksi CoT XML -tapahtuma per datagrammi, ilman palvelinta. Jokainen ryhmään liittynyt laite saa jokaisen tapahtuman, eikä uudelleenlähetystä ole: kadonnut datagrammi on kadonnut sijaintiraportti. Tämä on tila palvelimettoman blue force trackingin takana ryhmän Wi-Fi- tai MANET-segmentissä. (ATAK multicastaa GeoChatin erillisessä ryhmässä 224.10.10.1:17012, jonka TAK Server voi ottaa sisääntulona.)
• Suunnatut viestit. Viestit yhdelle vastaanottajalle kulkevat lyhytikäisellä TCP-yhteydellä: yhdistä, lähetä yksi tapahtuma, katkaise. Suoria vertaisia kuunteleva ATAK-laite hyväksyy ne TCP-portissa 4242 — kätevä tapa syöttää tapahtuma yhteen päätelaitteeseen ilman palvelinta.
• Striimi TAK Serveriin. Pysyvä yhteys (yleensä TLS) kantaa päästä päähän -virtaa XML-tapahtumia, kukin XML-määritys edessä ja rivinvaihto perässä. Vastaanottaja ei saa pituusetuliitettä eikä erotinta: hän pilkkoo striimin etsimällä kirjaimellista tokenia </event> ja leikkaamalla heti sen jälkeen — seuraava määritys alkaa aivan seuraavasta tavusta.

Käytännössä striimimuoto näyttää tältä (lyhennetty):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<event version="2.0" uid="RAVEN-1" type="a-f-G-U-C" how="m-g" …>…</event><?xml version="1.0" …?><event …>…</event>

Tämä tokenia skannava pilkkoja on protokollan käyttäytymistä, ei toteutuksen erikoisuus — TAK Serverin oma striimikoodekki dokumentoi erottimien puutteen ja etsii sulkevaa tagia. Jokaisen yhdyskäytävän on lähetettävä tapahtumia, jotka pilkkoutuvat puhtaasti: kokonaisia tapahtumia, määritys ensin, ei mitään väliin. Annotoidut täydet tapahtumat ovat CoT-viestiemme esimerkeissä.

TAK-protokolla versio 1: protobuf TakMessage

Versio 1 korvaa XML-tekstin yhdellä proto3-viestillä — atakmap.commoncommo.protobuf.v1.TakMessage — jonka määritelmä toimitetaan TAK-distribuutioiden mukana ja joka on peilattu kirjastoissa kuten Python-paketti takproto. Rakenne on tiivis mutta tarkasti määritelty:

• TakMessage sisältää kaksi valinnaista osaa: TakControl (protokollan kirjanpito — lähettäjän dekoodaamat min/max-versiot plus kontaktin UID) ja itse CotEvent.
• CotEvent kantaa kirjekuoren: type, uid, how, valinnaiset access/qos/opex, kolme aikaleimaa millisekunteina Unix-epookista (sendTime, startTime, staleTime) ja pisteen kentät lat, lon, hae, ce, le doubleina. Tuntematon korkeus tai virhe käyttää vartijatarkistusta 999999, kuten XML-käytännössä.
• Detail — tässä tulee kiinnostavaa. Kuusi hyvin tunnettua detail-elementtiä muuttui tyypitetyiksi alaviesteiksi: contact (endpoint, callsign), group (__groupsta: name, role), precisionLocation (geopointsrc, altsrc), status (battery), takv (device, platform, os, version), track (speed, course). Kaikki muu — remarks, chatin rungot, liitännäiset elementit — tungetaan yhteen xmlDetail-merkkijonoon, joka sisältää loppujen lasten raaka-XML:nä.

Kaksi spesifikaation sääntöä pelastaa tiimit hienovaraiselta datan rapautumiselta. Ensinnäkin, vain kokonaisia elementtejä: detail-elementti muunnetaan kokonaan tyypitettyksi viestiksi tai se jää kokonaan xmlDetailiin — sitä ei koskaan pilkota, ja jos se ei kartoitu siististi, se jää xmlDetailiin. Toiseksi vastaanottajat sulauttavat tyypitetyt viestit takaisin XML:ksi, ja ristiriidatapauksessa xmlDetail voittaa. Uusia kenttiä saa lisätä vain olemassa olevien viestien loppuun; kaikki semanttinen vaatii versionnosto. Käytännössä protobufin säästö kutistuu tyypittömän detailin kasvaessa — juuri sitä näkee chat- tai liitännäispainotteisessa liikenteessä.

Meshin ja striimin kehystys: konkreettiset tavut

Molemmat versiot kulkevat molemmilla kuljetuksilla; kehystys eroaa kuljetuksen mukaan, ei hyötykuorman mukaan:

• Mesh-datagrammi: 0xbf, varint-protokollaversio, 0xbf, sitten hyötykuorma. Maaginen tavu 0xbf (191 desimaalina) antaa vastaanottajan nuuhkia yhden datagrammin ja tietää, onko kyse protobufista vai legacy-XML:stä, joka alkaa merkillä < — TAK Serverin UDP-sisääntulot tekevät juuri tämän tarkistuksen jokaiselle datagrammille.
• Striimikehys: 0xbf, varint-kuorman pituus tavuina, sitten hyötykuorma. Versiotavua ei ole — versio neuvoteltiin kertaalleen per yhteys (seuraava osio), joten sen toistaminen joka kehyksessä olisi tuhlausta.

Varintit ovat tavallisia etumerkittömiä protobuf-varintteja — 7 bittiä kerrallaan, vähiten merkitsevä ensin, ylin bitti merkitsee jatkumista, enintään 64 bittiä (10 tavua). 258 tavun hyötykuorma koodautuu muotoon 82 02; 127 on 7f, 128 on 80 01.

Koska jokainen kehys kantaa oman pituutensa, striimijäsennin on pieni tilakone: odota 0xbf, kerää varint, puskuroi täsmälleen niin monta tavua, dekoodaa, toista — kantaen osittaiset kehykset lukukertojen yli. Versio 0 ei tarjoa mitään tätä; skannaat tekstiä hakien </event> ja toivot, ettei mikään katkea kesken tapahtuman.

Striimineuvottelu: t-x-takp-v, t-x-takp-q, t-x-takp-r

Asiakas ei voi tietää, puhuuko palvelin protobufia, joten vaihto neuvotellaan yhdisteyden sisällä kolmella CoT-ohjaustapahtumalla — itsekin lähetettynä XML:nä:

1. Tarjous (t-x-takp-v). TAK-protokollaa tukeva palvelin voi lähettää yhden tämän tyyppisen tapahtuman, joka kantaa <detail><TakControl><TakProtocolSupport version="1"/> — yhden elementin per tuettu versio, korkeintaan kerran per yhteys, autentikoinnin jälkeen jos sisääntulo sitä vaatii.
2. Pyyntö (t-x-takp-q). Asiakas valitsee version tarjouksesta ja vastaa <TakRequest version="1"/>, minkä jälkeen sen on lopetettava XML:n lähettäminen (käsitellen yhä saapuvaa XML:ää) ja odotettava — vähintään minuutti ennen luovuttamista ja uudelleenyhdistämistä.
3. Vastaus (t-x-takp-r). Palvelin vastaa <TakResponse status="true"/> tai "false". Arvolla true molemmat osapuolet vaihtavat koko yhteyden pituuskehystettyihin versio 1 -hyötykuormiin — sama versio molempiin suuntiin — eikä XML enää kulje. Arvolla false yhteys pysyy XML:nä ja asiakas voi yrittää myöhemmin uudelleen.

Kaikki kolme tapahtumaa jakavat yhden transaktio-UID:n (spesifikaation protouid), ja tanssi on tiukka: ennen true-vastausta lähetetty protobuf rikkoo yhteyden referenssipalvelimeen. Meshissä kättelyä ei ole: jokainen laite lähettää TakControl-viestin vähintään 60 sekunnin välein ilmoittaen minimi- ja maksimiversiot, jotka se dekoodaa; kaksi minuuttia hiljaiset kontaktit palaavat viimeisen dekoodattavan viestinsä versioon; ja kaikki lähettävät korkeimmalla versiolla, jonka kaikki tunnetut kontaktit osaavat dekoodata, palaten XML:ään heti kun legacy-laite on läsnä. Kuormitustestaa neuvottelu ennen kuin oletat kaluston vaihtuneen — viritysvipimet on TAK Server -suorituskykyoppaassamme.

TAK Serverin portit: oletuskartta

Oletukset TAK Server 5.7:n konfiguraatio-oppaasta ja sen esimerkki-CoreConfig.xmlstä; jokainen on säädettävissä, joten pidä tätä sen mitä valmis asennus avaa, ei sopimuksena. Oppaan oma palomuurineuvo on minimaalinen: avaa 8089 ja 8443.

Kaksi alaviitettä. FreeTAKServer, avoimen ekosysteemin Python-palvelin (katso avoimen TAK-ekosysteemin oppaamme), pitää 8089 CoT:lle TLS:n yli mutta käyttää 8087:ää salaamattomalle TCP-CoT:lle. Ja federaatio ansaitsee oman lukunsa: v1-linkki vaihtaa protobuf-FederatedEvent-viestejä nelitavuisen pituusetuliitteen takana, kun taas v2 ajaa gRPC-palvelua striimi-RPC:illä ja terveystarkistuksilla — käsitelty federaation asennusoppaassamme ja Federation Hub -arkkitehtuurikatsauksessamme.

Viestin koko ja kaistanleveys: XML vs. protobuf

Koodasimme kaksi edustavaa tapahtumaa molemmilla tavoilla — ATAK-tyylisen omapaikkailmoituksen (tyypitetty detail plus tyypittämätön uid-elementti) ja pienen drooniraidan MAVLink-sillasta, protobuf-puolen koodasi referenssi-Python-enkooderi:

Se on 52–59 % säästö näille muodoille — yhteneväinen 55–65 %:n kanssa, jota lainasimme droonitelemetrian integraatioartikkelissamme, ja Isoden vuoden 2025 kenttämittausten kanssa TAK:lle HF-radion yli: suunnilleen 530-tavuiset XML-tapahtumat vastaan 376–380-tavuisia federaatiossa siirrettäviä protobuf-viestejä, ennen pakkausta. Protobuf auttaa eniten siellä, missä XML on puhdas kirjekuori — määritykset, attribuuttien nimet, sulkevat tagit — kun taas xmlDetailiin pysäköity detail pitää XML-kokonsa.

Miksi radiolla väliä: neljäkymmentä käyttäjää, jotka ilmoittavat paikkansa joka kymmenes sekunti, maksavat noin 20 kbps striimatussa XML:ssä (634 t kpl) vastaan noin 8 kbps protobufissa, ennen TLS-tietueen ylikuormaa per viesti. Kapeakaistaisuudessa vaikutus on armoton — 75 bps:n nopeudella Isode mittasi 29–33 sekunnin päästä päähän -viiveen yhdelle tapahtumalle. Vielä yksi kokokäyttäytyminen: TAK Serverin striimilähtö kieltäytyy lähettämästä protobuf-TakMessagea, joka on suurempi kuin 65 536 tavua; ylikokoinen tapahtuma korvataan pienellä tiedostonsiirto-osoittimella, joka käskee asiakkaan noutamaan täyden XML:n HTTPS:llä. Chat-liikenne puretaan taktisen chatin datastrategia-artikkelissamme.

CoT:n lähettäminen Pythonista: TLS, sertifikaatit, protobuf

Kaikki yllä tiivistyy pieneen ohjelmaan — pelkkä standardikirjasto osaa avata TLS-yhteyden 8089-sisääntuloon asiakassertifikaatilla ja striimata version 0 XML-tapahtumia ilman riippuvuuksia:

import asyncio
import datetime as dt
import ssl
import xml.etree.ElementTree as ET

TAK_HOST, TAK_PORT = "tak.example.org", 8089      # TLS streaming input
CA_FILE, CERT_FILE, KEY_FILE = "takserver-ca.pem", "client.pem", "client.key"

def ts(t):  # CoT time: ISO 8601, UTC, millisecond precision
    return t.strftime("%Y-%m-%dT%H:%M:%S.") + f"{t.microsecond // 1000:03d}Z"

def cot_event(uid, cot_type, lat, lon, hae, callsign, stale_s=60):
    now = dt.datetime.now(dt.timezone.utc)
    ev = ET.Element("event", version="2.0", uid=uid, type=cot_type, how="m-g",
                    time=ts(now), start=ts(now),
                    stale=ts(now + dt.timedelta(seconds=stale_s)))
    ET.SubElement(ev, "point", lat=f"{lat:.7f}", lon=f"{lon:.7f}",
                  hae=f"{hae:.1f}", ce="10.0", le="9999999.0")
    ET.SubElement(ET.SubElement(ev, "detail"), "contact", callsign=callsign)
    return ET.tostring(ev, encoding="utf-8", xml_declaration=False)

async def drain(reader):
    # Keep reading the server (its t-x-takp-v offer, other users' SA),
    # or TCP flow control eventually stalls its writes to you.
    while await reader.read(65536):
        pass

async def main():
    ctx = ssl.create_default_context(cafile=CA_FILE)   # verify server cert + name
    ctx.load_cert_chain(CERT_FILE, KEY_FILE)           # our client identity
    reader, writer = await asyncio.open_connection(TAK_HOST, TAK_PORT, ssl=ctx)
    rx = asyncio.create_task(drain(reader))
    try:
        while not rx.done():
            writer.write(cot_event("gw-demo.uav-12", "a-f-A-M-F-Q",
                                   50.4501234, 30.5234567, 640.0, "UAV-12"))
            await writer.drain()
            await asyncio.sleep(5)                     # report well inside stale
    finally:
        writer.close()

asyncio.run(main())

Kolme yksityiskohtaa kantaa tässä kaiken. Asyncio-socketit poistavat Naglen algoritmin oletuksena käytöstä, joten jokainen tapahtuma lähtee heti — raakoja socketeja käyttäessä aseta TCP_NODELAY itse. drain-tehtävä ei ole koriste: palvelin, joka kirjoittaa koskaan lukemattomalle asiakkaalle, juuttuu lopulta TCP-virranhallintaan. Sertifikaattien on oltava PEM:ää: TAK Server myöntää PKCS#12-.p12-tiedoston (jonka ATAK kuluttaa), jonka OpenSSL muuntaa kolmella rivillä:

openssl pkcs12 -in gateway-01.p12 -clcerts -nokeys -out client.pem -passin pass:SECRET
openssl pkcs12 -in gateway-01.p12 -nocerts -nodes -out client.key -passin pass:SECRET
openssl pkcs12 -in truststore-root.p12 -nokeys -out takserver-ca.pem -passin pass:SECRET

Protobufille paketti takproto (PyPI) muuntaa CoT XML:ää versio 1 -hyötykuormiksi ja takaisin sekä lisää kehystyksen; PyTAK-kirjasto käärii koko asiakkaan — COT_URL hyväksyy tls://host:8089 tai udp+wo://239.2.3.1:6969, TAK_PROTO=1 valitsee protobufin, ja sertifikaatit tuodaan suoraan TAK-datakpaketista .zip. Laskelma "rakenna itse vai ota kirjasto" on TAK C2 -integraatiomallien artikkelissamme.

Toimitussemantiikka, tietoturva ja sudenkuopat jotka purevat

Ei kuittauksia — työn tekee stale

CoT on fire-and-forget jokaisessa kerroksessa: ei kuittauksia per viesti, ei järjestysnumeroita, ei istuntoja. Tuoreudesta huolehtii stale-aikaleima — kuluttajat vanhentavat tai pudottavat tapahtumat sen yli — ja tahdinus: lähetä selvästi omalle stale-ikkunallesi sisällä tai hyväksy aaveet kartalla. TAK Server pehmentää uudelleenyhdistyksiä latest SA -puskurillaan (uudet asiakkaat saavat heti tavoitettavien käyttäjien viimeisimmät tunnetut sijainnit), ja ATAK pitää yhteydet hengissä pingillä (t-x-c-t), johon palvelin vastaa pongilla (t-x-c-t-r). Lähetä nykykuvasi uudelleen jokaisen uudelleenyhdistyksen jälkeen sen sijaan, että olettaisit palvelimen muistaneen sen.

Sertifikaatit, ryhmät, kanavat

Operatiivinen TAK-liikenne on kaksisuuntaista TLS:ää: asiakas varmistaa palvelimen käyttöönoton CA:ta vastaan, palvelin varmistaa saman CA:n asiakassertifikaatin, ja sertifikaatin CN:stä tulee käyttäjätunnus ryhmäjaossa. Ryhmäjäsenyys — per sisääntulo, per sertifikaatti tai LDAP-/tiedostotaustojen kautta — on koko pääsynhallintamalli sille, kenen raiteita kuka näkee; parittomat yhteydet päätyvät __ANON__iin. Federaatio käyttää tahallaan erillistä luottamusvarastoa, joten kumppanin CA ei koskaan hiljaisesti valtuuta asiakasyhteyksiä, ja rekisteröinti toimii portissa 8446 HTTP Basic -todennuksen takana. Jos käyttöönotto tarvitsee HTTP-rajapintoja raakasocketien sijaan, se pinta kuvataan CloudTAK-rajapintaintegraatio-oppaassamme.

Toistuvat vikatilat

• Multicast, joka ei saavu: multicast etenee vain niin kauan kuin TTL sallii (oletus-TTL 1 pitää datagrammit paikallisessa segmentissä; TAK Serverin esimerkkikonfiguraatio nostaa sen 5:een), väärin säädetty IGMP-snooping pudottaa ryhmiä hiljaa, eikä multicast koskaan ylitä NAT:ia. Mesh SA on saman aliverkon tekniikkaa.
• Kellon driftaus: stale-pohjaisessa vanhentumisessa väärä kello joko haihduttaa kaikkien raidat tai jättää ne ikuisiksi. Synkronoi aika (GNSS tai NTP) ennen kuin debuggaat mitään muuta.
• Sertifikaattimuodon kitka: palvelin puhuu JKS:ää, asiakkaat PKCS#12:ta, palvelusi PEM:ää — ja client-auth-laajennettua avaimen käyttöä vailla olevat sertifikaatit hylätään jo kättelyssä. Muunna tarkoituksella ja testaa juuri se ketju.
• Naglen algoritmi: 200 ms eräilyviive on näkymätön datacenter-linkissä ja tappava taktisessa. Poista se käytöstä tai eräile eksplisiittisesti.
• Uudelleenyhdistysmyrskyt: sata yhdyskäytävää, jotka yhdistävät uudelleen yhtä aikaa radioikatkenemisen jälkeen, näyttää DDoS:lta. Käytä jittröityä eksponentiaalista peruutusta, todenna uudelleen, toista nykytila.
• Sekaversio-oletukset: yksi legacy-asiakas meshissä pudottaa kaikki takaisin XML:ään, eikä palvelin, joka ei koskaan tarjoa t-x-takp-v:tä, koskaan saa protobufia. Instrumentoi, millä koodauksella linkkisi asettuivat — tavut siirrossa minuutissa kertoo totuuden.

Referenssiarkkitehtuuri: CoT-yhdyskäytäväpalvelu

Pysyvä malli TAK-verkon ruokkimiseen ei-TAK-järjestelmistä on pieni, omistettu yhdyskäytäväpalvelu — ei jokaiseen lähteeseen upotettua koodia:

• Tuloliitinsovittimet — MAVLink, tutka, AIS, GPS-seurantalaitteet, REST-/WebSocket-syötteet — kukin normalisoituna sisäiseen raitamalliin.
• CoT-rakentaja — yksi paikka, joka omistaa UID-käytännön (vakaat, nimiavaruudelliset, törmäyskestävät), tyyppikartoituksen, how-koodit ja stale-ikkunat per lähde, tuottaen XML:ää tai protobufia samoin detail-säännöin.
• Lähtövalvoja — allas todennettuja TLS-yhteyksiä neuvottelulla (protobufia kun tarjotaan, muuten XML), jittröidyllä uudelleenyhdistyksellä, nopeudenmuotoilulla per linkki kapeakaistaisille poluille ja nykytilan toistolla.
• Operatiivinen pinta — linkkien terveys, käytetty koodaus, tavut minuutissa ja sertifikaattien vanhenemisen valvonta; taktisissa verkoissa protokolla on ensimmäinen epäilty ja viimeiseksi instrumentoitu.

Juuri tämä muoto — protokollalle uskollinen reuna toisen datan ja TAK Serverin välissä — on komponentti, jonka rakennamme puolustusohjelmille, rinnalla TAKpilot-kopilotin kanssa samalla infrastruktuurilla. Jos ohjelmasi piirtää tätä kaaviota juuri nyt, hae tiimi, joka on jo toimittanut sellaisen.