Vítejte v sekci pro vývojáře na webu Dronetag Help.

Najdete zde podklady a technické návody pro vývojáře. Je tu podrobná dokumentace API, pomocí které propojíte své systémy s řešeními Dronetagu pro Remote ID.

Kromě API zde najdete i návody, osvědčené postupy a další informace, které potřebujete ke spolehlivé integraci. Ať už propojujete naše produkty se svými stávajícími platformami, nebo zkoušíte něco nového, tato sekce vám k tomu dá potřebné nástroje i znalosti.

Projděte si, jak lze Dronetag zapojit do vašich systémů.

Podmínky použití​

Používání našeho API se řídí našimi podmínkami použití (Terms of Service).

Dronetag nabízí několik způsobů integrace, jak získat data z našich zařízení, především data Remote ID. Tento návod vám pomůže vybrat způsob, který se pro váš systém hodí nejlépe — ať už pracujete s platformami UTM, nebo stavíte vlastní řešení.

Chci použít existující integraci​

Pokud chcete využít zavedené platformy, Dronetag podporuje několik hotových integrací:

Integrace, které Dronetag v současnosti nabízí:

Data Push umí doručovat i vlastní formáty Dronetagu, mezi nimi DUMP JSON, DUMP JSON Typed a Dronetag Legacy JSON. Hodí se tehdy, když místo napojení na některou z výše uvedených platforem stavíte vlastní integraci. Doporučené kombinace najdete na stránce Protokoly a formáty.

Chci si postavit vlastní integraci​

Pro vlastní řešení nebo nové integrace nabízíme několik možností:

Pokud si nejste jisti, který způsob integrace je pro vás ten pravý, podívejte se na návod Výběr vhodného způsobu integrace.

Integrace přes naše API je přímočarý způsob, jak si programově vyměňovat informace se systémy nebo službami třetích stran. Nabízíme dva hlavní způsoby.

Stahování dat z našeho API​

Když si data z našeho API stahujete (pull), získáte aktuální informace přesně ve chvíli, kdy je potřebujete. Pro běžné požadavky nabízíme HTTP REST API, pro přístup k datům v reálném čase Socket.io. Tento způsob se hodí pro integrace typu server–klient, vlastní skripty a další aplikace.

Posílání dat z našich systémů do vašeho API​

Pro trvalejší řešení si můžete nastavit datový tok, při kterém naše systémy posílají (push) provoz v reálném čase přímo do vašeho API, jakmile dorazí na naše servery. Data se tak průběžně aktualizují, aniž byste se museli neustále dotazovat. Tento způsob je vhodný pro integrace typu server–server.

Naše cloudová platforma podporuje služby InterUSS, které umožňují výměnu letových dat s distribuovanými systémy UTM. Pokud váš systém už protokol InterUSS implementuje, s velkou pravděpodobností si s naší platformou data vyměňovat dokáže a integrace bude jednoduchá.

Když váš systém pracuje ve stejné instanci DSS (Distributed Situational Awareness) jako náš, mohou si obě platformy data přímo vyměňovat, což usnadňuje koordinaci provozu.

Více informací najdete na oficiálním webu InterUSS Platform.

Aktuálně podporované služby:

• Remote ID
• Strategic Deconfliction (strategické řešení konfliktů)
• Geo-awareness (geografické povědomí)

Pokud potřebujete náš hardware integrovat přímo, bez cloudových služeb, máte k dispozici několik možností.

Integrace do stávajících systémů na palubě​

Některé naše produkty jsou přímo navržené pro integraci do stávajících systémů. Podrobný postup najdete v uživatelské příručce k danému produktu:

• Integrační příručka pro Dronetag DRI
• Integrační příručka pro Dronetag BS

Integrace přes Bluetooth​

Všechna zařízení Dronetag používají standardní datové formáty Remote ID, které odpovídají pravidlu FAA o dálkové identifikaci bezpilotních letadel (Remote Identification of Unmanned Aircraft Systems) a normě ASTM F3411-22. Jsou tak kompatibilní s ostatními zařízeními i s předpisy.

Pokud chcete data Remote ID přijímat přímo přes Bluetooth, můžete si napsat vlastní aplikaci, která signály vysílané našimi zařízeními dekóduje podle normy.

Upozorňujeme, že SDK pro dekódování Remote ID ani dokumentaci k našim proprietárním charakteristikám Bluetooth neposkytujeme. Máte-li konkrétní projekt, který byste s námi chtěli probrat, neváhejte nás kontaktovat.

REST API se nejlépe hodí k získání aktuálních i historických telemetrických dat a k přístupu k datům účtu, jako jsou prostředky (assets), zařízení, letadla a další. Protože si data musíte sami vyžádat, není příliš vhodné pro streamování dat v reálném čase. Pro data v reálném čase doporučujeme naše endpointy Socket.io.

Získání přihlašovacích údajů k API​

Pro přístup k našemu API se musíte ověřit. Máte dvě možnosti:

1. Osobní token: Osobním tokenem získáte přístup k datům na svém účtu Dronetag. Vytvoříte ho v naší aplikaci nebo přes API.
2. OpenID Connect: OIDC slouží k pokročilejšímu ověřování a umožní vaší aplikaci přistupovat k soukromým datům jiných uživatelů.

Používání API​

Jakmile máte přihlašovací údaje, můžete API začít používat. Doporučujeme se nejprve seznámit s dokumentací API, která popisuje všechny dostupné endpointy a datové struktury, se kterými budete pracovat.

Datový formát DUMP​

Naše API používá řadu datových schémat, každé pro konkrétní prostředek API. Jedno z nich se ale napříč našimi službami používá nejjednotněji: formát Dronetag Unified Message Protocol (DUMP). Pokud pracujete s daty Remote ID, je pro vás porozumění tomuto protokolu obzvlášť důležité.

Připravili jsme podrobný návod, který rozebírá strukturu zpráv DUMP a vysvětluje, jak s nimi efektivně pracovat:

Podmínky pro parametry telemetrických požadavků​

