README
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
-
Install Go ≥ 1.13.
-
Create an empty folder, open a terminal in it and initialize the Go modules system:
go mod init main
-
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
-
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
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
Documentation
Overview ¶
Package gomavlib is a library that implements Mavlink 2.0 and 1.0 in the Go programming language. It can power UGVs, UAVs, ground stations, monitoring systems or routers acting in a Mavlink network.
Mavlink is a lighweight 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 common open-source flight controllers (Ardupilot and PX4).
Basic example (more are available at https://github.com/aler9/gomavlib/tree/master/examples):
package main import ( "fmt" "github.com/aler9/gomavlib" "github.com/aler9/gomavlib/pkg/dialects/ardupilotmega" ) func main() { node, err := gomavlib.NewNode(gomavlib.NodeConf{ Endpoints: []gomavlib.EndpointConf{ gomavlib.EndpointSerial{"/dev/ttyUSB0:57600"}, }, Dialect: ardupilotmega.Dialect, OutVersion: gomavlib.V2, OutSystemID: 10, }) if err != nil { panic(err) } defer node.Close() for evt := range node.Events() { if frm,ok := evt.(*gomavlib.EventFrame); ok { fmt.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message()) } } }
Index ¶
- type Channel
- type Endpoint
- type EndpointConf
- type EndpointCustom
- type EndpointSerial
- type EndpointTCPClient
- type EndpointTCPServer
- type EndpointUDPBroadcast
- type EndpointUDPClient
- type EndpointUDPServer
- type Event
- type EventChannelClose
- type EventChannelOpen
- type EventFrame
- type EventParseError
- type EventStreamRequested
- type Node
- func (n *Node) Close()
- func (n *Node) Events() chan Event
- func (n *Node) WriteFrameAll(fr frame.Frame)
- func (n *Node) WriteFrameExcept(exceptChannel *Channel, fr frame.Frame)
- func (n *Node) WriteFrameTo(channel *Channel, fr frame.Frame)
- func (n *Node) WriteMessageAll(m msg.Message)
- func (n *Node) WriteMessageExcept(exceptChannel *Channel, m msg.Message)
- func (n *Node) WriteMessageTo(channel *Channel, m msg.Message)
- type NodeConf
- type Version
Constants ¶
Variables ¶
Functions ¶
Types ¶
type Channel ¶
type Channel struct {
// contains filtered or unexported fields
}
Channel is a communication channel created by an Endpoint. An Endpoint can create channels. For instance, a TCP client endpoint creates a single channel, while a TCP server endpoint creates a channel for each incoming connection.
type Endpoint ¶
type Endpoint interface { // Conf returns the configuration used to initialize the endpoint Conf() EndpointConf // contains filtered or unexported methods }
Endpoint is an endpoint, which can create Channels.
type EndpointConf ¶
type EndpointConf interface {
// contains filtered or unexported methods
}
EndpointConf is the interface implemented by all endpoint configurations.
type EndpointCustom ¶
type EndpointCustom struct { // the struct or interface implementing Read(), Write() and Close() ReadWriteCloser io.ReadWriteCloser }
EndpointCustom sets up a endpoint that works with a custom interface that provides the Read(), Write() and Close() functions.
type EndpointSerial ¶
type EndpointSerial struct { // the address of the serial port in format name:baudrate // example: /dev/ttyUSB0:57600 Address string }
EndpointSerial sets up a endpoint that works with a serial port.
type EndpointTCPClient ¶
type EndpointTCPClient struct { // domain name or IP of the server to connect to, example: 1.2.3.4:5600 Address string }
EndpointTCPClient sets up a endpoint that works with a TCP client. TCP is fit for routing frames through the internet, but is not the most appropriate way for transferring frames from a UAV to a GCS, since it does not allow frame losses.
type EndpointTCPServer ¶
type EndpointTCPServer struct { // listen address, example: 0.0.0.0:5600 Address string }
EndpointTCPServer sets up a endpoint that works with a TCP server. TCP is fit for routing frames through the internet, but is not the most appropriate way for transferring frames from a UAV to a GCS, since it does not allow frame losses.
type EndpointUDPBroadcast ¶
type EndpointUDPBroadcast struct { // the broadcast address to which sending outgoing frames, example: 192.168.5.255:5600 BroadcastAddress string // (optional) the listening address. if empty, it will be computed // from the broadcast address. LocalAddress string }
EndpointUDPBroadcast sets up a endpoint that works with UDP broadcast packets.
type EndpointUDPClient ¶
type EndpointUDPClient struct { // domain name or IP of the server to connect to, example: 1.2.3.4:5600 Address string }
EndpointUDPClient sets up a endpoint that works with a UDP client.
type EndpointUDPServer ¶
type EndpointUDPServer struct { // listen address, example: 0.0.0.0:5600 Address string }
EndpointUDPServer sets up a endpoint that works with an UDP server. This is the most appropriate way for transferring frames from a UAV to a GCS if they are connected to the same network.
type Event ¶
type Event interface {
// contains filtered or unexported methods
}
Event is the interface implemented by all events received with node.Events().
type EventChannelClose ¶
type EventChannelClose struct {
Channel *Channel
}
EventChannelClose is the event fired when a channel gets closed.
type EventChannelOpen ¶
type EventChannelOpen struct {
Channel *Channel
}
EventChannelOpen is the event fired when a channel gets opened.
type EventFrame ¶
type EventFrame struct { // the frame Frame frame.Frame // the channel from which the frame was received Channel *Channel }
EventFrame is the event fired when a frame is received.
func (*EventFrame) ComponentID ¶
func (res *EventFrame) ComponentID() byte
ComponentID returns the frame component id.
func (*EventFrame) Message ¶
func (res *EventFrame) Message() msg.Message
Message returns the message inside the frame.
func (*EventFrame) SystemID ¶
func (res *EventFrame) SystemID() byte
SystemID returns the frame system id.
type EventParseError ¶
type EventParseError struct { // the error Error error // the channel used to send the frame Channel *Channel }
EventParseError is the event fired when a parse error occurs.
type EventStreamRequested ¶
type EventStreamRequested struct { // the channel to which the stream request is addressed Channel *Channel // the system id to which the stream requests is addressed SystemID byte // the component id to which the stream requests is addressed ComponentID byte }
EventStreamRequested is the event fired when an automatic stream request is sent.
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node is a high-level Mavlink encoder and decoder that works with endpoints.
func (*Node) Close ¶
func (n *Node) Close()
Close halts node operations and waits for all routines to return.
func (*Node) Events ¶
Events returns a channel from which receiving events. Possible events are:
*EventChannelOpen *EventChannelClose *EventFrame *EventParseError *EventStreamRequested
See individual events for meaning and content.
func (*Node) WriteFrameAll ¶
WriteFrameAll writes a frame to all channels. This function is intended only for routing pre-existing frames to other nodes, since all frame fields must be filled manually.
func (*Node) WriteFrameExcept ¶
WriteFrameExcept writes a frame to all channels except specified channel. This function is intended only for routing pre-existing frames to other nodes, since all frame fields must be filled manually.
func (*Node) WriteFrameTo ¶
WriteFrameTo writes a frame to given channel. This function is intended only for routing pre-existing frames to other nodes, since all frame fields must be filled manually.
func (*Node) WriteMessageAll ¶
WriteMessageAll writes a message to all channels.
func (*Node) WriteMessageExcept ¶
WriteMessageExcept writes a message to all channels except specified channel.
type NodeConf ¶
type NodeConf struct { // the endpoints with which this node will // communicate. Each endpoint contains zero or more channels Endpoints []EndpointConf // (optional) the dialect which contains the messages that will be encoded and decoded. // If not provided, messages are decoded in the MessageRaw struct. Dialect *dialect.Dialect // (optional) the secret key used to validate incoming frames. // Non signed frames are discarded, as well as frames with a version < 2.0. InKey *frame.V2Key // Mavlink version used to encode messages. See Version // for the available options. OutVersion Version // the system id, added to every outgoing frame and used to identify this // node in the network. OutSystemID byte // (optional) the component id, added to every outgoing frame, defaults to 1. OutComponentID byte // (optional) the secret key used to sign outgoing frames. // This feature requires a version >= 2.0. OutKey *frame.V2Key // (optional) disables the periodic sending of heartbeats to open channels. HeartbeatDisable bool // (optional) the period between heartbeats. It defaults to 5 seconds. HeartbeatPeriod time.Duration // (optional) the system type advertised by heartbeats. // It defaults to MAV_TYPE_GCS HeartbeatSystemType int // (optional) the autopilot type advertised by heartbeats. // It defaults to MAV_AUTOPILOT_GENERIC HeartbeatAutopilotType int // (optional) automatically request streams to detected Ardupilot devices, // that need an explicit request in order to emit telemetry stream. StreamRequestEnable bool // (optional) the requested stream frequency in Hz. It defaults to 4. StreamRequestFrequency int }
NodeConf allows to configure a Node.
Source Files
Directories
Path | Synopsis |
---|---|
cmd
|
|
examples
|
|
pkg
|
|
dialect
Package dialect contains the Dialect definition and utilities to encode and decode dialects.
|
Package dialect contains the Dialect definition and utilities to encode and decode dialects. |
dialects
Package dialects contains the official, autogenerated Mavlink dialects.
|
Package dialects contains the official, autogenerated Mavlink dialects. |
frame
Package frame contains frames and utilities to encode and decode them.
|
Package frame contains frames and utilities to encode and decode them. |
msg
Package msg contains the Message definition and utilities to encode and decode messages.
|
Package msg contains the Message definition and utilities to encode and decode messages. |
multibuffer
Package multibuffer implements a buffer with multiple levels.
|
Package multibuffer implements a buffer with multiple levels. |
transceiver
Package transceiver implements a Mavlink transceiver.
|
Package transceiver implements a Mavlink transceiver. |
udplistener
Package udplistener provides a UDP-based Listener.
|
Package udplistener provides a UDP-based Listener. |
x25
Package x25 implements the X25 hash.
|
Package x25 implements the X25 hash. |