Ovladač systému REXYGEN pro MAVLink
(modul MAVLinkDrv)
Uživatelská příručka

REX Controls s.r.o.

Verze 2.50.11
Plzeň
19.1.2022

Obsah

Kapitola 1
MAVLink pro systém REXYGEN

1.1 Úvod

V tomto manuálu je popsán MAVLinkDrv – ovladač pro komunikaci protokolem MAVLink v rámci systému REXYGEN. Ovladač byl vyvinut společností REX Controls.

Ovladač umožňuje integrovat komunikaci po protokolu MAVLink do řídicího algorimtu v systému REXYGEN. Současně umožňuje směrování protokolu mavlink po protokolu UDP, TCP nebo sériové lince, tedy funkci, kterou vykonává např. mavlink-router na Intel Aeru nebo MAVROS v systému ROS.

1.2 Základní koncepce

Základní koncepce ovladače je jednoduchá. Zpracovávání příchozích paketů a jejich směrování probíhá v kontextu vlákna ovladače v každém jeho tiku. Zpracování odchozích paketů je prováděno z kontextu vykonávání příslušných bloků. Pokud aplikace využívá funkce směrování, probíhá veškerá komunikace v systému s granularitou tiku ovladače. Pro korektní funkci aplikace jako „Companion computer“ se předpokládá nastavení periody exekutivy na 1-5ms.

Veškerá funkcionalita ovladače je zpřístupněna pomocí funkčních bloků typu RECV a SEND. Pro každou zprávu je definován jeden blok typu RECV (s názvem MAV_RECV_ <command>) a jeden blok typu SEND (s názvem MAV_SEND_<command>).

V aktuální verzi není prováděna synchronizace mezi bloky a výkonnou částí ovladače. Všechny bloky pro příjem je proto nutné umístit do úloh navázaných na příslušný ovladač (tj. pomocí bloku IOTASK). Veškerou vyšší logiku doporučujeme implementovat do subsystémů.

Ovladač podporuje zprávy se skalárními typy. Pole znaků jsou převáděna na STRING o příslušné délce. Pole ostatních typů jsou převáděna na skalární očíslované vstupy/výstupu v příslušném počtu. Bloky s polem typu jiného než znak delším než 8 nejsou podpořeny.

Dokumentace pro jednotlivé zprávy je k dispozici na adrese
https://mavlink.io/en/messages/common.html

1.2.1 Konfigurace ovladače

Konfigurace ovladače je uložena v souboru .rio ve formátu JSON. V aktuální verzi není k dispozici konfigurační dialog. Konfigurace slouží pro definici ID systému a nastavení routeru. Veškerá další funkcionalita je definována pomocí funkčních bloků. Následující blok zobrazuje jednoduchou konfiguraci ovladače.

 {  
        "SystemID" : 200,  
        "ComponentID" : 1,  
        "Endpoints" : [  
                {  
                        "Type": "Serial",  
                        "Device": "/dev/ttyS1",  
                        "BaudRate": 921600  
                },  
                {  
                        "Type": "UDP",  
                        "Mode": "listen",  
                        "Address": "192.168.1.100",  
                        "Port": 14550  
                        "BindAddress": "0.0.0.0",  
                        "BindPort": 14550  
                },  
                {  
                        "Type": "TCP",  
                        "Mode": "connect",  
                        "Address": "192.168.1.200",  
                        "Port": 15550  
                }  
        ]  
}

Význam hlavních atributů

  • System ID – definuje System ID aplikace,
  • Component ID – definuje Component ID aplikace,
  • Endpoints – definuje seznam komunikačních kanálů. Ovladač provádí automaticky směrování paketů mezi těmito kanály. Podpořeny jsou kanály Serial, UDP a TCP.

Význam atributů pro endpoint Serial

  • Device – cesta k sériovému zařízení,
  • BaudRate – nastavení rychlosti sériového portu.

