rostish / gomavlib

Mavlink library (2.0 and 1.0) for the Go programming language

gomavlib

gomavlib is a library that implements the Mavlink protocol (2.0 and 1.0) in the Go programming language. It can power UGVs, UAVs, ground stations, monitoring systems or routers, connected to other Mavlink-capable devices through a serial port, UDP, TCP or a custom transport.

Mavlink is a lightweight and transport-independent protocol that is mostly used to communicate with unmanned ground vehicles (UGV) and unmanned aerial vehicles (UAV, drones, quadcopters, multirotors). It is supported by the most popular open-source flight controllers (Ardupilot and PX4).

This library powers the mavp2p router.

Features:

• Decode and encode Mavlink v2.0 and v1.0. Supports checksums, empty-byte truncation (v2.0), signatures (v2.0), message extensions (v2.0).
• Dialects are optional, the library can work with standard dialects (ready-to-use standard dialects are provided in directory dialects/), custom dialects or no dialects at all. In case of custom dialects, a dialect generator is available in order to convert XML definitions into their Go representation.
• Create nodes able to communicate with multiple endpoints in parallel and with multiple transports:
  • serial
  • UDP (server, client or broadcast mode)
  • TCP (server or client mode)
  • custom reader/writer
• Emit heartbeats automatically
• Send automatic stream requests to Ardupilot devices (disabled by default)
• Support both domain names and IPs
• Examples provided for every feature, comprehensive test suite, continuous integration

Table of contents

• Installation
• API Documentation
• Dialect generation
• Testing
• Links

Installation

1. Install Go ≥ 1.15.

2. Create an empty folder, open a terminal in it and initialize the Go modules system:

   go mod init main
   

3. Download one of the example files and place it in the folder:

• endpoint-serial
• endpoint-udp-server
• endpoint-udp-client
• endpoint-udp-broadcast
• endpoint-tcp-server
• endpoint-tcp-client
• endpoint-custom
• message-read
• message-write
• signature
• dialect-no
• dialect-custom
• events
• router
• stream-requests
• transceiver

4. Compile and run

   go run name-of-the-go-file.go
   

API Documentation

https://pkg.go.dev/github.com/aler9/gomavlib#pkg-index

Dialect generation

Standard dialects are provided in the pkg/dialects/ folder, but it's also possible to use custom dialects, that can be converted into Go files by running:

go get github.com/aler9/gomavlib/cmd/dialect-import
dialect-import my_dialect.xml > dialect.go

Testing

If you want to hack the library and test the results, unit tests can be launched with:

make test

Links

Related projects

• https://github.com/aler9/mavp2p

Protocol documentation

• main website https://mavlink.io/en/
• packet format https://mavlink.io/en/guide/serialization.html
• common dialect https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml

Other Go libraries

• https://github.com/hybridgroup/gobot/tree/master/platforms/mavlink
• https://github.com/liamstask/go-mavlink
• https://github.com/ungerik/go-mavlink
• https://github.com/SpaceLeap/go-mavlink

Other non-Go libraries

• [C] https://github.com/mavlink/c_library_v2
• [Python] https://github.com/ArduPilot/pymavlink
• [Java] https://github.com/DrTon/jMAVlib
• [C#] https://github.com/asvol/mavlink.net
• [Rust] https://github.com/3drobotics/rust-mavlink
• [JS] https://github.com/omcaree/node-mavlink

Conventions

• https://github.com/golang-standards/project-layout