Komunikace v systému ACASYS Programátorská příručka Verze 1.05 acasys-ks_ms_cz_105
AMiT, spol. s r. o. nepřejímá žádné záruky, pokud se týče obsahu této publikace a vyhrazuje si právo měnit obsah dokumentace bez závazku tyto změny oznámit jakékoli osobě či organizaci. Tento dokument může být kopírován a rozšiřován za následujících podmínek: 1. Celý text musí být kopírován bez úprav a se zahrnutím všech stránek. 2. Všechny kopie musí obsahovat označení autorského práva společnosti AMiT, spol. s r. o. a veškerá další upozornění v dokumentu uvedená. 3. Tento dokument nesmí být distribuován za účelem dosažení zisku. V publikaci použité názvy produktů, firem apod. mohou být ochrannými známkami nebo registrovanými ochrannými známkami příslušných vlastníků. AMiT je registrovaná ochranná známka. Copyright (c) 2012, AMiT, spol. s r. o. Výrobce: AMiT, spol. s r. o. Naskové 3/1100, 150 00 Praha www.amit.cz Technická podpora: support@amit.cz acasys-ks_ms_cz_105 2/15
Obsah Historie revizí... 4 Související dokumentace... 4 1. Úvod... 5 2. Popis protokolu... 6 2.1. IP adresy a porty... 6 2.2. Komunikace typu dotaz-odpověď (Q-A)... 6 2.3. Komunikace typu zásilka (Parcel)... 6 2.4. Výběr typu komunikace... 7 2.5. Struktura rámců... 7 3. TRUD KS... 9 3.1. Princip činnosti IP monitoru... 9 4. Aplikační profil CU-IPM... 10 4.1. Rámec TxCU-RxIPM... 10 4.2. Rámec TxIPM-RxCU... 10 5. Aplikační profil CU-RU... 13 5.1. Rámec TxCU-RxRU... 13 5.2. Rámec TxRU-RxCU... 14 6. Aplikační profil IS-RU... 15 6.1. Rámec TxIS-RxRU... 15 6.2. Rámec TxRU-RxIS... 15 3/15 acasys-ks_ms_cz_105
Historie revizí Jméno dokumentu: acasys-ks_ms_cz_105.pdf Autor: O. Stančík Verze Datum Změny 100 02. 08. 2012 Nový dokument 101 29. 10. 2012 Vysílací porty nastaveny na Implementačně nezávislé v souladu s aktuální implementací Doplnění informací k polím s gps polohou u TxCU-RxRU 102 22. 11. 2012 Konfigurace scén Doplnění CAMS_MASK 103 01. 12. 2012 Kontrola pravopisu, aktualizace šablony dokumentu, drobné korekce textu v kapitolách 3.1 Příklad, 4.1 popis Backlight, 4.2 popis Backlight, 5.1 GPS_xxx. 104 03. 07. 2013 Rozšíření rámce TxRU-RxCU 105 27. 09. 2013 Oprava délky rámce TxIPM-RxCU Související dokumentace 1. Projekční příručka ACASYS-KS Modulární kamerový systém soubor: acasys-ks_mp_cz_xxx.pdf 2. Uživatelská příručka AcasysStudio Prohlížeč videozáznamů z jednotky PPM2000 soubor: acasysstudio_ms_cz_xxx.pdf acasys-ks_ms_cz_105 4/15
1. Úvod Tento dokument popisuje komunikační rozhraní mezi kamerovým systémem ACASYS-KS a okolními jednotkami. Komunikační protokol je označován názvem TRUD. Kamerový systém se sestává z IP monitorů, IP kamer a záznamové jednotky. IP monitory zobrazují video stream z kamery nebo z více kamer. Záznamová jednotka zaznamenává obraz většinou ze všech kamer ve sníženém fps (frames per second). IP monitory nebo záznamová jednotka mohou v kamerovém systému chybět. 5/15 acasys-ks_ms_cz_105
2. Popis protokolu Základní charakteristika Aplikační profil Protokol typu klient/server, postavený na linkové vrstvě Ethernet v2 (RFC 1191) a transportní vrstvě UDP (RFC768). Vícebajtové datové typy jsou kódovány v Little endian. Každý rámec TRUD je přepravován právě jedním UDP paketem. Do jednoho UDP paketu tedy nelze vkládat více rámců TRUD a také není podporováno dělení jednoho rámce TRUD do více UDP paketů (pozn. netýká se fragmentace na úrovní vrstvy IP). V aplikačním profilu jsou stanoveny základní parametry komunikace. Aplikační profil je popsán dále. 2.1. IP adresy a porty IP adresy zařízení mohou být součástí aplikačního profilu nebo mohou být definovány v jiném dokumentu. Přidělení portů je součástí aplikačního profilu. 2.2. Komunikace typu dotaz-odpověď (Q-A) Dotaz odesílá klient na server ve formě tzv. rámce dotazu. Odpověď odesílá server na základě obsahu příslušného dotazu ve formě tzv. rámce odpovědi. Výpadek komunikace klient detekuje timeout při čekání na odpověď. Velikost timeoutu je definována v aplikačním profilu. Algoritmus výměny Komunikace je dána posloupností výměn dotazů a odpovědí v čase. Algoritmus jedné výměny probíhá jinak u klienta a jinak u serveru. Z pohledu klienta: 1. Sestavení rámce dotazu. 2. Odeslání rámce dotazu na server. 3. Čekání po dobu timeoutu na odpověď serveru na odeslaný rámec. 4. Pokud před uplynutím čekací doby dorazila odpověď na odeslaný rámec, klient může zpracovat obsah odpovědi. V opačném případě došlo k výpadku UDP a odesílání je třeba zopakovat. Z pohledu serveru: 1. Čekání na rámec dotazu od klienta. 2. Sestavení rámce odpovědi v závislosti na obsahu dotazu. 3. Odeslání rámce odpovědi klientovi. 2.3. Komunikace typu zásilka (Parcel) Jedna stanice zasílá na adresu druhé rámec s příslušnými daty bez požadavku na potvrzení příjmu. Vysílající stanice tiše předpokládá, že protější stanice data přijímá. Komunikace může probíhat i opačným směrem a stanice si takto acasys-ks_ms_cz_105 6/15
mohou vzájemně kontrolovat svůj provoz (ne však doručení konkrétního balíku). Tento způsob komunikace je určen pro periodické zasílání dat. 2.4. Výběr typu komunikace 2.5. Struktura rámců Struktura rámců Pro komunikaci s určitým uzlem musí byt stanoven typ komunikace a tento typ komunikace nelze měnit v run-time. Q-A je určena pro komunikaci při změně hodnot, komunikace Parcel je určena pro periodické zasílání dat. V obou dvou případech je používána stejná hlavička, pouze její význam se mění. Každý rámec TRUD se sestává z hlavičky a nákladu, jehož struktura a obsah závisí na aplikaci a může být i kompletně vynechán. Struktura hlavičky je však pevně definována. Velikost hlavičky je 8 bajtů a nejvyšší povolená velikost nákladu je nastavena na 1446 bajtů. Společně s hlavičkami jednotlivých vrstev MAC, IP a UDP je využita celková kapacita rámce Ethernet v2 1500 bajtů. Položka Typ Q-A P FLG U16 Typ rámce Typ rámce bit#0 1 0 bit#1 1 Dotaz Bez významu 0 Odpověď bit#2 až 15 Bez významu Bez významu LEN U16 Délka nákladu v bajtech Délka nákladu v bajtech ID U16 Identifikátor typu dotazu Identifikátor typu rámce SEQ U16 Identifikátor výměny Bez významu PLD - Náklad (struktura závisí na typu dotazu) Příznaky Identifikace Význam SEQ Generování SEQ Položka FLG představuje prostor pro specifikaci šestnácti různých příznaků. Nultý bit s hodnotou 1 udává typ komunikace Q-A, opačně typ komunikace P. Bit 1 udává specifikaci dotazu či odpovědi a je zaveden především pro servisní/ladící účely. Stanice jsou však při typu komunikace Q-A povinny tento bit správně vyplnit. Další bity jsou bez významu a předpokládá se jejich nulová hodnota. Pole ID určuje typ dotazu/rámce a tedy význam rámce či obsah datové části PLD. Účelem položky SEQ je odlišit od sebe jednotlivé výměny. Klient by ji měl nastavit na takovou hodnotu, aby podle ní dokázal určit příslušnou odpověď (rámec SEQ s příslušnou odpovědí totiž bude obsahovat její kopii). Tímto mechanizmem se eliminují nežádoucí efekty, které by mohly nastat vlivem záměny pořadí UDP paketů během transportu nebo přijímáním odpovědí, kterým mezitím u klienta vypršela čekací lhůta. Systém generování hodnot SEQ v dotazech je záležitostí klienta, úkolem serveru je pouze tyto hodnoty zkopírovat do příslušných odpovědí. K využití se nabízí 7/15 acasys-ks_ms_cz_105
např. generátor náhodných čísel s rovnoměrným rozložením či nějaká forma kontrolního součtu obsahu paketu v kombinaci s pořadím opakování dotazu. Doporučeným a zároveň nejjednodušším algoritmem je obyčejný čítač výměn. U komunikace typu Parcel je pole SEQ ignorováno. Náklad Datové typy Strukturu nákladu rámce dotazu PLD určuje hodnota ID. Položka LEN pak udává velikost nákladu v bajtech a její hodnota se musí pohybovat v intervalu 0 až 1446. V popisu protokolu jsou používány názvy datových typů s následujícím významem. Označení Typ Velikost (bit) U8/I8 Integer neznaménkový/znaménkový 8 U16/I16 Integer neznaménkový/znaménkový 16 U32/I32 Integer neznaménkový/znaménkový 32 F32 Float 32 CSTR Řetězec znaků o proměnlivé délce ukončený binární nulou Datové typy jsou kódovány v Little Endian. Řetězcové rozšíření základních typů je v dalším textu značeno výrazem typ[n], kde typ udává základní typ řetězce a n jeho délku (n je přirozené číslo větší než 0). Kódování znaků (ASCII, UTF-8, Unicode, ) je součástí aplikačního profilu. acasys-ks_ms_cz_105 8/15
3. TRUD KS CU IPM RU IS Tento dokument popisuje komunikaci mezi centrální jednotkou a IP monitory, komunikaci mezi centrální jednotkou a záznamovou jednotkou. Použité zkratky: Centrální jednotka. IP monitor. Záznamová jednotka. Informační systém. 3.1. Princip činnosti IP monitoru IP monitor zobrazuje video stream z jedné nebo více IP kamer. Více obrazů z kamer je na monitoru zobrazováno v dlaždicích o maximálním počtu 4 4 (multi zobrazení). Zobrazení určité kamery nebo kamer musí být pevně předdefinováno a je nazýváno scénou. CU pak pomocí protokolu zasílá informaci do IPM jaká scéna má být aktivní v daný okamžik. Konfiguraci scén a dalších vlastností monitoru udává textový soubor, který se jednorázově nahrává do monitoru protokolem FTP nebo SSH. K vytvoření či úpravě konfiguračního souboru lze použít servisní software ACASYS Configurator. Příklad Máme jeden IPM a dvě kamery na levé a pravé straně. Chceme zobrazovat levou a pravou kameru zvlášť na obrazovce a poté obě kamery dohromady. Levá kamera má IP adresu 192.168.1.1 a pravá kamera má adresu 192.168.1.2. Část konfiguračního souboru, která obsahuje definice streamů podle výše uvedeného příkladu, vypadá následovně: stream=1;axis;192.168.1.1;0;left;left camera stream=2;axis;192.168.1.2;0;right;right camera stream=3;multi2x1;1,2;0;both the left and right camera in a single row Pro zobrazení levé kamery na IPM pošle řídicí jednotka CU rámec TxCU-RxIPM (viz kap. 4.1) s parametrem SCENE nastaveným na hodnotu 1. Zobrazení pravé kamery pak odpovídá hodnota 2 a zobrazení obou kamer najednou hodnota 3 parametru SCENE. 9/15 acasys-ks_ms_cz_105
4. Aplikační profil CU-IPM Způsob komunikace PARCEL Perioda vysílání z CU Implementačně závislá Perioda vysílání z IPM 1 s Port příjmu na CU 55000 Port vysílání na CU Implementačně závislé Port příjmu na IPM 55000 Port vysílání na IPM Implementačně závislé 4.1. Rámec TxCU-RxIPM Rámec vysílá CU, přijímá IPM. Ofs Položka Typ Hodnota Význam 0 FLG U16 0x0000 2 LEN U16 6 4 ID U16 0x0701 Identifikátor rámce RxIPM-TxCU. 6 SEQ U16 Ignoruje se. 8 LIFETIME U8 0 až 255 Inkrementující se čítač, signalizace života CU. 9 SCENE U8 Číslo scény, která se má zobrazit na IPM. 10 BACKLIGHT U8 0 až 100 Nastavení intenzity podsvitu v procentech (po krocích 10 %). 11 CAMDIAG U8 0 Neprovádět diagnostiku připojených kamer. 1 Provádět diagnostiku připojených kamer 12 RX_TM U16 Timeout v s pro příjem RxIPM rámce. RX_TM CAMDIAG Timeout pro příjem rámce RxIPM z CU do IPM. IPM po restartu nastavuje vnitřní čítač na 0. RX_TM nastavuje tuto vnitřní proměnnou. Pokud je různá od nuly, IPM po této době, pokud nepřijme další rámce RxIPM, nastavuje defaultní scénu pokud je definována. Pokud je hodnota 1, pak IPM provádí diagnostiku připojených kamer (ping) a diagnostická data posílá v rámci TxIPM. Je odpovědností CU, aby z dané množiny IPM byla nastavena nejvýše jedna, která tuto diagnostiku bude provádět. 4.2. Rámec TxIPM-RxCU Rámec vysílá IPM, přijímá CU. Ofs Položka Typ Hodnota Význam 0 FLG U16 0x0000 2 LEN U16 36 4 ID U16 0x0700 Identifikátor rámce TxIPM-RxCU. 6 SEQ U16 Ignoruje se. 8 LIFETIME U8 0 až 255 Inkrementující se čítač, signalizace života IPM. 9 SCENE U8 Číslo scény, která se aktuálně zobrazuje na IPM. acasys-ks_ms_cz_105 10/15
10 BACKLIGHT U8 0 až 100 Aktuálně nastavená intenzita podsvitu v procentech. 11 ERROR U8 Kód chyby jednotky: 0 Bez poruchy. 1 Překročena vnitřní teplota jednotky. 2 Vnitřní chyba jednotky. 12 CAMDIAG U8 Kopie pole CAMDIAG z rámce TxCU-RxIPM: 0 neprovádět diagnostiku připojených kamer 1 provádět diagnostiku připojených kamer 13 RESERVED U8 Rezervováno 14 RX_TM U16 Aktuální hodnota vnitřní proměnné hlídající timeout příjmu rámce RxIPM. 16 CAMS U32 Bitové pole výsledku ping na jednotlivé kamery: 0 kamera není testována nebo se neozývá 1 kamera detekována. 20 CAMS_MASK U32 Bitové pole testovaných kamer: 0 kamera není testována 1 kamera je testována. 24 FIRMWARE_ U8 Verze firmwaru videoprocesoru (major). MAJOR 25 FIRMWARE_ U8 Verze firmwaru videoprocesoru (minor). MINOR 26 FIRMWARE_ U16 Revize firmwaru videoprocesoru. REVISION 28 FSG_TOTAL U32 Celkový počet změn stavového kódu dohledového proc. (viz FSG_LATEST). 32 FSG_ERRORS U32 Počet změn stavového kódu dohledového procesoru na chybový kód viz FSG_LATEST). Ke zvýšení hodnoty FSG_ERRORS dochází při přechodu ze stavového kódu 0x00 na libovolný chybový kód nebo při přechodu z chybového kódu na jiný chybový kód. 36 FSG_LATENCY U16 Zpoždění snímku [ms]. 38 FSG_VERSION_ MAJOR U8 Verze aplikace dohledového procesoru (major). 39 FSG_VERSION_ MINOR U8 Verze aplikace dohledového procesoru (minor). 40 FSG_LATEST U8 Stavový kód (hex): 0x00 - normální činnost, není chyba 0x41 - chyba CRC metadat snímku 0x42 - chyba parity metadat snímku 0x43 - chyba toggle metadat snímku 0x44 - chyba identifikátoru metadat snímku 0x45 - nadlimitní zpoždění snímku 0x46 - kontrola vypnuta, provádí se selftest 0x47 - vnitřní chyba dohledového proc. 41 RESERVE1 U8 Rezervováno pro budoucí použití (mo- 11/15 acasys-ks_ms_cz_105
mentálně se hodnota ignoruje). 42 RESERVE2 U8 Rezervováno pro budoucí použití (momentálně se hodnota ignoruje). 43 RESERVE3 U8 Rezervováno pro budoucí použití (momentálně se hodnota ignoruje). RX_TM CAMS CAMS_MASK Pokud je hodnota nulová, je nastavena implicitní scéna. Bitové pole signalizující připojení kamer. Pokud je na příslušném bitu CAMS_MASK nastaven bit, pak na odpovídajícím bitu položky CAMS je výsledek testování připojení kamery. Bitové pole testovaných kamer. Hodnotu sestavuje IPM podle konfiguračního souboru. Pro každý definovaný stream, který odpovídá jedné konkrétní kameře (nikoli tedy multi-stream), se nastaví jeden bit hodnoty CAMS_MASK na jedničku. Pořadí tohoto bitu je dáno výrazem i-1, přičemž i je číselný identifikátor streamu. Pro výše uvedený příklad tří streamů bude mít pole CAMS_MASK hodnotu 0x00000003, tzn. nejnižší dva bity, odpovídající streamům 1 a 2, jsou nastaveny na log. 1. Stream 3 je multizobrazení, takže třetí bit (stejně jako i všechny zbývající) je nastaven na log. 0. Hodnotu CAMS_MASK lze využít pro rychlou detekci výpadku kamery v CU. Platí-li rovnost (CAMS&CAMS_MASK)==CAMS_MASK, pak jsou všechny kamery online. V opačném případě došlo k výpadku nejméně na jedné z kamer. acasys-ks_ms_cz_105 12/15
5. Aplikační profil CU-RU Způsob komunikace PARCEL Perioda vysílání z CU Implementačně závislá Perioda vysílání z RU 1 s Port příjmu na CU 55001 Port vysílání na CU Implementačně závislé Port příjmu na RU 55001 Port vysílání na RU Implementačně závislé 5.1. Rámec TxCU-RxRU Rámec vysílá CU, přijímá RU. Ofs Položka Typ Hodnota Význam 0 FLG U16 0x0000 2 LEN U16 6 4 ID U16 0x0702 Identifikátor rámce TxCU-RxZJ. 6 SEQ U16 Ignoruje se. 8 LIFETIME U8 0 až 255 Inkrementující se čítač, signalizace života CU. 9 CMD U8 Bitově kódovaná zpráva: bit#0 1 SOS aktivace sos události. bit#1 až 7 Rezervováno. 10 VEHICLE U32 Identifikace vozidla. 14 GPS_ I32-180 /180 Zeměpisná šířka ve formátu I32. LATITUDE 18 GPS_ I32-180 /180 Zeměpisná délka ve formátu I32. LONGITUTE 22 TIME U32 Čas ve formátu Unix (počet vteřin od 1. 1. 1970). GPS_xxx Pokud jsou obě dvě pole nulové, je považována gps hodnota za neplatnou. GPS polohu RU neinterpretuje, pouze ji ukládá. Formát je tedy z hlediska RU nevýznamný. K interpretaci dochází až v programu Acasys studio, kterým lze zaznamenaná data zpracovávat. Výchozí formát odpovídá doméně I32 (32 bit znaménkový integer) na rozsahu <-180, +180> stupňů. Rozsah <-2 147 483 648, 2 147 483 647> odpovídá tedy <-180, +180> stupňů. Doporučený přepočet je pak takový, kdy 1 vteřině odpovídá číslo 1000. Výpočty s přesností na 0.001 vteřiny se pak dají provádět v celočíselné aritmetice. Poté rozsah <-180, +180> stupňů odpovídá rozsahu čísel <-648 000 000, 648 000 000>. 13/15 acasys-ks_ms_cz_105
5.2. Rámec TxRU-RxCU Rámec vysílá RU, přijímá CU. Ofs Položka Typ Hodnota Význam 0 FLG U16 0x0000 2 LEN U16 24 4 ID U16 0x0703 Identifikátor rámce TxZJ-RxCU. 6 SEQ U16 Ignoruje se. 8 LIFETIME U8 0 až 255 Inkrementující se čítač, signalizace života IPM. 9 STATE U8 Bitově kódovaná zpráva. bit#0 1 Aktivace SOS události. bit#1 0 Nahrávání zapnuto. 1 Nahrávání vypnuto na žádost CU. bit#2 až 7 Rezervováno. 10 ERROR U8 Signalizace vnitřní chyby RU. 11 RESERVED U8 Rezervováno pro budoucí použití. 12 CAMS U32 Bitové pole záznamu jednotlivých kamer: 0 záznam neběží 1 záznam běží 16 CAMS_MASK U32 Bitové pole připojených kamer: 0 kamera není připojena 1 kamera je připojena. 22 TIME U32 Aktuální čas jednotky ve formátu Unix (počet vteřin od 1. 1. 1970) 26 IS_COUNTER U32 Čítač zpráv z IS. 28 FIRMWARE_ U8 Verze firmwaru (major). MAJOR 29 FIRMWARE_ U8 Verze firmwaru (minor). MINOR 30 FIRMWARE_ REVISION U16 Revize firmwaru. acasys-ks_ms_cz_105 14/15
6. Aplikační profil IS-RU Způsob komunikace PARCEL Perioda vysílání z IS Implementačně závislá Perioda vysílání z RU 1 s Port příjmu na IS Není Port vysílání na IS Implementačně závislé Port příjmu na RU 55002 Port vysílání na RU Není 6.1. Rámec TxIS-RxRU Rámec vysílá IS, přijímá RU. Přijatá data jsou ukládána na disk ve formě metadat. Metadata lze pak používat při práci se záznamy v prohlížecím programu Acasys Studio. Ofs Položka Typ Hodnota Význam 0 FLG U16 0x0000 2 LEN U16 6 4 ID U16 0x0704 Identifikátor rámce TxCU-RxZJ. 6 SEQ U16 Ignoruje se 8 LIFETIME U8 0 až 255 Inkrementující se čítač, signalizace života CU. 9 MSG_TYPE U8 Určuje formu IS_MSG. 10 IS_MSG CSTR C-string Konkrétní podobu řetězce IS_MSG definuje použitý informační systém. IS_MSG==0 Příklad Pro MSG_TYPE==0 má IS_MSG následující formát: IS_MSG má 6 položek, vzájemně oddělených středníkem. Znak středník se nesmí vyskytnout v žádné z položek. Položky jsou následující LINEID DIR STNID STNAME GPGGA Číslo linky. 0 jízda zpět, 1 jízda tam. Číselný identifikátor aktuální stanice. Jméno aktuální stanice v kódování UTF-8. GPS souřadnice ve formátu věty GPGGA. 9;0;;Kobylisy;$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47 Linka 9, směr jízdy zpět, id. stanice není, jméno stanice Kobylisy, GPS poloha v GPGGA formátu. Celý řetězec končí binární nulou. 6.2. Rámec TxRU-RxIS RU do IS nevysílá. 15/15 acasys-ks_ms_cz_105