Význam atributů pro endpoint UDP

  • Mode – možné varianty listen – naslouchání na lokálním portu nebo connect – připojení ke vzdálenému zařízení. V módu listen jsou přijaty zprávy od všech zařízení s libovolnou IP a portem, v režimu connect jsou přijímány pouze data od zařízení určeném pomocí Address a Port.
  • Address – IP adresa vzdáleného zařízení. Pokud není uvedeno nebo je nastaveno na 0.0.0.0 v módu listen, bude ovladač posílat data prvnímu připojenému zařízení.
  • Port – port vzdáleného zařízení. Pokud není uvedeno nebo je nastaveno na 0 v módu listen, bude ovladač posílat data prvnímu připojenému zařízení
  • BindAddress – IP adresa lokálního rozhraní, na kterém bude probíhat komunikace. Může být vynecháno nebo nastaveno na 0.0.0.0, v takovém případě budou použita všechna lokální rozhraní.
  • BindPort – Port lokálního rozhraní. Může být vynecháno nebo nastaveno na 0, v takovém případě případě je vybrán vhodný lokální port operačním systémem.

Pro endpoint typu UDP doporučujeme používat výhradně režim listen, protože režim connect může způsobovat problémy v případě, kdy není protější strana dostupná nebo ukončí spojení. V režimu listen je také možné provozovat komunikaci pomocí vysílání všem – tzv. broadcast. V takovém případě musí být vybráno lokální rozhraní nastavením příslušné adresy IP pomocí parametrů BindAddress a BindPort a parametrem Address nastavena lokální všesměrová adresa (např. 192.168.1.255).

Význam atributů pro endpoint TCP

  • Mode – možné varianty listen – naslouchání na lokálním portu nebo connect – připojení ke vzdálenému zařízení,
  • Address – IP adresa lokálního rozhraní (0.0.0.0 pro všechny) nebo IP adresa vzdáleného zařízení,
  • Port – lokální port v případě naslouchání nebo port vzdáleného zařízení.

1.2.2 Příjem zpráv

Zprávy jsou přijímány pomocí bloků MAV_RECV_<command>. Základní rozhraní bloku je následující

  • INHIBIT – vstup BOOL. Určuje, zda se má přijatá zpráva poslat dál (směrovat). Toto musí být nastaveno dopředu tj. není možné rozhodnout o směrování na základě obashu zprávy.
  • VALID – výstup BOOL. Udává validitu dat na výstupu. Nastavený v případě příchozích dat v definovaném čase (viz. parametr TimoutMS).
  • ACT – výstup BOOL. Nastaven pouze v prvním tiku po příjmu nových dat.
  • Sequence – číslo Sequence z hlavičky posledního přijatého rámce dané zprávy – viz dokumentace MAVLink.
  • Timestamp – časová značka posledních přijatých dat v interním formátu REXYGENu tj. nanosekundy.
  • SrcSystemID – parametr typu SHORT. Určuje system ID vysílacího uzlu (1 pro UAV).
  • SrcComponentID – parametr typu SHORT. Určuje component ID vysílacího uzlu (1 pro UAV).
  • TgtSystemID – parametr typu SHORT. Určuje system ID cílového uzlu (-1 pro nenastaveno resp. není součástí dané zprávy, -2 pro ID algoritmu – viz SystemID v konfiguraci ovladače).
  • TgtComponentID – parametr typu SHORT. Určuje component ID cílového uzlu (-1 pro nenastaveno resp. není součástí dané zprávy, -2 pro ID algoritmu – viz ComponentID v konfiguraci ovladače).
  • TimeoutMS – maximální doba mezi jednotlivými zprávami. V případě, že nedojde k příjmu nových dat v tomto intervalu, dojde k nastavení VALID na false. Pokud je nastaveno na 0, timeout není definován.

Ostatní výstupy jsou definovány příslušnou zprávou a obsahují data z poslední přijaté zprávy.

1.2.3 Vysílání zpráv

