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
• API Documentation
• Dialect generation
• Testing
• Links

Installation

1. Install Go ≥ 1.13.

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

1. 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

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
  • func (ch *Channel) Endpoint() Endpoint
  • func (ch *Channel) String() string
• 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
  • func (res *EventFrame) ComponentID() byte
  • func (res *EventFrame) Message() msg.Message
  • func (res *EventFrame) SystemID() byte
• type EventParseError
• type EventStreamRequested
• type Node
  • func NewNode(conf NodeConf) (*Node, error)
  • 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
  • func (v Version) String() string

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

func (*Channel) Endpoint

func (ch *Channel) Endpoint() Endpoint

Endpoint returns the channel Endpoint.

func (*Channel) String

func (ch *Channel) String() string

String implements fmt.Stringer.

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 NewNode

func NewNode(conf NodeConf) (*Node, error)

NewNode allocates a Node. See NodeConf for the options.

func (*Node) Close

func (n *Node) Close()

Close halts node operations and waits for all routines to return.

func (*Node) Events

func (n *Node) Events() chan Event

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

func (n *Node) WriteFrameAll(fr frame.Frame)

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

func (n *Node) WriteFrameExcept(exceptChannel *Channel, fr frame.Frame)

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

func (n *Node) WriteFrameTo(channel *Channel, fr frame.Frame)

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

func (n *Node) WriteMessageAll(m msg.Message)

WriteMessageAll writes a message to all channels.

func (*Node) WriteMessageExcept

func (n *Node) WriteMessageExcept(exceptChannel *Channel, m msg.Message)

WriteMessageExcept writes a message to all channels except specified channel.

func (*Node) WriteMessageTo

func (n *Node) WriteMessageTo(channel *Channel, m msg.Message)

WriteMessageTo writes a message to given 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.

type Version

type Version int

Version is a Mavlink version.

const (
	// V1 is Mavlink 1.0
	V1 Version = 1

	// V2 is Mavlink 2.0
	V2 Version = 2
)

func (Version) String

func (v Version) String() string

String implements fmt.Stringer.