github.com/bluenviron/gomavlib/v2@v2.2.1-0.20240308101627-2c07e3da629c/README.md (about) 1 # gomavlib 2 3 [![Test](https://github.com/bluenviron/gomavlib/workflows/test/badge.svg)](https://github.com/bluenviron/gomavlib/actions?query=workflow:test) 4 [![Lint](https://github.com/bluenviron/gomavlib/workflows/lint/badge.svg)](https://github.com/bluenviron/gomavlib/actions?query=workflow:lint) 5 [![Dialects](https://github.com/bluenviron/gomavlib/workflows/dialects/badge.svg)](https://github.com/bluenviron/gomavlib/actions?query=workflow:dialects) 6 [![Go Report Card](https://goreportcard.com/badge/github.com/bluenviron/gomavlib)](https://goreportcard.com/report/github.com/bluenviron/gomavlib) 7 [![CodeCov](https://codecov.io/gh/bluenviron/gomavlib/branch/main/graph/badge.svg)](https://app.codecov.io/gh/bluenviron/gomavlib/branch/main) 8 [![PkgGoDev](https://pkg.go.dev/badge/github.com/bluenviron/gomavlib/v2)](https://pkg.go.dev/github.com/bluenviron/gomavlib/v2#pkg-index) 9 10 gomavlib is a library that implements the Mavlink protocol (2.0 and 1.0) in the Go programming language. It can interact with Mavlink-capable devices through a serial port, UDP, TCP or a custom transport, and it can be used to power UGVs, UAVs, ground stations, monitoring systems or routers. 11 12 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). 13 14 This library powers the [**mavp2p**](https://github.com/bluenviron/mavp2p) router. 15 16 Features: 17 18 * Decode and encode Mavlink v2.0 and v1.0. Supports checksums, empty-byte truncation (v2.0), signatures (v2.0), message extensions (v2.0). 19 * 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. 20 * Create nodes able to communicate with multiple endpoints in parallel and with multiple transports: 21 * serial 22 * UDP (server, client or broadcast mode) 23 * TCP (server or client mode) 24 * custom reader/writer 25 * Emit heartbeats automatically 26 * Send automatic stream requests to Ardupilot devices (disabled by default) 27 * Support both domain names and IPs 28 * Examples provided for every feature, comprehensive test suite, continuous integration 29 30 ## Table of contents 31 32 * [Installation](#installation) 33 * [API Documentation](#api-documentation) 34 * [Dialect generation](#dialect-generation) 35 * [Testing](#testing) 36 * [Specifications](#specifications) 37 * [Links](#links) 38 39 ## Installation 40 41 1. Install Go ≥ 1.19. 42 43 2. Create an empty folder, open a terminal in it and initialize the Go modules system: 44 45 ``` 46 go mod init main 47 ``` 48 49 3. Download one of the example files and place it in the folder: 50 51 * [endpoint-serial](examples/endpoint-serial/main.go) 52 * [endpoint-udp-server](examples/endpoint-udp-server/main.go) 53 * [endpoint-udp-client](examples/endpoint-udp-client/main.go) 54 * [endpoint-udp-broadcast](examples/endpoint-udp-broadcast/main.go) 55 * [endpoint-tcp-server](examples/endpoint-tcp-server/main.go) 56 * [endpoint-tcp-client](examples/endpoint-tcp-client/main.go) 57 * [endpoint-custom](examples/endpoint-custom/main.go) 58 * [message-read](examples/message-read/main.go) 59 * [message-write](examples/message-write/main.go) 60 * [signature](examples/signature/main.go) 61 * [dialect-no](examples/dialect-no/main.go) 62 * [dialect-custom](examples/dialect-custom/main.go) 63 * [events](examples/events/main.go) 64 * [router](examples/router/main.go) 65 * [router-edit](examples/router-edit/main.go) 66 * [serial-to-json](examples/serial-to-json/main.go) 67 * [stream-requests](examples/stream-requests/main.go) 68 * [readwriter](examples/readwriter/main.go) 69 70 4. Compile and run 71 72 ``` 73 go run name-of-the-go-file.go 74 ``` 75 76 ## API Documentation 77 78 [Click to open the API Documentation](https://pkg.go.dev/github.com/bluenviron/gomavlib/v2#pkg-index) 79 80 ## Dialect generation 81 82 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: 83 84 ``` 85 go install github.com/bluenviron/gomavlib/v2/cmd/dialect-import@latest 86 dialect-import my_dialect.xml 87 ``` 88 89 ## Testing 90 91 If you want to hack the library and test the results, unit tests can be launched with: 92 93 ``` 94 make test 95 ``` 96 97 ## Specifications 98 99 |name|area| 100 |----|----| 101 |[main website](https://mavlink.io/en/)|protocol| 102 |[packet format](https://mavlink.io/en/guide/serialization.html)|protocol| 103 |[common dialect](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml)|dialects| 104 |[Golang project layout](https://github.com/golang-standards/project-layout)|project layout| 105 106 ## Links 107 108 Related projects 109 110 * [mavp2p](https://github.com/bluenviron/mavp2p) 111 112 Other Go libraries 113 114 * [gobot](https://github.com/hybridgroup/gobot/tree/master/platforms/mavlink) 115 * [liamstask/go-mavlink](https://github.com/liamstask/go-mavlink) 116 * [ungerik/go-mavlink](https://github.com/ungerik/go-mavlink) 117 * [SpaceLeap/go-mavlink](https://github.com/SpaceLeap/go-mavlink) 118 * [MAVSDK-Go](https://github.com/mavlink/MAVSDK-Go) 119 120 Other non-Go libraries 121 122 * [official library (C)](https://github.com/mavlink/c_library_v2) 123 * [pymavlink (Python)](https://github.com/ArduPilot/pymavlink) 124 * [mavlink.net (C#)](https://github.com/asvol/mavlink.net) 125 * [rust-mavlink (Rust)](https://github.com/3drobotics/rust-mavlink) 126 * [node-mavlink (JS)](https://github.com/omcaree/node-mavlink)