Při telemetrických požadavcích na endpointy vzdušného prostoru (/v2/airspace/*) musíte vždy zadat časový rozsah (from a to) i geografickou oblast (bbox).

Z tohoto pravidla existuje několik výjimek:

• Pokud zadáte operation_id, žádné další parametry nejsou potřeba.
• Pokud zadáte uas_id, můžete vynechat geografickou oblast bbox, časový rozsah je ale stále povinný.

Velikost bbox je omezená a je určená pro středně velké oblasti. Pomocí bbox nelze pokrýt velká území, jako jsou celé státy, kontinenty nebo celý svět.

Pokud je pro vás tato podmínka problémem, doporučujeme podívat se na způsoby, jak vám data posíláme (Data Push).

Další návody​

Pro běžné případy použití našeho API máme několik dalších návodů. Ať už chcete získat aktuální stav vzdušného prostoru, nebo historická data, najdete v nich vše potřebné:

Další návody najdete v levém postranním panelu.

API Socket.io je určené ke streamování telemetrických dat v reálném čase a poskytuje jen živé aktualizace (žádná historická ani absolutní data). Data, která zmeškáte během odpojení, se znovu neposílají — aktuální stav nebo chybějící data po opětovném připojení získáte přes REST API. Tento návod vás provede navázáním spojení v reálném čase mezi Dronetagem a vaší aplikací přes Socket.io.

Parametry spojení​

Ke spojení použijte ve svém klientovi Socket.io tyto konfigurační parametry:

• Host: https://api.dronetag.app
• Path: /v2/airspace/socket.io
• Verze klienta: v3 nebo v4

Výběr klienta Socket.io​

Socket.io podporuje řada knihoven v mnoha programovacích jazycích. Úplný seznam podporovaných klientských implementací najdete zde.

Ověření relace​

Relaci Socket.io ověříte stejným přístupovým tokenem, jaký používáte pro požadavky na REST API. Jak přístupový token získat, popisuje návod k přihlašovacím údajům k API.

Ověření není povinné. Relace bez tokenu dostává jen veřejně dostupná data, ověřená relace navíc i data, ke kterým má přístup váš účet.

Pokud pošlete neplatný token, server spojení odmítne a váš klient dostane connect_error se zprávou unauthorized.

Nativní ověření v Socket.io​

U klientů, které podporují nativní ověřování Socket.io, můžete přístupový token předat přímo v konfigurační volbě auth.

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  auth: "eyJhbGciOiJSUzI1NiIsInR5c...",
});

Více o ověřování v Socket.io najdete v dokumentaci Socket.io.

Bearer token v úvodním požadavku (handshake)​

Pokud váš klient volbu auth nepodporuje, můžete přístupový token poslat v hlavičce Authorization úvodního požadavku (handshake):

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  extraHeaders: { Authorization: "Bearer eyJhbGciOiJSUzI1NiIsInR5c..." }
});

Hodnota hlavičky musí mít tvar Bearer <token>, jinak server spojení odmítne se zprávou wrong bearer token format.

Tento postup se hodí i při testování v nástrojích, jako je Postman, které nativní ověřování obvykle nepodporují. Stačí přidat hlavičku Authorization na kartě Headers v Postmanu.

Ověření navázaného spojení​

Ověřit můžete i spojení, které už je navázané: pošlete přístupový token v události authenticate. Server ji potvrdí odpovědí {"result": "ok"}. Je-li token neplatný, server odpoví {"result": "not_authenticated"} a spojení zůstane otevřené jako neověřené, takže dostává jen veřejně dostupná data.

Odběr událostí​

Po připojení můžete naslouchat těmto událostem:

• serverinfo – posílá se jednou, hned po navázání spojení. Obsahuje informace o serveru, například server_version, environment a your_sid (ID vaší relace, jak ho vidí server).
• telemetry_ua – telemetrie bezpilotního letadla (UA)
• telemetry_operator – telemetrie operátora
• telemetry_system – systémová telemetrie
• operation – změny operací

Každá událost telemetry_ua, telemetry_operator, telemetry_system a operation nese pole zpráv DUMP, ne jednu zprávu. Telemetrické události jsou omezené na nastavený viewport (viz níže), události operation viewport neomezuje. Událost operation nese zprávy OperationUpdate, které obsahují jen nedávné změny operace, ne její úplný stav.

Nejaktuálnější a úplný seznam dostupných událostí, jejich obsahu a odpovědí najdete v naší dokumentaci AsyncAPI.

Nastavení a aktualizace výřezu (viewport)​

Stejně jako u REST API musíte zadat geografickou oblast, o kterou se vaše aplikace zajímá.

Po připojení musí váš klient poslat úvodní událost viewport, která určí sledovanou geografickou oblast. Kdykoli se oblast zájmu změní, musí klient oblast aktualizovat novou událostí viewport. Každá událost viewport nahradí dříve nastavený viewport. Pokud viewport nenastavíte, relace nedostane telemetrii z žádné oblasti.

Viewport platí jen pro jedno spojení. Při každém připojení i opětovném připojení ho klient musí poslat znovu.

Viewport je řetězec ve tvaru lon_min,lat_min,lon_max,lat_max — zeměpisná délka a šířka ve stupních, oddělené čárkami bez mezer. Viewport nastavený například na Prahu může vypadat takto: emit("viewport", "14,49.9,15,50.3").

V aplikacích Dronetagu se například mapa dynamicky posouvá podle toho, co uživatel dělá. Po navázání spojení pošle aplikace úvodní viewport a při posouvání mapy ho aktualizuje. Doporučujeme tyto aktualizace tlumit (debounce), aby klient neposílal nový viewport při každém drobném posunu mapy.

Viewport vždy nastavujte uvážlivě. Musí pokrýt celou oblast vašeho zájmu, ale zároveň nesmí být zbytečně velký — dostávali byste data, která nechcete, a mohly by nastat problémy s výkonem. Doporučujeme přidat na každé straně dostatečnou rezervu několika kilometrů. Největší podporovaná plocha viewportu je zhruba 6 milionů km², takovým extrémním hodnotám se ale raději vyhněte.

Server každou událost viewport potvrdí jednou z těchto odpovědí:

• {"result": "ok"} – viewport je nastavený.
• {"result": "invalid-param", "messages": [...]} – viewport nemá očekávaný tvar nebo jsou jeho hodnoty mimo povolený rozsah.
• {"result": "bbox_area_too_large", "messages": [...]} – plocha viewportu přesahuje největší podporovanou plochu. Dál platí dříve nastavený viewport.

Odpověď přečtete tak, že při odeslání události předáte callback pro potvrzení (acknowledgement), například socket.emit("viewport", "14,49.9,15,50.3", (response) => console.log(response)).

Řazení telemetrie​

Ve výchozím stavu je telemetrie v každé události seřazená vzestupně podle času. Řazení můžete pro každou telemetrickou událost změnit událostí ordering. Jejím obsahem musí být řetězec v kódování JSON, který názvům událostí přiřadí jednu z těchto hodnot:

• time – vzestupně (výchozí)
• -time – sestupně

socket.emit("ordering", JSON.stringify({
  telemetry_ua: "-time",
  telemetry_operator: "time",
  telemetry_system: "time",
}));

Server událost potvrdí odpovědí {"result": "ok"}, nebo {"result": "invalid-param", "messages": [...]}, pokud obsah není platný. Stejně jako viewport platí i řazení jen pro jedno spojení.

Ukázky kódu​

Níže je několik krátkých ukázek, které vám se Socket.io pomohou začít v různých programovacích jazycích:

const { io } = require('socket.io-client');

const socket = io('https://api.dronetag.app', {
  path: '/v2/airspace/socket.io',
  auth: 'eyJhbGciOiJSUzI1NiIsInR5c...'
});

socket.on('connect', () => {
  // The viewport must be sent after every (re)connect
  socket.emit('viewport', '14,49.9,15,50.3', (response) => {
    console.log('Viewport response:', response);
  });
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

socket.on('telemetry_ua', (batch) => {
  for (const telemetry of batch) {
    console.log('UA telemetry received:', telemetry);
  }
});

import socketio

sio = socketio.Client()

@sio.event
def connect():
    # The viewport must be sent after every (re)connect
    sio.emit(
        'viewport',
        '14,49.9,15,50.3',
        callback=lambda response: print(f'Viewport response: {response}'),
    )

@sio.event
def connect_error(data):
    print(f'Connection error: {data}')

@sio.event
def telemetry_ua(batch):
    for telemetry in batch:
        print(f'UA telemetry received: {telemetry}')

sio.connect(
    'https://api.dronetag.app',
    socketio_path='/v2/airspace/socket.io',
    auth='eyJhbGciOiJSUzI1NiIsInR5c...'
)

sio.wait()

Na této stránce se dozvíte, jak ověřovat požadavky, abyste získali přístup k prostředkům na účtech Dronetag.

Nabízíme dva způsoby ověřování: osobní přístupové tokeny (Personal Access Tokens, PAT) a OpenID Connect. Každý se hodí pro jiné použití, proto si přečtěte, který lépe odpovídá vašemu projektu.

Osobní přístupové tokeny (Personal Access Tokens, PAT)​

Pokud chcete pracovat s vlastními daty ze svého účtu Dronetag — například je dodatečně zpracovávat, vytvořit si vlastní nástroj pro příkazovou řádku (CLI) nebo data převádět do jiného softwaru —, nabízíme pro jednoduchý a přímý přístup k API osobní přístupové tokeny (PAT).

Tyto tokeny jsou snadno použitelné, ale méně bezpečné. Pro robustnější integrace určené veřejnosti doporučujeme spíše OpenID Connect.

Vytvoření nového tokenu​

{
    "password": "hunter2",
    "expires_at": "2025-09-09"
}

Nově vydaný osobní přístupový token si bezpečně uložte. Znovu ho už zobrazit nepůjde.

Autorizace požadavků tokenem​

Token nyní můžete při požadavcích posílat v HTTP hlavičce X-Personal-Access-Token.

Příklad požadavku s PAT​

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
X-Personal-Access-Token: 4c5250130bbce349.b0dc901facd944e999b32ebf984c5250130bbce349b0dc901facd944e999b32e

Implementace OpenID Connect​

Když implementujete přihlášení Sign in with Dronetag, umožníte uživatelům přistupovat k jejich datům přes vaši aplikaci. Tento způsob je spolehlivější a nabízí standardizovaný přístup k ověřování.

Co je OpenID Connect (OIDC)​

Naše implementace vychází z OpenID Connect (nezaměňujte s OpenID). Díky OIDC můžete využít existující knihovny a vaše aplikace ho možná už podporuje. Více se dozvíte na webu OpenID Foundation.

Abyste mohli OIDC ve své aplikaci použít, potřebujete vlastní client ID a secret. Pokud jste tyto přihlašovací údaje ještě nedostali, kontaktujte nás.

Implementace ověřování ve vaší aplikaci​

curl -X POST "https://auth.dronetag.app/realms/dcp/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=<your-client-id>" \
-d "client_secret=<your-client-secret>" \
-d "username=<your-username>" \
-d "password=<your-password>"

{
    "access_token": "eyJhbGc...",
    "expires_in": 1200,
    "refresh_expires_in": 604800,
    "refresh_token": "eyJhbGc...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "35d764ee-c27c-4763-bc05-5ffa2e2b822e",
    "scope": "email"
}

Tabulka výše předpokládá, že vaše aplikace už má přidělené „Client ID“ a „Client Secret“. Pro testování můžete použít obecné Client ID dronetag-integration-test, ke kterému secret není potřeba. Pro produkční provoz musí mít každá aplikace vlastní jedinečné Client ID, jinak může být omezen objem stahovaných dat. Přihlašovací údaje vám vydá podpora Dronetagu.

Použití přístupových tokenů​

Osobní přístupové tokeny i přístupové tokeny získané přes OIDC můžete k ověření požadavků na API posílat jako Bearer token v hlavičce Authorization.

Příklad požadavku​

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItQllNT2...

Obnovování tokenů​

Přístupové tokeny vydávané jako JWT mají krátkou platnost a po vypršení je nutné je obnovit. Více o obnovovacích tokenech (refresh token) a jejich bezpečném používání najdete v těchto zdrojích (anglicky):

• What Are Refresh Tokens and How to Use Them Securely - Auth0
• Understanding Refresh Tokens, Access Tokens, and ID Tokens in OIDC Protocol - Logto
• Refresh Access Tokens and Rotate Refresh Tokens - Okta

Telemetrická data ze zařízení Dronetag můžete získávat i tak, že spojení navážou naše servery a data posílají (push) na ty vaše. Tato spojení spravujete v našem portálu integrací, kde si vše nakonfigurujete sami. Portál vám dává plnou kontrolu nad nastavením integrace — můžete zvolit protokol spojení, například HTTP webhooky, MQTT, TCP nebo UDP, snadno přepínat mezi testovacím a produkčním prostředím a upravovat další nastavení podle potřeby.

Jak získat přístup k portálu integrací​

K nastavení integrace Data Push potřebujete přístup k portálu. Ten mají uživatelé s předplatným Pro a obchodní partneři zapojení do našich společných projektů. Pokud o přístup máte zájem, ozvěte se nám.

Portál najdete na adrese https://integrations.dronetag.app.

V přehledném webovém rozhraní integraci nastavíte během několika kroků.

Co lze nastavit?​

Náš integrační systém je navržený tak, aby byl co nejflexibilnější. U každé integrace si můžete sami, bez naší pomoci, upravit řadu parametrů:

• Protokol spojení: HTTP webhooky, MQTT, TCP nebo UDP.
• Cílová adresa: Data můžete směrovat na produkční nebo testovací (staging) endpoint svého API — je to na vás.
• Výstupní formát: Kromě našeho standardního formátu JSON podporujeme i různé systémy UTM. Doporučené kombinace najdete na stránce Protokoly a formáty.
• Omezení provozu (throttling): Abyste nepřetížili své servery, můžete za cenu určitého zpoždění omezit počet požadavků.
• Ověřování: Na výběr je řada způsobů ověřování, mimo jiné HTTP Basic Authentication, vlastní HTTP hlavičky, OAuth 2.0 a další.
• … a další

Nastavení prvního cíle distribuce​

Abyste mohli začít přenášet data, musíte vytvořit cíl distribuce (distribution target). Ten představuje službu, do které chcete data posílat. Cílů můžete vytvořit několik, jejich počet je ale omezený. Jakmile cíl vytvoříte, náš systém do něj bude data automaticky posílat, dokud ho nedeaktivujete nebo neodstraníte.

1. Přihlaste se do portálu integrací svým účtem Dronetag, nebo si vytvořte nový.
2. Na hlavní stránce uvidíte všechny distribuce, které jste vytvořili.
3. Vytvořte nový cíl distribuce tlačítkem Add New.
4. Vyplňte formulář s konfigurací cíle. S nastavením vám pomohou další sekce na této stránce.
5. Cíl uložte a počkejte několik minut, než se změny projeví.
6. Chyby komunikace nebo konfigurace zkontrolujete v serverových lozích. Najděte novou distribuci na hlavní stránce a klikněte na View & Edit.

Pozastavení nebo ukončení distribuce​

Chcete-li dočasně přestat posílat data do svých služeb, distribuci pozastavte tím, že ji označíte jako neaktivní. Pokud distribuci už nepotřebujete, můžete ji trvale smazat.

Co dál?​

• Po nastavení integrace zkontrolujte, zda funguje správně.
• Přečtěte si více o našem formátu DUMP JSON.
• Pokud vám tento způsob integrace nevyhovuje, podívejte se na návod k výběru nejvhodnějšího způsobu integrace.

Každá distribuce Data Push kombinuje dvě nezávislé volby:

• Protokol spojení - jak Dronetag posílá data do vašeho systému.
• Výstupní formát - jak je zakódovaná každá telemetrická zpráva.

Většina formátů je technicky nezávislá na přenosu, ne každá kombinace má ale v praxi smysl. Protokol vyberte podle toho, jak váš systém data přijímá, a formát podle toho, co umí váš cílový systém zpracovat.

Doporučené kombinace​

Matice kompatibility​

Názvy produktů​

Některé integrace jsou známější pod názvem produktu nebo ekosystému než pod svým protokolem a formátem:

Názvy v portálu a možnosti zabezpečení​

Portál integrací používá tyto názvy typů spojení:

Pokud váš přijímač ověřování nevyžaduje, můžete ho nechat prázdné. V této tabulce jsou HTTPS, MQTT over TLS a TLS/mTLS možnosti zabezpečení přenosu a AES data encryption je šifrování obsahu zprávy, nikoli způsob přihlášení. Popisek HTTP Basic Authentication se v portálu používá i pro jméno a heslo k MQTT.

Nastavení mTLS portál zobrazuje jen u distribucí typu TCP Socket. Portál přijímá buď samostatné soubory PEM, nebo balíčky PKCS#12 .p12:

• PEM: certifikát CA, klientský certifikát, soukromý klíč klienta a volitelné heslo ke klíči klienta.
• PKCS#12: truststore .p12 s jedním nebo více certifikáty pro ověření serveru a klientský .p12 s klientským certifikátem a odpovídajícím soukromým klíčem. Každý balíček může mít vlastní volitelné heslo. Portál oba balíčky před použitím v integraci převede do formátu PEM.
• Verify host ověřuje název hostitele serveru proti certifikátu TLS.

Zvolený Data Source (zdroj dat) určuje, které zprávy smí cíl distribuce dostávat, ještě před převodem protokolu nebo formátu. Které typy zpráv umí jednotlivé výstupní formáty odeslat, popisuje stránka Pokrytí zpráv.

Portál nabízí také nastavení doručování:

• Keep reliable určuje chování, když zprávy nelze doručit.
• Throttle messages omezuje, jak často vám Dronetag data posílá.
• Allow mixed content povoluje více typů zpráv v jednom požadavku, pokud to zvolený výstupní formát podporuje.
• Send empty payloads posílá v intervalu omezení prázdný požadavek i tehdy, když nejsou k dispozici žádná nová telemetrická data. Vyžaduje zapnuté omezování (throttling).

Obvyklé sady nastavení​

HTTP Webhooks API​

Použijte pro vlastní API, webhooky a většinu integrací s API partnerů.

Obvyklé nastavení:

• Cílová URL začíná https://.
• Ověřování je HTTP Basic Authentication, OAuth 2.0, způsob specifický pro partnera nebo vlastní HTTP hlavičky.
• Další hlavičky mohou nést klíče API, identifikátory tenantů nebo volbu prostředí.

MQTT Client​

Použijte, když vaše infrastruktura očekává telemetrii v tématech (topics) MQTT.

Obvyklé nastavení:

• Cílová URI a port ukazují na váš broker MQTT.
• Přenos je tcp nebo websockets podle vašeho brokeru.
• Pokud to broker vyžaduje, je nastavené ověřování jménem a heslem.
• Téma může obsahovat {msgtype} pro směrování DUMP JSON.
• QoS je obvykle 0 nebo 1 podle toho, zda je důležitější nízká latence, nebo potvrzení doručení.

TAK / CoT​

Použijte pro TAK Server, ATAK, WinTAK, iTAK nebo middleware kompatibilní s TAK.

Obvyklé nastavení:

• Výstupní formát je Cursor on Target XML.
• Protokol je obvykle TCP nebo UDP socket.
• TCP je vhodnější, když potřebujete stav spojení a spolehlivější doručování.
• UDP je běžné u jednoduchých kanálů CoT, kde občasná ztráta paketu nevadí.
• Pokud váš TAK Server vyžaduje klientské certifikáty, lze u TCP zapnout mTLS.

SAPIENT​

Použijte jen pro systémy, které SAPIENT výslovně implementují.

Obvyklé nastavení:

• Protokol je TCP Socket.
• Výstupní formát je SAPIENT.
• Režim protokolu TCP je sapient.
• Pokud to přijímající uzel vyžaduje, je nastavený interval stavových zpráv (heartbeat).
• Pokud to nasazení SAPIENT vyžaduje, je zapnuté TLS nebo mTLS.

Poznámky k protokolům​

HTTP Webhooks​

HTTP je nejlepší volba, pokud váš systém poskytuje endpoint API. Dronetag posílá na vaši cílovou URL požadavky POST. URL musí začínat http:// nebo https://.

Nešifrované HTTP používejte jen při vývoji a testování. Pro produkční prostředí důrazně doporučujeme HTTPS.

HTTP může přenášet metadata v hlavičkách, například typ obsahu, typ zprávy, client ID integrace a viditelnost veřejných dat. Pro distribuci můžete nastavit i další vlastní HTTP hlavičky.

HTTP používejte pro formáty API specifické pro partnery, například Altitude Angel, ASTRA, Highlander a podobné integrace.

MQTT Client​

MQTT je nejlepší volba, pokud váš systém už provozuje broker MQTT a očekává telemetrii v tématech. Dronetag se připojí jako klient MQTT a převedené zprávy publikuje do nastaveného tématu.

MQTT se dobře hodí pro obsah ve formátu JSON. Pokud používáte DUMP JSON, můžete do názvu tématu vložit {msgtype} a směrovat tak telemetrii UA, telemetrii operátora, systémovou telemetrii a změny operací do samostatných témat.

TCP Socket​

TCP se hodí, když cílový systém očekává trvalé socketové spojení. Je to také doporučený protokol pro SAPIENT a jeden z doporučených protokolů pro TAK Server.

Pro SAPIENT nastavte režim protokolu TCP na sapient. Tím se zapne registrační postup SAPIENT a binární zprávy s délkovou předponou.

TCP může také používat TLS nebo vzájemné TLS (mutual TLS), pokud váš cíl vyžaduje zabezpečení certifikáty.

UDP Socket​

UDP se hodí pro jednoduché doručování bez potvrzení (fire-and-forget), zejména při integraci se systémy, které už kanály UDP přijímají, například některá nasazení TAK.

Protože UDP nepotvrzuje doručení, použijte TCP nebo HTTP, pokud vaše integrace vyžaduje spolehlivější doručování.

Metadata​

HTTP posílá metadata v hlavičkách požadavku. MQTT, TCP a UDP mohou u formátů, kde je to užitečné, metadata volitelně vkládat do obsahu zprávy.

Vložená metadata obalí obsah zprávy objektem s poli data a metadata. Používejte je jen tehdy, když je váš přijímač napsaný tak, aby tuto obálku zpracoval.

Když si nejste jisti​

U vlastních integrací začněte takto:

1. HTTP Webhooks + DUMP JSON, pokud vaše služba může poskytnout endpoint HTTPS.
2. MQTT + DUMP JSON, pokud vaše infrastruktura už MQTT používá.
3. TCP + Cursor on Target XML, pokud se napojujete na TAK Server.
4. TCP + SAPIENT, pokud váš cílový systém SAPIENT výslovně vyžaduje.

Při konfiguraci distribuce v našem portálu integrací narazíte na pole „data source“ (zdroj dat). Tento článek podrobně vysvětluje, co zdroje dat jsou a jak je ve své integraci využít.

Zdroj dat určuje, které zprávy připadají pro cíl distribuce v úvahu. Zvolený výstupní formát může okruh skutečně odesílaných typů zpráv dále zúžit. Podrobnosti najdete na stránce Pokrytí zpráv.

My Account​

Požadavky: žádné
Sdílená data: jen data spojená s účtem vlastníka distribuce

Tento zdroj dat má k dispozici každý, kdo používá portál integrací. Je určený hlavně k počátečnímu testování a vyzkoušení. Když ho zvolíte, získáte přístup jen k datům spojeným se stejným účtem, který distribuci vytvořil (vlastník). Viditelná jsou jen zařízení registrovaná k tomuto účtu, takže data ostatních uživatelů zůstávají soukromá a oddělená.

Device Group​

Požadavky: existující skupina zařízení vázaná na objednávku zařízení Dronetag
Sdílená data: všechna data bez ohledu na nastavení soukromí nebo stav registrace

Device Group (skupina zařízení) je určená zákazníkům, kteří s Dronetagem uzavřeli partnerství a zakoupili skupinu zařízení. Tato zařízení jsou zařazena do předem definované statické skupiny, kterou lze zvolit jako zdroj dat. Členství ve skupině je pevné a lze ho změnit jen na požádání. Běžní uživatelé Dronetagu skupiny zařízení nevidí a nemají k nim přístup.

Partner Integration​

Požadavky: registrace partnerství s Dronetagem
Sdílená data: podle souhlasu uživatelů (opt-in), všechna data bez ohledu na nastavení soukromí

Partnerské integrace (Partner Integration) uživatelé vidí a mají k nim přístup. Plně sami rozhodují, které integrace smějí k jejich datům přistupovat.

Přístup ke svým datům mohou uživatelé každé integraci povolit nebo zakázat v Dronetag App v sekci „Integrations“. Data tak mohou sdílet jen s vybranými integracemi a před ostatními je ponechat soukromá.

Partnerskou integraci lze nastavit tak, aby se uživatele při zapnutí integrace v Dronetag App zeptala na libovolný token, identifikátor nebo autorizační hodnotu. Uživatelé tak mohou zadat přihlašovací údaje nebo identifikátory, které vyžaduje služba třetí strany, a ta pak spolehlivě přiřadí uživatele Dronetagu k vlastním uživatelským účtům nebo autorizačním systémům.

Partnerské integrace zvyšují transparentnost a informovanost uživatelů: uživatelé mohou zůstat v soukromém režimu, a přesto integrace třetích stran využívat. Pro většinu integrací je to doporučený způsob.

Každá partnerská integrace vyžaduje následující údaje, které se pak zobrazují v sekci „Integrations“ v Dronetag App:

• Plný/zobrazovaný název firmy nebo aplikace
• URL loga (volitelné) – vodorovné logo pro lepší rozpoznání značky
• Popis (volitelné) – krátký text o vaší firmě, aplikaci nebo platformě
• URL webu – odkaz na váš web
• Účet správce – účet Dronetag, který bude moci tuto partnerskou integraci vybrat v portálu integrací jako zdroj dat
• Konfigurace Client ID (volitelné) – určuje, zda chcete, aby uživatelé před zapnutím integrace zadali identifikaci

All Public Data (zastaralé)​

Dřívější požadavky: žádné
Sdílená data: všechna veřejná data všech uživatelů Dronetagu (ale ne soukromá data)

Tento zdroj dat dříve umožňoval sdílet všechna veřejná data dostupná v Dronetag App s jakoukoli třetí stranou přes portál integrací.

Kvůli lepší uživatelské zkušenosti a ochraně soukromí byla tato možnost zrušena a už není k dispozici.

Nejběžnější typ distribuce posílá data protokolem HTTP.
Pro každou telemetrickou zprávu se vytvoří nový HTTP požadavek a odešle se na HTTP server vaší služby.

Specifická konfigurace​

Ve specifické konfiguraci lze zatím nastavit jen další HTTP hlavičky.

Příklad specifické konfigurace​

Následuje příklad konfiguračního JSON, ve kterém se pomocí vlastních hlaviček posílá s každým požadavkem Bearer token.

{
  "target_additional_http_headers": {
    "X-My-Custom-Id": "12345"
  }
}

Pokud vaše služba provozuje server brokeru MQTT, můžete použít typ MQTT Client, který se k vašemu serveru připojí a data na něm publikuje.

Specifická konfigurace​

Příklad specifické konfigurace​

Následuje příklad konfiguračního JSON.

{
  "mqtt_dist_client_id": "dronetag_0001",
  "mqtt_dist_transport": "tcp",
  "mqtt_dist_tls": false,
  "mqtt_dist_json_datastream_topic": "dronetag/telemetry/{msgtype}",
  "mqtt_dist_publish_qos_default": 0
}

Použití {msgtype} v názvu tématu​

Pokud používáte formát Dronetag DUMP a chcete posílat různé typy zpráv do různých témat, můžete do názvu tématu vložit zástupný text {msgtype}. Před odesláním se nahradí skutečným typem zprávy. Je-li typem zprávy například „UA telemetry“, z tématu dronetag/telemetry/{msgtype} se stane dronetag/telemetry/tele-ua.

Dostupné typy zpráv:

• tele-ua - zprávy s telemetrií UA
• tele-operator - zprávy s telemetrií operátora
• tele-system - zprávy se systémovou telemetrií
• operation-update - zprávy o změně operace

Více o typech zpráv najdete na stránce Zprávy DUMP.

Doporučení ke konfiguraci​

• Obvykle je nutné nastavit platný Target Port.

Tento typ distribuce posílá data přes obyčejný TCP nebo UDP socket.

Specifická konfigurace​

Příklad specifické konfigurace​

Následuje příklad konfiguračního JSON

{
  "embed_metadata": true
}

Doporučení ke konfiguraci​

• Musí být nastavený 'Target port'
• Pro zabezpečení provozu doporučujeme typ autorizace AES cipher

Data Push používá před odesláním dat do vašeho cíle dva samostatné filtry:

1. Nastavení Data Source (zdroj dat) určuje, které zprávy připadají pro cíl distribuce v úvahu.
2. Nastavení Output Format (výstupní formát) určuje, které z těchto typů zpráv lze v daném formátu vyjádřit a odeslat.

Například cíl se zdrojem dat My account může dostávat jen zprávy, ke kterým má tento účet přístup. Pokud tentýž cíl používá partnerský formát pro polohu UAV, odesílají se jen zprávy o poloze letadla, protože tento formát neumí vyjádřit polohu operátora, systémovou telemetrii ani změny operací.

Typy zpráv podle výstupního formátu​

DUMP JSON a DUMP JSON Typed jsou nejlepší volbou, pokud váš cíl potřebuje úplnou sadu zpráv Data Push.

Systémovou telemetrii lze pro daný cíl vypnout nastavením spojení distribute_system_telemetry.

Po nastavení první distribuce budete nejspíš chtít sledovat, zda funguje správně. Můžete to dělat několika způsoby.

Kontrola stavu v portálu integrací​

Aktuální stav distribuce zjistíte v portálu integrací, kde ověříte, že je distribuce zapnutá a správně nakonfigurovaná.

Po kliknutí na odkaz View & Edit uvidíte podrobnosti, jako je doba provozu (uptime) a statistiky za posledních 24 hodin. Zobrazí se i malý graf s rychlým přehledem, kolik zpráv touto distribucí za tu dobu prošlo.

Monitorování stavu přes Prometheus / OpenTelemetry​

Pokud chcete pokročilejší monitorování včetně historických dat a upozornění, můžete napojit Prometheus, který bude z našeho systému sbírat metriky. Tato funkce je dostupná všem uživatelům portálu integrací a poskytuje podrobná data o každé běžící integraci.

K vizualizaci dat doporučujeme Grafanu.

Získání URL s metrikami​

1. Přihlaste se do portálu integrací svým účtem Dronetag, nebo si vytvořte nový.
2. Najděte cíl distribuce, který vás zajímá, a klikněte na View & Edit.
3. Klikněte na tlačítko Get Prometheus Metrics.
4. Zobrazí se metriky ve formátu Prometheus/OpenMetrics.
5. Tuto URL pravidelně stahujte nástrojem, který vám vyhovuje (podrobnosti v další sekci).

URL vypadá takto:

https://relay.dronetag.app/metrics/[[your_distribution_id]]

Poznamenejte si ID své distribuce.

Sběr metrik pomocí Promethea​

Prometheus je open-source monitorovací systém, který umí náš export metrik sbírat (scrape). Více informací a návod k instalaci najdete v oficiální dokumentaci Promethea.

Doporučená konfigurace, se kterou můžete začít naše metriky sbírat:

global:
  scrape_interval: 10s
scrape_configs:
  - job_name: 'dronetag_distribution_metrics'
    scrape_interval: 10s
    metrics_path: '/metrics/[[your_distribution_id]]'
    static_configs:
      - targets: ['relay.dronetag.app']

Tato konfigurace sbírá metriky každých 10 sekund z URL https://relay.dronetag.app/metrics/[[your_distribution_id]].

Dostupné metriky​

Vizualizace dat v Grafaně​

Grafana je open-source nástroj pro monitorování a analýzu dat, který umí Prometheus používat jako zdroj dat.

Jak Grafanu nainstalovat a nastavit v ní Prometheus jako zdroj dat, popisuje návod 'Get started with Grafana and Prometheus'.

Ukázkový dashboard pro Grafanu​

Připravili jsme jednoduchý ukázkový dashboard pro Grafanu. Soubor JSON můžete importovat do své instance Grafany a upravit podle svých potřeb.

{ "annotations": { "list": [ { "builtIn": 1, "datasource": { "type": "grafana", "uid": "-- Grafana --" }, "enable": true, "hide": true, "iconColor": "rgba(0, 211, 255, 1)", "name": "Annotations & Alerts", "target": { "limit": 100, "matchAny": false, "tags": [], "type": "dashboard" }, "type": "dashboard" } ] }, "editable": true, "fiscalYearStartMonth": 0, "graphTooltip": 0, "id": 47, "links": [ { "asDropdown": false, "icon": "cloud", "includeVars": false, "keepTime": false, "tags": [], "targetBlank": false, "title": "Dronetag Integration Portal", "tooltip": "", "type": "link", "url": "https://integrations.dronetag.app" } ], "liveNow": false, "panels": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "fieldConfig": { "defaults": { "color": { "mode": "thresholds" }, "mappings": [], "thresholds": { "mode": "absolute", "steps": [ { "color": "dark-purple", "value": null } ] }, "unit": "string" }, "overrides": [] }, "gridPos": { "h": 3, "w": 16, "x": 0, "y": 0 }, "id": 3, "options": { "colorMode": "value", "graphMode": "none", "justifyMode": "auto", "orientation": "horizontal", "reduceOptions": { "calcs": [ "lastNotNull" ], "fields": "/^relay_distribution_name$/", "values": false }, "text": { "valueSize": 40 }, "textMode": "value" }, "pluginVersion": "10.1.1", "targets": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "relay_messages_read_created{distribution_id=\"$distribution_id\"}", "format": "table", "instant": false, "legendFormat": "__auto", "range": true, "refId": "A" } ], "transformations": [], "type": "stat" }, { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "fieldConfig": { "defaults": { "color": { "mode": "thresholds" }, "mappings": [], "thresholds": { "mode": "absolute", "steps": [ { "color": "green", "value": null }, { "color": "dark-blue", "value": 80 } ] }, "unit": "dateTimeFromNow" }, "overrides": [] }, "gridPos": { "h": 3, "w": 8, "x": 16, "y": 0 }, "id": 2, "options": { "colorMode": "value", "graphMode": "none", "justifyMode": "center", "orientation": "horizontal", "reduceOptions": { "calcs": [ "lastNotNull" ], "fields": "/^Created$/", "values": false }, "textMode": "value_and_name" }, "pluginVersion": "10.1.1", "targets": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "relay_messages_read_created{distribution_id=\"$distribution_id\"}", "format": "time_series", "instant": false, "legendFormat": "Created at", "range": true, "refId": "A" } ], "transformations": [ { "id": "calculateField", "options": { "alias": "Created", "binary": { "left": "Created at", "operator": "*", "reducer": "sum", "right": "1000" }, "mode": "binary", "reduce": { "reducer": "sum" }, "replaceFields": true } } ], "type": "stat" }, { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "description": "Average rates of sent (distributed) messages. Dotted line shows source input rate, which can be higher if there are filters applied (such as filter to specific device group).", "fieldConfig": { "defaults": { "color": { "mode": "palette-classic" }, "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "bars", "fillOpacity": 100, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "insertNulls": false, "lineInterpolation": "linear", "lineWidth": 0, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "never", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } }, "mappings": [], "thresholds": { "mode": "absolute", "steps": [ { "color": "green", "value": null }, { "color": "red", "value": 80 } ] }, "unit": "mps" }, "overrides": [ { "matcher": { "id": "byName", "options": "Input rate" }, "properties": [ { "id": "custom.lineWidth", "value": 1 }, { "id": "custom.lineStyle", "value": { "dash": [ 2, 6 ], "fill": "dot" } }, { "id": "color", "value": { "mode": "fixed" } }, { "id": "custom.drawStyle", "value": "line" }, { "id": "custom.fillOpacity", "value": 0 } ] } ] }, "gridPos": { "h": 8, "w": 24, "x": 0, "y": 3 }, "id": 1, "interval": "15s", "maxDataPoints": 128, "options": { "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true }, "tooltip": { "mode": "single", "sort": "none" } }, "targets": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "sum(rate(relay_messages_distributed_total{distribution_id=\"$distribution_id\"}[$__rate_interval])) by (distribution_id)", "instant": false, "legendFormat": "Distributed rate", "range": true, "refId": "A" }, { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "sum(rate(relay_messages_read_total{distribution_id=\"$distribution_id\"}[$__rate_interval])) by (distribution_id)", "hide": false, "instant": false, "legendFormat": "Input rate", "range": true, "refId": "B" } ], "title": "Average distribution rate", "type": "timeseries" }, { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "description": "The duration of how long it takes to convert the source input data to the output format. Includes filtering or other data pre-processing.", "fieldConfig": { "defaults": { "color": { "mode": "fixed", "seriesBy": "last" }, "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 0, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "insertNulls": false, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "line" } }, "mappings": [], "thresholds": { "mode": "absolute", "steps": [ { "color": "blue", "value": null } ] }, "unit": "s" }, "overrides": [] }, "gridPos": { "h": 8, "w": 12, "x": 0, "y": 11 }, "id": 4, "interval": "15s", "options": { "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true }, "tooltip": { "mode": "single", "sort": "none" } }, "targets": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "sum(rate(relay_message_conversion_seconds_sum{distribution_id=\"$distribution_id\"}[$__rate_interval]) / rate(relay_message_conversion_seconds_count{distribution_id=\"$distribution_id\"}[$__rate_interval])) by (distribution_id)", "instant": false, "legendFormat": "__auto", "range": true, "refId": "A" } ], "title": "Average conversion duration", "type": "timeseries" }, { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "description": "The duration of how long it takes to distribute the data. The largest part is usually the server latency. Some distribution types can be missing a support for this metric.", "fieldConfig": { "defaults": { "color": { "mode": "thresholds", "seriesBy": "max" }, "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 0, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "insertNulls": false, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "dashed" } }, "mappings": [], "thresholds": { "mode": "absolute", "steps": [ { "color": "blue", "value": null }, { "color": "dark-orange", "value": 0.7 }, { "color": "semi-dark-red", "value": 1 } ] }, "unit": "s" }, "overrides": [] }, "gridPos": { "h": 8, "w": 12, "x": 12, "y": 11 }, "id": 5, "interval": "15s", "options": { "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true }, "tooltip": { "mode": "single", "sort": "none" } }, "targets": [ { "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "editorMode": "code", "expr": "sum(rate(relay_message_distribution_seconds_sum{distribution_id=\"$distribution_id\"}[$__rate_interval]) / rate(relay_message_distribution_seconds_count{distribution_id=\"$distribution_id\"}[$__rate_interval])) by (distribution_id)", "instant": false, "legendFormat": "__auto", "range": true, "refId": "A" } ], "title": "Average distribute duration", "type": "timeseries" } ], "refresh": "", "schemaVersion": 38, "style": "dark", "tags": [ "dronetag" ], "templating": { "list": [ { "current": { "selected": false, "text": "cc2129b7-30e4-469e-8b13-92e7e097d528", "value": "cc2129b7-30e4-469e-8b13-92e7e097d528" }, "datasource": { "type": "prometheus", "uid": "aRT0ZzYnk" }, "definition": "label_values(relay_messages_read_total,distribution_id)", "hide": 0, "includeAll": false, "label": "Distribution ID", "multi": false, "name": "distribution_id", "options": [], "query": { "query": "label_values(relay_messages_read_total,distribution_id)", "refId": "PrometheusVariableQueryEditor-VariableQuery" }, "refresh": 1, "regex": "", "skipUrlSync": false, "sort": 0, "type": "query" } ] }, "time": { "from": "now-1h", "to": "now" }, "timepicker": { "nowDelay": "", "refresh_intervals": [ "5s", "10s", "30s", "1m", "5m" ] }, "timezone": "", "title": "Dronetag Single Distribution Monitoring", "uid": "f2370455-bdac-4098-baf5-ea8857bc199d", "version": 5, "weekStart": "" }

Pokud máte potíže s integrací Data Push nebo s nastavením distribuce, pomůže vám tento návod najít a vyřešit nejčastější problémy.

Časté problémy a jejich řešení​

1. Distribuce neposílá data​

Pokud je distribuce nastavená, ale žádná data se neposílají, zkuste tento postup:

• Zkontrolujte stav distribuce: Přihlaste se do portálu integrací a ověřte, že je distribuce aktivní a správně nakonfigurovaná. Podívejte se do logů, zda v nich nejsou chyby nebo varování.
• Ověřte cílovou adresu: Zkontrolujte, že je cílová adresa (endpoint API, broker MQTT atd.) správná. Otestujte spojení a ověřte, že je vaše služba dosažitelná.
• Firewall nebo síťová omezení: Ověřte, že příchozí data z našich serverů neblokuje firewall ani žádné síťové pravidlo. Zkontrolujte, že jsou otevřené potřebné porty (zejména při použití vlastních portů pro TCP/UDP).

2. Zpožděná data nebo vysoká latence​

Pokud data přicházejí se zpožděním nebo s vysokou latencí, příčinou může být:

• Omezení provozu (throttling): Zkontrolujte, zda nemáte v portálu integrací nastavené omezení provozu. Silné omezení může latenci zvýšit.
• Výkon sítě: Prověřte výkon sítě a dobu odezvy svého serveru. Vysoká latence může být způsobená i pomalým zpracováním na vašem serveru. Latenci požadavků na vaše servery můžete sledovat v našich metrikách pro Prometheus.

3. Chyby ověřování​

Pokud distribuce selhává kvůli chybám ověřování:

• Zkontrolujte způsob ověřování: Ověřte, že je v portálu integrací nastavený správný způsob ověřování (HTTP Basic Authentication, OAuth 2.0, vlastní hlavičky atd.).
• Přihlašovací údaje: Zkontrolujte, že jsou přihlašovací údaje k API nebo tokeny aktuální a ve vaší cílové službě správně nastavené.

4. Neúspěšné doručení zpráv​

Pokud se zprávy nedaří doručit nebo je počet distribuovaných zpráv nižší než počet zpráv na vstupu:

• Zkontrolujte filtry: Systém může některé zprávy podle vaší konfigurace odfiltrovat. Zkontrolujte položku konfigurace Data Source.
• Projděte serverové logy: Hledejte v serverových lozích distribuce chybová hlášení nebo varování. Najdete je v portálu integrací po kliknutí na View & Edit u dané distribuce.
• Problémy se spojením: Pokud je cílová služba mimo provoz nebo nedosažitelná, systém zprávy doručit nemůže. Ověřte, že je vaše služba online a dostupná.

5. Metriky v Prometheu se nezobrazují​

Pokud metriky sbíráte Prometheem, ale nevidíte žádná data:

• URL s metrikami: Zkontrolujte URL s metrikami v konfiguraci Promethea. Musí mít správný tvar: https://relay.dronetag.app/metrics/[[your_distribution_id]].
• Konfigurace Promethea: Projděte konfigurační soubor prometheus.yml a ověřte, že je cesta k metrikám správná a že Prometheus sbírá data ve správném intervalu.
• Chyby distribuce: Pokud se distribuce nedokáže správně spustit nebo selhává, bývá endpoint s metrikami prázdný. V serverových lozích distribuce zkontrolujte, zda běží správně.

Potřebujete další pomoc?​

Pokud tyto kroky problém nevyřeší, obraťte se na naši podporu. Přiložte všechny užitečné podrobnosti, například chybové logy nebo snímky obrazovky, abychom mohli problém rychle diagnostikovat.

Tento návod je určený zákazníkům a partnerům, kteří chtějí řešení Dronetagu zapojit do svých systémů. Najdete v něm podklady a odkazy podle toho, jakou integraci potřebujete.

Než začnete, ujasněte si požadavky na integraci:

• Jaká data potřebujete a v jakých formátech? Jaké protokoly váš systém preferuje?
• V jakém prostředí bude integrace běžet — na straně klienta, na straně serveru, nebo v obou?
• Chcete výměnu dat zahajovat ze svého systému, nebo chcete, aby vám data posílal (streamoval) přímo Dronetag?

Jednorázový import dat do jiné aplikace​

„Chci jen importovat data o svých letech do jiné aplikace.“

Pokud nepotřebujete přístup v reálném čase ani průběžný sběr dat, můžete data z našich aplikací exportovat v otevřených formátech, jako je CSV, KML nebo GPX.

Více o aplikaci Dronetag najdete zde.

Skript pro sběr historických letových dat​

„Chci napsat skript, který stáhne všechna data o mých letech za minulý týden ve formátu KML.“

Pro automatizovaný sběr historických dat umožňuje naše REST API export v několika formátech. Ve výchozím stavu používáme náš formát JSON, můžete si ale vyžádat i CSV, KML, GPX nebo GeoJSON tak, že požadovaný typ MIME uvedete v hlavičce Accept.

Protože budete přistupovat k vlastním zařízením na svém účtu, nejjednodušším způsobem ověřování jsou pro vás osobní přístupové tokeny (Personal Access Tokens).

Podrobnosti najdete v návodu k získání telemetrických dat nebo v naší dokumentaci API.

Data v reálném čase ze všech vašich zařízení​

„Chci svá zařízení Dronetag zobrazovat v reálném čase v jiném softwaru.“

Pokud jsou pro vás prioritou data v reálném čase, doporučujeme buď existující integraci, nebo kombinaci našeho REST API a API Socket.io pro reálný čas.

Podívejte se na stránku Začínáme, kde je seznam aktuálně dostupných integrací s našimi partnery a softwarem třetích stran.

Pokud taková integrace k dispozici není, můžete se napojit na naše REST API a API Socket.io. Protože budete přistupovat k vlastním zařízením na svém účtu, nejjednodušším způsobem ověřování jsou pro vás osobní přístupové tokeny (Personal Access Tokens).

Viz náš návod k získávání dat v reálném čase nebo dokumentace API.

Zobrazení dat uživatelů v klientské aplikaci​

„Mám webovou aplikaci a chci uživatelům Dronetagu umožnit, aby si v ní zobrazovali svá data a spravovali svá zařízení a další prostředky Dronetag.“

Aby si uživatelé mohli prohlížet svá data z Dronetagu ve vaší klientské aplikaci, doporučujeme integrovat OpenID Connect. Uživatelé se pak do vaší aplikace mohou přihlásit přímo svým účtem Dronetag.

Více o ověřování k API.

Sdílení telemetrie uživatelů do serverového řešení​

„Mám cloudové řešení a chtěl bych sbírat data ze zařízení Dronetag jiných uživatelů.“

Pokud máte serverovou aplikaci a chcete v ní uživatelům zpřístupnit jejich telemetrická data, doporučujeme náš portál integrací. Můžete v něm navázat trvalé spojení mezi cloudovou platformou Dronetagu a vaším serverem. Uživatelé pak mohou vaši integraci autorizovat v Dronetag App a telemetrická data z jejich zařízení se začnou posílat na vaše servery.

Začněte návodem Začínáme s Data Push.

Integrace dat U-Space​

Pokud potřebujete integraci se službami U-Space, podporujeme také hlášení do U-Space přes InterUSS. Data můžeme posílat do několika instancí DSS (Discovery and Synchronization Service). Pokud váš systém už protokol InterUSS implementuje, můžeme nejspíš pracovat s vaší stávající DSS nebo vaši instanci DSS zapojit.

Více o integraci s U-Space najdete v naší sekci o InterUSS.

Nenašli jste, co potřebujete?​

Pro běžné použití nabízíme robustní API pro reálný čas. Pokud jsou ale vaše požadavky na integraci složitější, nabízíme v rámci předplatného Enterprise vyhrazenou podporu. Kontaktujte nás a probereme vaše potřeby.

Tento podrobný návod ukazuje, jak po dokončení letů se zařízeními Dronetag získat letová data z našeho API.

Podle toho, jaké údaje o letu máte, existují dva hlavní postupy. Buď si vyžádáte seznam proběhlých letů, jeden vyberete a stáhnete všechna dostupná data k tomuto letu, nebo — pokud znáte jen přibližný čas a místo — si stáhnete výsek historie vzdušného prostoru. Obě možnosti podporuje naše REST API.

Telemetrie jednoho letu​

Tímto postupem získáte úplnou historii telemetrie jednoho konkrétního letu z jednoho zařízení. Odpověď API obsahuje data, která toto zařízení nasbíralo.

1. Ověřte své požadavky na API​

   Nejprve si zajistěte přístup k potřebným prostředkům. Jak ověřovat požadavky na API, popisuje návod k ověřování.

2. Vypište dostupné lety​

   get/v1/flights/ dokumentace API »

   Vyžádejte si seznam dostupných letů spojených s vaším ověřeným účtem Dronetag. Poznamenejte si id letu, který vás zajímá.

3. Vyžádejte si telemetrická data letu​

   get/v2/airspace/telemetry/ua dokumentace API »

   Jako parametr dotazu operation_id použijte id letu. Dostanete telemetrická data vybraného letu, aniž byste museli zadávat časový rozsah nebo geografickou oblast.

   Naše telemetrické endpointy podporují několik výstupních formátů. Zvolte si preferovaný formát a uveďte ho v hlavičce Accept požadavku.

   K dispozici jsou i další telemetrické proudy pro sledování operátora UA nebo systému RID.
   Podrobnosti najdete v návodu k DUMP.

   Poznámka

   Možná narazíte i na endpoint /v1/flights/{id}/telemetry. Doporučujeme ale používat endpoint v2, protože v1 bude postupně ukončen.

Historie vzdušného prostoru​

Tímto postupem získáte historická data o vzdušném prostoru pro zadané místo a časové období.

1. Ověřte své požadavky na API​

   Zajistěte si přístup k potřebným prostředkům. Jak ověřovat požadavky na API, popisuje návod k ověřování.

2. Zvolte parametry​

   Podle údajů, které máte, získáte historii vzdušného prostoru buď:

   • zadáním časového rozsahu (from, to) a geografické oblasti (bbox), nebo
   • zadáním časového rozsahu (from, to) a UAS ID (sériového čísla zařízení, uas_id).

3. Vyžádejte si telemetrická data vzdušného prostoru​

   get/v2/airspace/telemetry/ua dokumentace API »

   Zvolte si preferovaný výstupní formát a uveďte ho v hlavičce Accept požadavku.

   K dispozici jsou i další telemetrické proudy pro sledování operátora UA nebo systému RID.
   Více o těchto typech telemetrie najdete v návodu k DUMP.

4. Vyžádejte si podrobnosti o operaci​

   get/v2/airspace/operation/{operation_id} dokumentace API »

   Předchozí požadavek sice vrací telemetrická data, neobsahuje ale všechny informace o letu, například identifikaci a typ UA. Další podrobnosti získáte z endpointu Operation API, který vrací úplnější informace o operaci.

Tento návod vysvětluje, jak získat a zobrazit telemetrii v reálném čase. Obvykle se ke sledování dění ve vzdušném prostoru v reálném čase kombinuje REST API a Socket.io pro reálný čas.

1. Ověřte své požadavky na API​

   Zajistěte si potřebný přístup k prostředkům. Podrobný postup najdete v návodu k ověřování.

2. Nastavte parametry sledování​

   Rozhodněte se, zda chcete sledovat určitou geografickou oblast (bbox), nebo konkrétní zařízení (uas_id).

   Poznámka: Geografická oblast má svá omezení. Velká území, jako jsou kontinenty nebo státy, sledovat nelze. Podrobnosti najdete v návodu k REST API.

3. (Volitelné) Úvodním požadavkem zjistěte stav vzdušného prostoru​

   get/v2/airspace/telemetry/ua?from=-00:05:00&bbox=... dokumentace API »

   Než začnete přijímat aktualizace v reálném čase, doporučujeme stáhnout výchozí stav vzdušného prostoru, podle kterého aplikace nastaví svůj počáteční stav. Stáhněte například data o vzdušném prostoru za posledních 5 minut jako výchozí bod pro sledování v reálném čase.

4. Přijímejte aktualizace telemetrie v reálném čase​

   Možnost 1: Připojení k Socket.io pro aktualizace v reálném čase​

   wswss://api.dronetag.app/v2/airspace/socket.io telemetry_ua dokumentace API »

   Přes Socket.io dostáváte aktualizace v reálném čase s nízkou latencí a nemusíte řešit parametry časového rozsahu v dotazu. Pro aplikace, které mají rychle reagovat, je to preferovaná možnost.

   Možnost 2: Opakované dotazování REST API​

   get/v2/airspace/telemetry/ua?from=$last_date&bbox=... dokumentace API »

   Aktualizace můžete také získávat pravidelným dotazováním API (polling). Pro aplikace, které potřebují časté aktualizace, je ale tento přístup méně efektivní.

   Pokud zvolíte tuto možnost, použijte v dalších voláních jako parametr from hodnotu hlavičky Date z poslední odpovědi (je nutné ji převést do ISO 8601). Vyhnete se tak duplicitním datům.

   Nedoporučujeme

   Opakované dotazování se pro vysokou frekvenci aktualizací obecně nehodí. Při dotazování tohoto endpointu s vysokou frekvencí (> 1 za sekundu) může dojít k chybám kvůli omezení počtu požadavků (rate limiting).

5. Zjistěte podrobnosti o operaci​

   Telemetrická data sice poskytují informace o letu v reálném čase, nemusí ale obsahovat důležité podrobnosti, jako je identifikace a typ UA. Další informace si můžete vyžádat o samotné operaci.

   Možnost 1: Naslouchání změnám operací přes Socket.io​

   wswss://api.dronetag.app/v2/airspace/socket.io operation dokumentace API »

   Přes Socket.io můžete naslouchat kanálu operation, kde dostanete aktualizaci, když vznikne nová operace nebo se změní existující. Výpadky sítě ale mohou způsobit ztrátu dat, proto je nejlepší tento způsob kombinovat s občasnými HTTP požadavky, aby aplikace zůstala synchronizovaná.

   Možnost 2: HTTP požadavky podle potřeby​

   get/v2/airspace/operations/{operation_id} dokumentace API »

   Podrobnosti o operaci si můžete podle potřeby vyžádat přes Operation API pomocí operation_id. Dostanete uložené informace o operaci ve vzdušném prostoru.

6. Udržujte výřez (viewport) aktuální​

   Pokud vaše aplikace zobrazuje dynamickou mapu nebo se oblast zájmu v čase mění, aktualizujte parametr dotazu bbox v požadavcích na API, případně při použití Socket.io posílejte události viewport.

   Více informací najdete v dokumentaci API a v návodu k Socket.io.

V reálném čase máte k dispozici i další telemetrické proudy pro sledování operátora UA nebo systému RID. Podrobnosti najdete v návodu k DUMP.

Tento návod vysvětluje, jak v reálném čase sledovat stav zařízení Dronetag, například nabití baterie, sílu signálu LTE a GNSS a další důležité ukazatele. Data můžete získávat přes REST API nebo přes API Socket.io pro reálný čas.

Rozdíly oproti ostatním typům telemetrie​

Na rozdíl od ostatních telemetrických dat, jako je Telemetry-UA nebo Telemetry-Operator, která se posílají často, se telemetrie o stavu systému zařízení (Telemetry-System) posílá zpravidla v delších intervalech — obvykle jednou za 10 až 15 sekund nebo i méně často.

Více o všech typech telemetrie najdete v návodu k DUMP.

Sledování konkrétního zařízení podle UAS ID​

Ke zjištění stavu zařízení Dronetag v reálném čase musíte použít UAS ID zařízení, které odpovídá jeho sériovému číslu. Na rozdíl od ostatních typů telemetrie, které lze sledovat podle geografické oblasti (pomocí bbox), tento endpoint sledování podle geografické oblasti nepodporuje. Pro přístup k datům konkrétního zařízení musíte zadat jeho UAS ID.

1. Ověřte své požadavky na API​

   Ověřením požadavků na API si zajistěte přístup k potřebným prostředkům. Podrobnosti o ověřování najdete v návodu k ověřování.

2. Určete zařízení podle UAS ID​

   Než začnete posílat požadavky, zjistěte UAS ID (sériové číslo) zařízení, které chcete sledovat. UAS ID najdete na samotném zařízení Dronetag, v nastavení účtu v Dronetag App nebo v jiných odpovědích API.

3. Vyžádejte si data o stavu systému v reálném čase​

   Možnost 1: Získání dat přes REST API​

   K datům o stavu zařízení v reálném čase přes REST API použijte tento endpoint:

   get/v2/airspace/telemetry/system dokumentace API »

   Parametr dotazu uas_id nastavte na sériové číslo zařízení Dronetag a časový rozsah určete parametrem from, případně from a to.

   Možnost 2: Aktualizace v reálném čase přes API Socket.io​

   Zatím není k dispozici

   Tato možnost zatím není k dispozici

   wswss://api.dronetag.app/v2/airspace/socket.io telemetry_system dokumentace API »

   Pro aktualizace v reálném čase se přes Socket.io připojte ke kanálu telemetry_system. Tento způsob přináší aktualizace s nižší latencí než opakované dotazování REST API.

Všechny cloudově připojené produkty Dronetag lze integrovat s TAK Serverem přes náš portál integrací a streamovat jejich data Remote ID ve formátu Cursor on Target (CoT) přímo na váš TAK server v reálném čase.

Zařízení se síťovým Remote ID (NRI), například Dronetag Mini, mohou streamovat polohu UA. Přijímače přímého Remote ID (DRI), například Dronetag RIDER nebo Dronetag Scout, mohou navíc streamovat polohu operátora a polohu samotného přijímače.

Co budete potřebovat​

Než začnete, ověřte, že máte:

• účet Dronetag (vytvoříte ho na https://dronetag.app/signup),
• podporovaný produkt Dronetag (jeden nebo více) registrovaný k vašemu účtu
  • podporované jsou Dronetag Mini, Dronetag Mini 4G, Dronetag RIDER a Dronetag Scout,
• aktivní předplatné Pro nebo Enterprise (nutné pro přístup k portálu integrací),
• instanci TAK Serveru
  • s veřejně dostupným endpointem TAK Serveru (IP adresa nebo doménové jméno).

Postup nastavení​

1. Nakonfigurujte svůj TAK Server​

   Před nastavením integrace připravte TAK Server:

   1. Otevřete potřebný port ve firewallu
   2. Nastavte TAK Server tak, aby na tomto portu přijímal datové kanály
   3. Poznamenejte si údaje pro připojení:
      • IP adresu nebo doménu serveru (např. tak.yourcompany.com nebo 203.0.100.200)
      • číslo portu (např. 8087)

   Pokud konfiguraci TAK Serveru neznáte, podívejte se do oficiální dokumentace TAK Serveru.

2. Otevřete portál integrací​

   Přejděte na https://integrations.dronetag.app a přihlaste se svými přihlašovacími údaji

3. Vytvořte novou distribuci​

   Vytvořte novou distribuci s touto konfigurací:

   Povinná nastavení​

   • Connection type — TCP nebo UDP Socket
   • Target URI — adresa vašeho TAK Serveru (např. tak.yourcompany.com nebo 203.0.100.200)
   • Target port — port vašeho TAK Serveru (např. 8087)
   • Output format — Cursor on Target XML

   Ostatní volby ponechte ve výchozím stavu, nebo je upravte podle svých potřeb. Ne všechny volby se ale integrace TCP+XML týkají.

   Výběr zdroje dat​

   Všimněte si, jaký zdroj dat je zvolený. Výchozí „My account“ streamuje data ze všech zařízení registrovaných k vašemu účtu. Další možnosti jsou „Device Groups“ (statický seznam zařízení) a „Partnered Integration“ (umožňuje kterémukoli uživateli Dronetagu sdílet data na váš TAK server). Podrobnosti vám sdělíme na požádání.

   Volitelné ověřování mTLS​

   Pokud váš TAK Server vyžaduje vzájemné ověřování TLS (mutual TLS), zapněte volbu mTLS a nahrajte potřebný klientský certifikát a soubory se soukromým klíčem ve formátu PEM. Tato volba je dostupná jen pro spojení TCP.

4. Ověřte spojení​

   • Počkejte 2–3 minuty, než se integrace inicializuje a naváže spojení
   • Zapněte zařízení Dronetag a ověřte, že aktivně vysílá
   • Otevřete klienta TAK (ATAK, WinTAK nebo iTAK) a zkontrolujte, že se na mapě v místě zařízení objevila ikona dronu
   • Ověřte, že se poloha aktualizuje v reálném čase

Řešení problémů​

Pokud máte potíže, zkuste tyto kroky v uvedeném pořadí:

1. Ověřte spojení s TAK Serverem — Zkontrolujte, že je IP adresa nebo doména TAK Serveru správná a veřejně dostupná a že pravidla firewallu povolují příchozí spojení na zadaném portu.

2. Zkontrolujte stav zařízení — Ověřte, že je zařízení Dronetag zapnuté, má přesnou polohu z GNSS, je ve stavu „Online“ a je vidět na mapě ve vašem účtu na https://dronetag.app.

3. Projděte logy v portálu integrací — Podívejte se do sekce „Server logs“ v portálu integrací a několikrát zobrazení obnovte (logy se neaktualizují v reálném čase). Hledejte chyby spojení nebo stavová hlášení.

4. Dejte inicializaci čas — Integrace potřebuje k navázání spojení 2–3 minuty. Pokud problémy trvají i potom, restartujte distribuci v portálu integrací tak, že ji vypnete a znovu zapnete.

Pokud problémy přetrvávají, kontaktujte podporu a přiložte serverové logy a údaje o konfiguraci.

Související zdroje​

• Začínáme s integracemi Data Push
• Oficiální dokumentace TAK Serveru
• Kontaktujte podporu Dronetagu

V našem API narazíte u bodů letové telemetrie na tři různé hodnoty výšky. Tato sekce vysvětluje, co tyto hodnoty představují, jak se získávají a jak je můžete ve svých aplikacích využít.

Hodnoty výšky​

• WGS84 HAE (Height Above Ellipsoid) — výška nad elipsoidem WGS84 v metrech

  • Jde o surovou výšku, kterou hlásí přímo vnitřní přijímač GNSS v zařízení Dronetag.
  • Představuje výšku nad elipsoidem (nikoli nad geoidem ani nad střední hladinou moře). Někdy se mylně vykládá jako MSL, WGS84-HAE však udává výšku nad elipsoidem, ne nad hladinou moře.
  • Přesnost této výšky se může měnit podle podmínek příjmu signálu GNSS a podle omezení modelu Země uloženého v přijímačích GNSS.
  • V API je k dispozici jako HAE-WGS84

• QNE (Pressure Altitude) — tlaková výška vypočtená z barometrického tlaku, v metrech

  • Tato hodnota se počítá z palubního barometru při standardním tlaku na hladině moře 1013,25 hPa (QNE).
  • Je velmi přesná pro relativní měření, například pro porovnání výšek blízkých dronů, nemusí ale odpovídat přesné absolutní výšce nad terénem.
  • V letectví se často používá pro standardní údaje o výšce, zejména při letu ve větších výškách, kde atmosférický tlak klesá předvídatelně.
  • V API je k dispozici jako PA-QNE

• ATO (Above Takeoff Level) — výška nad místem vzletu, v metrech

  • Tato hodnota se počítá jako rozdíl mezi aktuální QNE (tlakovou výškou) a tlakovou výškou v okamžiku vzletu.
  • Udává relativní výšku nad výchozím místem vzletu, což se hodí ke sledování změn výšky během letu.
  • Hodnoty ATO jsou citlivé na změny atmosférického tlaku v čase, takže se jejich přesnost může při delších letech nebo výrazné změně počasí zhoršovat.
  • Pokud se prostředí nemění a let začal na zemi, lze tuto výšku někdy chápat jako AGL (výšku nad terénem).
  • V API je k dispozici jako ATO

Časté dotazy​

Proč neexistuje spolehlivá výška AGL (nad terénem)?​

Výšku AGL nenabízíme, protože naše zařízení nemají senzory, které by dokázaly kdekoli na světě přímo měřit vzdálenost k zemi nebo terénu. Bez konzistentních a přesných údajů o tlaku nebo nadmořské výšce na úrovni terénu by byl výpočet skutečné výšky AGL nespolehlivý.

Uživatelé si ale mohou výšku AGL odhadnout sami, pokud mají pro svou oblast k dispozici spolehlivé údaje o tlaku na úrovni terénu. Surové hodnoty tlaku hlášené zařízením pak mohou porovnat se známým tlakem na úrovni terénu a výšku odhadnout.

Proč moje výška ATO někdy ukazuje záporné hodnoty?​

Pole ATO se počítá vzhledem k tlakové výšce zaznamenané při vzletu. Záporné hodnoty mohou mít dvě hlavní příčiny:

1. Tlak při vzletu: Pokud začnete let sledovat, až když je dron už ve vzduchu (např. 10 m nad zemí), tlak při vzletu odpovídá této výšce. Po přistání pak výška ukáže zápornou hodnotu (např. -10 m), protože dron je níž než původní místo vzletu.

2. Změny tlaku v čase: Atmosférický tlak se během dne mění podle počasí. Pokud sledujete dlouhý let trvající hodiny, může výška postupně ujíždět, protože referenční tlak při vzletu už neodpovídá aktuálnímu tlaku u země. To může vést k nesprávným údajům, zejména u dlouhých letů.

Proč můj komerční dron ukazuje výšku AGL, ale Dronetag ne?​

Většina komerčních dronů ve skutečnosti výšku AGL neukazuje. Používá podobný princip jako naše ATO (výška nad místem vzletu): řídicí jednotka dronu zaznamená tlak při vzletu a pak zobrazuje rozdíl mezi výškou vzletu a aktuální výškou. Ten se prezentuje jako výška dronu nad zemí, i když je to technicky jen výška vzhledem k místu vzletu, nikoli skutečná AGL.

DUMP (Dronetag Unified Message Protocol) je interní formát zpráv Dronetagu, který jednotně používají všechny naše služby. Ať pracujete s naším REST API, se Socket.io, nebo s integrací přes náš portál, můžete se spolehnout, že standardním formátem pro výměnu dat je DUMP.

Aktuální verze je DUMP v1.

DUMP podporuje tyto typy zpráv:​

• Operation ⏺︎
• OperationUpdate ⏺︎
• Telemetry-UA ⏺︎ (často zkracováno jako TELE-UA)
• Telemetry-Operator ⏺︎ (TELE-Operator)
• Telemetry-System ⏺︎ (TELE-System)

Podrobnosti o těchto typech zpráv, včetně toho, kdy a jak se používají, najdete níže.

Typy zpráv DUMP​

Operation (nebo OperationUpdate)​

📋 Úplné schéma JSON najdete v naší dokumentaci API

Zpráva Operation obsahuje statické informace o konkrétním letu. Tato data se oddělují do objektu operace proto, aby se v každé telemetrické zprávě neopakovaly neměnné informace, jako je sériové číslo dronu nebo ID modulu Remote ID (RID).

Jedna operace nemusí vždy odpovídat přesně jednomu letu. Pokud se let zaznamenává několika systémy — například kombinací síťového Remote ID a pozemních přijímačů přímého Remote ID —, může být rozdělen do více operací.

Rozdíl mezi Operation a OperationUpdate je podstatný. Zpráva Operation představuje úplný stav letu v okamžiku požadavku a vrací se při dotazu přes REST API. Naproti tomu zprávy OperationUpdate představují dílčí změny, které se posílají hlavně v reálném čase (např. přes Socket.io nebo přes náš portál integrací). OperationUpdate obsahuje jen nedávné změny, ne celý stav.

Příklad​

{
  "id": "a45cb00e-b600-4111-bd52-42537c28feb3",
  "status": "current",
  "uas_operator_id": "FIN87astrdge12k8",
  "ua_classification": "class1",
  "ua_classification_type": "open",
  "ua_identifiers": [
    {
      "type": "serial_number",
      "value": "15968AB92D361"
    },
    {
      "type": "caa_assigned",
      "value": "JA.JU12345ABCDE"
    }
  ],
  "authentication": [],
  "descriptions": []
}

Telemetry-UA​

📋 Úplné schéma JSON najdete v naší dokumentaci API

Zpráva Telemetry-UA je hlavní datový objekt pro Remote ID. Zachycuje okamžitou geografickou polohu bezpilotního letadla (UA), jeho stav a další údaje, které vyžadují předpisy o Remote ID.

Každá zpráva Telemetry-UA je přes pole operation_id přiřazena k jedné zprávě Operation. Každé zařízení s Remote ID během provozu generuje zprávy Telemetry-UA.

Příklad​

{
  "operation_id": "a45cb00e-b600-4111-bd52-42537c28feb3",
  "timestamp": "2024-10-05T10:15:06.100Z",
  "timestamp_accuracy": 0.1,
  "operational_state": "airborne",
  "location": {
    "latitude": 50.073873, "longitude": 14.466586, "accuracy": 50
  },
  "altitudes": [
    { "type": "WGS84", "value": 192.5, "accuracy": 10 },
    { "type": "QNE", "value": 323.1, "accuracy": 0.5 },
    { "type": "AGL", "value": -10.0, "accuracy": 0.5 }
  ],
  "velocity": {
    "heading": 92, "horizontal_speed": 9.72, "vertical_speed": 1.22, "speed_accuracy": 0.5
  },
  "air_pressure": 1017.712
}

Telemetry-Operator​

📋 Úplné schéma JSON najdete v naší dokumentaci API

Zpráva Telemetry-Operator sleduje polohu operátora. Některé systémy UAV hlásí polohu pilota v reálném čase prostřednictvím svého ovládacího vybavení. Drony se standardním Remote ID mohou poskytovat sledování operátora, kdežto moduly Remote ID obvykle hlásí jen místo vzletu.

Příklad​

{
  "operation_id": "a45cb00e-b600-4111-bd52-42537c28feb3",
  "timestamp": "2024-10-05T10:15:06.100Z",
  "timestamp_accuracy": 0.1,
  "location": {
    "latitude": 50.073873, "longitude": 14.466586, "accuracy": 50
  },
  "altitude": { 
    "type": "WGS84", "value": 202.5, "accuracy": 10
  },
  "source_type": "take_off"
}

Telemetry-System​

📋 Úplné schéma JSON najdete v naší dokumentaci API

Zpráva Telemetry-System nese informace o stavu samotného modulu Remote ID, nikoli letadla. Obsahuje údaje o nabití baterie, připojení GNSS, signálu LTE a dalších parametrech systému. Zprávy Telemetry-System zatím generují jen zařízení Dronetag.

Příklad​

{
  "operation_id": "a45cb00e-b600-4111-bd52-42537c28feb3",
  "timestamp": "2024-10-05T10:15:06.100Z",
  "timestamp_accuracy": 0.1,
  "system_type": "rid_module",
  "system_status": "operational",
  "power_source": {
    "type": "battery",
    "input_voltage": 4.11,
    "charge_percentage": 90,
    "is_being_charged": false
  },
  "lte_connectivity": {
    "status": "connected",
    "rsrq": -10,
    "rsrp": -97,
    "snr": 9,
    "tac": "291E",
    "cell_id": "555CA02"
  },
  "gnss_connectivity": {
    "status": "connected",
    "satellites": 12
  }
}

The Dronetag ATAK Plugin connects a Dronetag RIDER to ATAK (Android Team Awareness Kit) over a USB-C cable or Bluetooth LE — no cellular data or cloud connectivity required. Every drone (and pilot) detection decoded by RIDER appears as a live track on the ATAK map and is shared with the rest of your TAK network via CoT (Cursor on Target).

Because it works entirely over USB or Bluetooth, the plugin keeps working in terrain with poor or no cellular coverage — exactly where RIDER and ATAK are most often used together.

Prerequisites​

Before you begin, make sure you have:

• ATAK-CIV installed, version 5.6.0 or later (check under Settings → About ATAK)
• Android 11 or later
• A Dronetag RIDER, with a USB-C cable or paired over Bluetooth LE

Installing the plugin​

The plugin is distributed through the Play Store, under the Dronetag developer account:

Install it like any other Android app. Because it's an ATAK plugin, not a standalone app, it won't appear with its own icon on your home screen — opening it always happens from inside ATAK.

Checking that the plugin loaded​

The first time a new plugin is installed, ATAK requires you to approve it before it loads. Open Settings → Tool Preferences → Package Management:

Look for Dronetag ATAK Plugin in the list:

• Loaded (green, checked) — the plugin is active and ready to use.
• Unloaded / unchecked — tap the checkbox next to it to load it.

Main UI​

Once loaded, the plugin adds a Dronetag tile to ATAK's tools menu (the hamburger icon in the top toolbar → Tools). It sits near the end of the tools grid, after the built-in tools:

Tapping it opens the Dronetag side panel, which is your main interface — a running list of all current detections, and a Device Manager button in the top-right corner to manage your RIDER connection:

Connecting your RIDER​

Open Device Manager (top-right of the Dronetag panel) to manage connections:

• USB cable — turn this on and plug your RIDER in with a USB-C cable. ATAK will prompt for USB permission the first time.
• Test beacon — see Using the test device below.
• Scan for devices — searches for nearby RIDERs over Bluetooth LE and lists any found so you can connect:

Information displayed​

Tap any entry in the detections list to open its detail page:

This shows everything decoded from the drone's Remote ID broadcast: status, UID, serial number, callsign, affiliation, the technology used (Bluetooth or Wi-Fi), signal strength, position, altitude, height above ground, speed, vertical speed, heading, and when it was first/last seen. If the broadcast includes a pilot location, a separate pilot marker appears on the map linked to the same drone.

From this page you can also:

• Callsign — set a custom callsign for this detection, overriding the default name:

  

• Details — look up the maker, model, and specifications of the aircraft, when identifiable from its serial number

• Show on map — center the map on this detection

• Back — return to the detections list

Using the test device​

The Test beacon, toggled on from Device Manager, simulates a synthetic drone orbiting your own location — no real RIDER or real drone required. It's useful for:

• Verifying connectivity: confirming the full pipeline (plugin → ATAK → CoT → your TAK server) works before you need it in the field
• Demonstrating the plugin: showing a team how detections look and behave without waiting for real air traffic

It behaves exactly like a real detection — it appears in the list, has a position and heading, and can be renamed or inspected the same way — so it's a safe way to learn the UI before your first real deployment.

Settings​

The plugin's own settings live under Settings → Tool Preferences → Specific Tool Preferences → Dronetag ATAK Plugin:

Detections

• Mark stale after — how long a detection can go without an update before it's shown as stale on the map
• Remove after — how long before a stale detection is removed from the list and map entirely

Callsigns — see below.

Working with the Callsign list​

Instead of naming detections one at a time, you can bulk-assign callsigns and affiliations from a CSV file:

1. Prepare a CSV with one row per known drone:

   SN,Callsign,{friendly,hostile,neutral}
   

   For example:

   1596M0170424A1234,Patrol 1,friendly
   1596M0170424A5678,Unknown Contact,hostile
   

2. Go to Settings → Tool Preferences → Specific Tool Preferences → Dronetag ATAK Plugin → Callsign CSV file, and pick the file using ATAK's file browser.
3. The plugin matches detections to rows by serial number, applying the callsign and affiliation from the matching row.

A few things worth knowing:

• The CSV is reloaded automatically whenever the file changes — no need to reselect it after an edit.
• A manual callsign set from a detection's detail page (see Information displayed) always takes priority over the CSV for that detection.
• If a detection's serial isn't in the CSV, it falls back to a generated name (Drone <last 4 characters of serial>).
• Clear callsign CSV stops using the file entirely — all detections fall back to their default names and affiliations.

Dronetag nabízí simulační nástroj Mocker, se kterým můžete během vývoje testovat svou integraci bez fyzického zařízení. V Mockeru vytvoříte virtuální lety a ověříte, že váš systém data z Dronetagu správně přijímá a zpracovává.

👉 https://mocker.dronetag.app

Co budete potřebovat​

• Účet Dronetag — pokud ho nemáte, vytvořte si ho zdarma
• Virtuální zařízení Mocker registrované k vašemu účtu (viz níže)
• Přístup k aplikaci Mocker — obvykle ho dostanete spolu s prvním virtuálním zařízením

Získání virtuálních zařízení​

Virtuální zařízení získáte, když nás kontaktujete a uvedete údaje o svém účtu Dronetag. Virtuální zařízení pro testování a vývoj zpravidla rádi poskytneme. Jakmile je virtuální zařízení registrované k vašemu účtu, můžete s ním simulovat lety a testovat svou integraci.

Vytvoření simulace​

Mocker podporuje dva simulační engine podle typu zařízení, které chcete simulovat:

Simulace zařízení NRI (nri_via_live)​

Simulace NRI napodobuje zařízení, které do sítě hlásí vlastní polohu. Stačí jeden identifikátor, protože simulované zařízení hlásí samo sebe.

1. Otevřete aplikaci Mocker a přihlaste se
2. Klepnutím kamkoli do mapy umístěte novou simulaci
3. Zvolte engine nri_via_live
4. Vyberte letový scénář
5. V poli UAS Identifier vyberte jedno ze svých zařízení Mocker — bude fungovat jako zařízení NRI
6. Nastavte zbývající parametry zvoleného scénáře a klikněte na Create

Simulace přijímače DRI (dri_via_funnel)​

Simulace přijímače DRI napodobuje zařízení, které detekuje letadla s Remote ID ve svém okolí a hlásí je. Potřebuje dva identifikátory: jeden pro přijímač a jeden pro detekované letadlo.

1. Otevřete aplikaci Mocker a přihlaste se
2. Klepnutím kamkoli do mapy umístěte novou simulaci
3. Zvolte engine dri_via_funnel
4. Vyberte letový scénář
5. Do pole UAS Identifier zadejte libovolné platné sériové číslo Remote ID podle ANSI — představuje letadlo, které váš přijímač detekuje
6. V poli Sensor ID vyberte jedno ze svých zařízení Mocker — bude fungovat jako přijímač DRI
7. Nastavte zbývající parametry zvoleného scénáře a klikněte na Create

Ovládání simulací​

Vytvořené simulované zařízení se objeví na mapě a v levém postranním panelu. V postranním panelu můžete simulaci:

• Pause — pozastavit
• End — řádně ukončit
• Force kill — násilně ukončit; použijte jen k otestování situace se ztrátou spojení

Dronetag exports flights and detections in a few file formats. The formats are the same wherever you export from, for example the Dronetag App, the Dronetag Export service or your own software through the Dronetag API. This section describes the files. What you can choose in each place is described on that place's own page, such as Exporting Data in the Dronetag App.

This page helps you pick a format.

A flight is reported by a Dronetag device on your own drone. A detection is a drone that one or more of your receivers heard, for example a Dronetag Scout. Flights and detections use the same file formats. A detection fills in a few extra fields, such as which receiver heard it.

Pick a Format​

KML is the same map as KMZ, but without the icons and the colour legend. Google Earth shows its own default pins instead. Choose KML only if a tool can't open KMZ.

With Tracks or Summary​

JSON and CSV come in two versions. You pick one when you export.

• With tracks has every recorded position. This is the default.
• Summary has one entry per flight or detection, without the positions.

The figures in a Summary are still calculated from the whole track. Choose Summary when you export many flights. For 80 flights, a Summary is a few hundred kilobytes and With tracks is tens of megabytes.

Units and Times​

JSON and CSV always use metres, metres per second, degrees and seconds. Their times are in UTC.

KMZ and PDF use metric units, or imperial ones where the place you export from lets you choose. Their times are also in UTC, marked "(UTC)".

File Names​

Detections say operations or operation instead of flights or flight. A Summary ends in -summary instead of -telemetry. A zip has the same name with the extension .zip. Dates and times in file names are in UTC.

Format Versions​

JSON, CSV Telemetry and CSV Summary are all version 1.0, and each has its own version. When something is only added, the second number goes up. When something is removed, renamed or changes meaning, the first number goes up. If your software reads JSON, read schema_version and check the first number before you read the rest.

When You Get a Zip File​

A CSV can arrive in a zip together with a file called ATTRIBUTION.txt. This happens when heights in the CSV were calculated from terrain data that must be credited. Keep the two files together when you pass the data on. See Terrain Data and Attribution.

Some places also put several formats, or a large selection split into parts, into one zip.

Files Safe to Share Publicly​

Some places can make a file that is safe to share publicly. The file then leaves out the pilot's name and ID, the pilot's positions and the take-off point. It also leaves out the callsign, the Self-ID text, the return-to-home point and the receivers that heard a detection.

Serial numbers keep their first four and last four characters. Registration numbers and operator IDs are hidden completely. The drone's own track stays in the file.

Example Files​

The examples on these pages come from these files. They are synthetic. Every name, serial number, receiver and registration in them is invented.

In a real download the file names follow the pattern under File Names, and each of these CSVs would arrive in a zip with its ATTRIBUTION.txt.

CSV Telemetry is the CSV you get with With tracks. It has one row for every recorded position. The file name ends in -telemetry.csv.

Flights and detections use the same 15 columns in the same order. A column that one kind never fills stays empty.

Columns​

The five altitude columns are explained in Altitudes Explained.

An empty cell means the value wasn't reported and Dronetag couldn't calculate it. A real zero, such as the speed of a hovering drone, is written as zero and never left empty.

CSV has no accuracies. If you need to know how exact a value is, use JSON.

Facts about the aircraft and the pilot are in CSV Summary. Its id column holds the same value as operation_id, so you can join the two files.

Example​

The first row of the example flight and of the example detection (synthetic data):

operation_id,timestamp,serial_number,sensor_id,operational_state,latitude,longitude,horizontal_speed,vertical_speed,heading,alt_hae_wgs84,alt_ato,alt_pressure,alt_msl,alt_agl
3f6b1c2e-8d4a-4b7f-9e21-5a0c7d3e9b14,2026-09-17T07:42:13.350390Z,1596CEXAMPLE00001,,,49.1679989,16.4950113,0.0,0.0,,327.1,0.08,255.81,282.13207082568454,0.43031044931819906
6d2f8a41-93c7-4e0b-b5d2-1f7a9c3e8b60,2026-09-22T15:31:04.048000Z,1581FEXAMPLE00000004,SCT-EXAMPLE-01,grounded,49.9599978,14.4999964,0.0,0.0,0.0,400.3,0.0,327.7,354.9,1.0917571914229143

The flight row has no receiver and no state. The detection row has both.

Opening It in Excel​

A CSV is written in one of two styles. Some places let you choose the style when you export.

• Decimal point writes 1.5 and separates columns with commas. It suits English-language Excel, Numbers and LibreOffice.
• Decimal comma writes 1,5 and separates columns with semicolons. It suits Czech, German and most other European set-ups.

When the style matches your Excel, double-click the file and it opens in columns. Accents and the degree sign display correctly.

If everything lands in one column, the file was written in the other style. Import it instead.

1. In Excel, choose Data → From Text/CSV and pick the file.
2. Set the delimiter to comma or semicolon.
3. If numbers come out as text, choose Transform Data, select the columns and use Change Type → Using Locale.

Numbers keep every digit the source reported. Format the cells in Excel if you want fewer decimals.

Reading It in a Program​

The file is UTF-8 with a byte order mark. In Python, open it with encoding="utf-8-sig". Lines end in CRLF and times end in Z (UTC). Numbers have full precision and no thousands separators. The header always has the same 15 columns.

If You Get a Zip File​

When alt_msl or alt_agl came from terrain data that must be credited, the CSV arrives in a zip with ATTRIBUTION.txt. Keep the two files together. See Terrain Data and Attribution.

CSV Summary is the CSV you get with Summary. It has one row for each flight or detection. It doesn't contain the positions. The file name ends in -summary.csv.

Flights and detections use the same 37 columns in the same order. The figures are calculated from the whole track, exactly as in a With tracks export.

Columns​

The Who column says which kind fills the column. F means flights, D means detections.

Identity​

Aircraft and Operator​

When​

Where​

The first and last positions are where the record starts and ends. They are often not the take-off and landing, because a receiver starts hearing a drone when it comes into range.

How Far and How Fast​

operator_track_kind tells you what the pilot position is. operator is the pilot's real position. take_off means the drone sent only its take-off location, so the distances are measured from there. mixed is some of each.

Altitudes​

There are no minimums. See Altitudes Explained.

Status Values​

Only in JSON​

CSV Summary keeps to the fields most people need. These are only in JSON:

• Accuracies.
• Start and end times as the source states them. These can differ from the first and last position.
• The return-to-home point and the declared operation area of a flight.
• Rare identifiers, the Self-ID text and the flight's colour.

Example​

One example flight and one example detection (synthetic data):

id,status,sensor_ids,serial_number,callsign,caa_assigned,aircraft_manufacturer,aircraft_model,aircraft_category,ua_classification,uas_operator_id,pilot_id,pilot_name,message_count,duration,time_first_telemetry,time_last_telemetry,take_off_latitude,take_off_longitude,first_latitude,first_longitude,last_latitude,last_longitude,min_latitude,max_latitude,min_longitude,max_longitude,point_count,total_distance,max_horizontal_speed,operator_track_kind,max_operator_distance,operator_movement_extent,transmission_technologies,max_alt_ato,max_alt_msl,max_alt_agl
3f6b1c2e-8d4a-4b7f-9e21-5a0c7d3e9b14,finished,,1596CEXAMPLE00001,EXAMPLE-FLIGHT-1,,,DJI Matrice 350 RTK,,,CZEexampleoper01,9b6b1c2e-8d4a-4b7f-9e21-5a0c7d3e9b14,Tomáš Example,,260.963047,2026-09-17T07:42:13.350390Z,2026-09-17T07:46:34.313437Z,49.1679989,16.4950113,49.1679989,16.4950113,49.168003,16.4949982,49.167991,49.1699201,16.4949881,16.4979653,262,1373.6529667703585,10.14401301260995,,,,,80.33,364.0258824461374,83.32078650204227
6d2f8a41-93c7-4e0b-b5d2-1f7a9c3e8b60,past,SCT-EXAMPLE-01|SCT-EXAMPLE-02,1581FEXAMPLE00000004,,OK-UAS-EXAMPLE-4,DJI,DJI Mavic 3,rotorcraft,open class_1,CZEexampleoper04,,,194,192.977,2026-09-22T15:31:04.048000Z,2026-09-22T15:34:17.025000Z,,,49.9599978,14.4999964,49.9599977,14.4999876,49.9599864,49.9620193,14.4999838,14.5036452,194,973.7599886011964,12.16,operator,261.9408504975598,44.46384785221796,wifi_beacon|wifi_nan,95.1,449.4,97.37793678299658

The same columns for three flights. The detection-only columns stay empty.

Joining It With CSV Telemetry​

id here and operation_id in CSV Telemetry hold the same value. Put both files in one workbook, with the summary on a sheet called Summary. In the telemetry sheet, add a column with this formula:

=XLOOKUP(A2, Summary!A:A, Summary!H:H)

It copies aircraft_model (column H) into each position row. If your Excel separates formula arguments with semicolons, use semicolons instead of the commas.