Zprávy jsou přijímány pomocí bloků MAV_SEND_<command>. Základní interface bloku je následující

  • RUN – vstup BOOL. Data jsou vyslána v daném tiku, pokud je tento vstup nastaven.
  • SENT – výstup BOOL. Nastaven v případě nastavení vstupu RUN a současně byla data úspěšně odeslána.
  • TgtSystemID – parametr typu SHORT. Určuje system ID cílového uzlu (může být -1 tj. „všem“ v případě, že není součástí daného typu zprávy).
  • TgtComponentD – parametr typu SHORT. Určuje component ID cílového uzlu (může být -1 tj. „všem“ v případě, že není součástí daného typu zprávy).

Ostatní vstupy jsou definovány příslušnou zprávou a obsahují data pro vyslání.

1.3 Instalace ovladače na cílovém zařízení

1.3.1 Zařízení s operačním systémem Windows

Ovladač pro vývojové nástroje (host) je součástí instalátoru. Ovladač není podporován na cílovém zařízení (target) se systémem Windows.

1.3.2 Zařízení s operačním systémem Linux

Pokud na cílovém zařízení nainstalovaný RexCore runtime modul, pak je nutné ho nainstalovat podle kroků popsaných v návodu Začínáme s řídicím systémem REXYGEN [1] Instalace obsahuje všechny dostupné ovladače včetně MAVLinkDrv.

Pro instalaci ovladače odděleně může být z terminálu použit příkaz
sudo apt-get install rex-mavlinkdrvt

Kapitola 2
Zavedení ovladače do projektu

Ovladač je zaveden do projektu v momentě, kdy je ovladač přidán do hlavního souboru a vstupy a výstupy jsou zapojeny do řídicího algoritmu.

2.1 Přidání MAVLinkDrv ovladače

Pro zavedení ovladače musí být do hlavního souboru bloku přidány 2 bloky. První z bloků je typu MODULE a musí být napojen na výstup Modules bloku EXEC. Blok musí být přejmenován na MAVLinkDrv.

Druhým z bloků je typu IODRV a musí být napojen na výstup Drivers bloku EXEC v hlavním souboru projektu. Jméno tohoto bloku (MAVLink) musí být zároveň prefixem všech vstupních a výstupních signálů, které ovladač poskytuje.

Mezi nejvýznamnější parametry bloku IODRV patří:

  • module – jméno modulu, na který je ovladač napojen, v tomto případě MAVLinkDrv – je nutné dodržovat velikosti písmen!
  • classname – třída ovladače, v tomto případě MAVLinkDrv
  • cfgname – jméno konfiguračního souboru, např. mavlink.rio
  • factor – násobek parametru tick bloku EXEC definující periodu spouštění ovladače

Výše zmíněné parametry bloku IODRV jsou konfigurovány v REXYGEN Studio programu.

Kapitola 3
Licence

Část kódu ovladače vychází z kódu mavlink-router, který je k dispozici na https://github.com/intel/mavlink-router. Kód je poskytován pod licencí Apache License verze 2.0.

Apache License  
 
Version 2.0, January 2004  
 
http://www.apache.org/licenses/  
 
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION  
 
1. Definitions.  
 
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by  
Sections 1 through 9 of this document.  
 
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is  
granting the License.  
 
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are  
controlled by, or are under common control with that entity. For the purposes of this definition,  
"control" means (i) the power, direct or indirect, to cause the direction or management of such  
entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the  
outstanding shares, or (iii) beneficial ownership of such entity.  
 
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this  
License.  
 
"Source" form shall mean the preferred form for making modifications, including but not limited to  
software source code, documentation source, and configuration files.  
 
"Object" form shall mean any form resulting from mechanical transformation or translation of a  
Source form, including but not limited to compiled object code, generated documentation, and  
conversions to other media types.  
 
"Work" shall mean the work of authorship, whether in Source or Object form, made available under  
the License, as indicated by a copyright notice that is included in or attached to the work (an  
example is provided in the Appendix below).  
 
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or  
derived from) the Work and for which the editorial revisions, annotations, elaborations, or other  
modifications represent, as a whole, an original work of authorship. For the purposes of this  
License, Derivative Works shall not include works that remain separable from, or merely link (or  
bind by name) to the interfaces of, the Work and Derivative Works thereof.  
 
"Contribution" shall mean any work of authorship, including the original version of the Work and  
any modifications or additions to that Work or Derivative Works thereof, that is intentionally  
submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal  
Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition,  
"submitted" means any form of electronic, verbal, or written communication sent to the Licensor or  
its representatives, including but not limited to communication on electronic mailing lists, source  
code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor  
for the purpose of discussing and improving the Work, but excluding communication that is  
conspicuously marked or otherwise designated in writing by the copyright owner as "Not a  
Contribution."  
 
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a  
Contribution has been received by Licensor and subsequently incorporated within the Work.  
 
2. Grant of Copyright License. Subject to the terms and conditions of this License, each  
Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,  
irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly  
perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.  
 
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor  
hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable  
(except as stated in this section) patent license to make, have made, use, offer to sell, sell,  
import, and otherwise transfer the Work, where such license applies only to those patent claims  
licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by  
combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If  
You institute patent litigation against any entity (including a cross-claim or counterclaim in a  
lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct  
or contributory patent infringement, then any patent licenses granted to You under this License for  
that Work shall terminate as of the date such litigation is filed.  
 
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof  
in any medium, with or without modifications, and in Source or Object form, provided that You meet  
the following conditions:  
 
You must give any other recipients of the Work or Derivative Works a copy of this License; and  
You must cause any modified files to carry prominent notices stating that You changed the files; and  
You must retain, in the Source form of any Derivative Works that You distribute, all copyright,  
patent, trademark, and attribution notices from the Source form of the Work, excluding those  
notices that do not pertain to any part of the Derivative Works; and  
If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works  
that You distribute must include a readable copy of the attribution notices contained within such  
NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at  
least one of the following places: within a NOTICE text file distributed as part of the Derivative  
Works; within the Source form or documentation, if provided along with the Derivative Works; or,  
within a display generated by the Derivative Works, if and wherever such third-party notices  
normally appear. The contents of the NOTICE file are for informational purposes only and do not  
modify the License. You may add Your own attribution notices within Derivative Works that You  
distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such  
additional attribution notices cannot be construed as modifying the License.  
 
You may add Your own copyright statement to Your modifications and may provide additional or  
different license terms and conditions for use, reproduction, or distribution of Your  
modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and  
distribution of the Work otherwise complies with the conditions stated in this License.  
 
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution  
intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms  
and conditions of this License, without any additional terms or conditions. Notwithstanding the  
above, nothing herein shall supersede or modify the terms of any separate license agreement you may  
have executed with Licensor regarding such Contributions.  
 
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service  
marks, or product names of the Licensor, except as required for reasonable and customary use in  
describing the origin of the Work and reproducing the content of the NOTICE file.  
 
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor  
provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT  
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any  
warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR  
PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing  
the Work and assume any risks associated with Your exercise of permissions under this License.  
 
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including  
negligence), contract, or otherwise, unless required by applicable law (such as deliberate and  
grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for  
damages, including any direct, indirect, special, incidental, or consequential damages of any  
character arising as a result of this License or out of the use or inability to use the Work  
(including but not limited to damages for loss of goodwill, work stoppage, computer failure or  
malfunction, or any and all other commercial damages or losses), even if such Contributor has been  
advised of the possibility of such damages.  
 
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works  
thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity,  
or other liability obligations and/or rights consistent with this License. However, in accepting  
such obligations, You may act only on Your own behalf and on Your sole responsibility, not on  
behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each  
Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by  
reason of your accepting any such warranty or additional liability.  
 
END OF TERMS AND CONDITIONS

Literatura

[1]   REX Controls s.r.o.. Začínáme s řídicím systémem REXYGEN, 2020. .


Referenční číslo dokumentace: 13771

2022 © REX Controls s.r.o., www.rexygen.com