gomavlib

package module
v4.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 1, 2026 License: MIT Imports: 17 Imported by: 0

README

gomavlib

Test Lint Dialects Go Report Card CodeCov PkgGoDev

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.

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:

  • Create Mavlink nodes able to communicate with other nodes.
    • Supported transports: serial, UDP (server, client or broadcast mode), TCP (server or client mode), custom reader/writer.
    • Support both domain names and IPs.
    • Emit heartbeats automatically.
    • Send automatic stream requests to Ardupilot devices (disabled by default).
  • Decode and encode Mavlink v2.0 and v1.0.
    • Compute and validate checksums.
    • Support all v2 features: empty-byte truncation, signatures, message extensions.
  • Use dialects in multiple ways.
    • Ready-to-use standard dialects are available in directory dialects/.
    • Custom dialects can be defined. Aa dialect generator is available in order to convert XML definitions into their Go representation.
    • Use no dialect at all. Messages can be routed without having their content decoded.
  • Read and write telemetry logs (tlog)

Table of contents

Installation

  1. Install Go ≥ 1.25.

  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.

  4. Compile and run:

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

Examples

API Documentation

Click to open the API Documentation

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 install github.com/bluenviron/gomavlib/v4/cmd/dialect-import@latest
dialect-import my_dialect.xml

Specifications

name area
main website protocol
packet format protocol
common dialect dialects
Golang project layout project layout

Related projects

Other Go libraries

Other non-Go libraries

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

Examples are available at https://github.com/bluenviron/gomavlib/tree/main/examples

Index

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 {
	// contains filtered or unexported methods
}

Endpoint is an endpoint, which provides Channels.

type EndpointCustomClient 

type EndpointCustomClient struct {
	// custom connect function that opens the connection
	Connect func(ctx context.Context) (net.Conn, error)

	// the label of the protocol
	Label string

	// whether the connection is datagram-based (e.g. UDP).
	IsDatagram bool
	// contains filtered or unexported fields
}

EndpointCustomClient is an endpoint that works with a custom implementation by providing a Connect func that returns a net.Conn.

type EndpointCustomServer 

type EndpointCustomServer struct {
	// function to invoke when server should start listening
	Listen func() (net.Listener, error)

	// the label of the protocol
	Label string

	// whether the connection is datagram-based (e.g. UDP).
	IsDatagram bool
	// contains filtered or unexported fields
}

EndpointCustomServer is an endpoint that works with custom implementations by providing a custom Listen func that returns a net.Listener. This allows you to use custom protocols that conform to the net.listner. A use case could be to add encrypted protocol implementations like DTLS or TCP with TLS.

type EndpointSerial 

type EndpointSerial struct {
	// name of the device of the serial port (i.e: /dev/ttyUSB0)
	Device string

	// baud rate (i.e: 57600)
	Baud int

	EndpointCustomClient
}

EndpointSerial is an 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

	EndpointCustomClient
}

EndpointTCPClient is an 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

	EndpointCustomServer
}

EndpointTCPServer is an 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 {
	// broadcast address to which sending outgoing frames, example: 192.168.5.255:5600
	BroadcastAddress string

	// (optional) listening address. if empty, it will be computed
	// from the broadcast address.
	LocalAddress string

	EndpointCustomClient
}

EndpointUDPBroadcast is an 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

	EndpointCustomClient
}

EndpointUDPClient is an endpoint that works with a UDP client.

type EndpointUDPServer 

type EndpointUDPServer struct {
	// listen address, example: 0.0.0.0:5600
	Address string

	EndpointCustomServer
}

EndpointUDPServer is an 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
	Error   error
}

EventChannelClose is fired when a channel is closed.

type EventChannelOpen 

type EventChannelOpen struct {
	Channel *Channel
}

EventChannelOpen is fired when a channel is opened.

type EventFrame 

type EventFrame struct {
	// frame
	Frame frame.Frame

	// channel from which the frame was received
	Channel *Channel
}

EventFrame is 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() message.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 {
	// error
	Error error

	// channel used to send the frame
	Channel *Channel
}

EventParseError is fired when a parse error occurs.

type EventStreamRequested 

type EventStreamRequested struct {
	// channel to which the stream request is addressed
	Channel *Channel

	// system id to which the stream requests is addressed
	SystemID byte

	// component id to which the stream requests is addressed
	ComponentID byte
}

EventStreamRequested is fired when an automatic stream request is sent.

type Node 

type Node struct {
	// endpoints with which this node will
	// communicate. Each endpoint contains zero or more channels
	Endpoints []Endpoint

	// (optional) 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) 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
	// system id, added to every outgoing frame and used to identify this
	// node in the network.
	OutSystemID byte
	// (optional) component id, added to every outgoing frame, defaults to 1.
	OutComponentID byte
	// (optional) 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) period between heartbeats. It defaults to 5 seconds.
	HeartbeatPeriod time.Duration
	// (optional) system type advertised by heartbeats.
	// It defaults to MAV_TYPE_GCS
	HeartbeatSystemType int
	// (optional) 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) requested stream frequency in Hz. It defaults to 4.
	StreamRequestFrequency int

	// (optional) read timeout.
	// It defaults to 10 seconds.
	ReadTimeout time.Duration
	// (optional) write timeout.
	// It defaults to 10 seconds.
	WriteTimeout time.Duration
	// (optional) timeout before closing idle connections.
	// It defaults to 60 seconds.
	IdleTimeout time.Duration
	// 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 

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

func (*Node) FixFrame 

func (n *Node) FixFrame(fr frame.Frame) error

FixFrame recomputes the Frame checksum and signature. This can be called on Frames whose content has been edited.

func (*Node) Initialize 

func (n *Node) Initialize() error

Initialize initializes a Node.

func (*Node) WriteFrameAll 

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

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) error

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) error

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 message.Message) error

WriteMessageAll writes a message to all channels.

func (*Node) WriteMessageExcept 

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

WriteMessageExcept writes a message to all channels except specified channel.

func (*Node) WriteMessageTo 

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

WriteMessageTo writes a message to given channel.

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
dialect-import command
dialect-import command.
 dialect-import command.
dialects-gen command
dialects-gen command.
 dialects-gen command.
examples
frame-read-writer command
Package main contains an example.
 Package main contains an example.
node-command-microservice command
Package main contains an example.
 Package main contains an example.
node-dialect-absent command
Package main contains an example.
 Package main contains an example.
node-dialect-custom command
Package main contains an example.
 Package main contains an example.
node-endpoint-custom-client command
Package main contains an example.
 Package main contains an example.
node-endpoint-custom-server command
Package main contains an example.
 Package main contains an example.
node-endpoint-serial command
Package main contains an example.
 Package main contains an example.
node-endpoint-tcp-client command
Package main contains an example.
 Package main contains an example.
node-endpoint-tcp-server command
Package main contains an example.
 Package main contains an example.
node-endpoint-udp-broadcast command
Package main contains an example.
 Package main contains an example.
node-endpoint-udp-client command
Package main contains an example.
 Package main contains an example.
node-endpoint-udp-server command
Package main contains an example.
 Package main contains an example.
node-events command
Package main contains an example.
 Package main contains an example.
node-message-read command
Package main contains an example.
 Package main contains an example.
node-message-write command
Package main contains an example.
 Package main contains an example.
node-router command
Package main contains an example.
 Package main contains an example.
node-router-edit command
Package main contains an example.
 Package main contains an example.
node-serial-to-json command
Package main contains an example.
 Package main contains an example.
node-signature command
Package main contains an example.
 Package main contains an example.
node-stream-requests command
Package main contains an example.
 Package main contains an example.
telemetry-log command
Package main contains an example.
 Package main contains an example.
pkg
conversion
Package conversion contains functions to convert definitions from XML to Go.
 Package conversion contains functions to convert definitions from XML to Go.
dialect
Package dialect contains the dialect definition and its parser.
 Package dialect contains the dialect definition and its parser.
dialects/all
Package all contains the all dialect.
 Package all contains the all dialect.
dialects/ardupilotmega
Package ardupilotmega contains the ardupilotmega dialect.
 Package ardupilotmega contains the ardupilotmega dialect.
dialects/asluav
Package asluav contains the asluav dialect.
 Package asluav contains the asluav dialect.
dialects/avssuas
Package avssuas contains the avssuas dialect.
 Package avssuas contains the avssuas dialect.
dialects/common
Package common contains the common dialect.
 Package common contains the common dialect.
dialects/csairlink
Package csairlink contains the csairlink dialect.
 Package csairlink contains the csairlink dialect.
dialects/cubepilot
Package cubepilot contains the cubepilot dialect.
 Package cubepilot contains the cubepilot dialect.
dialects/development
Package development contains the development dialect.
 Package development contains the development dialect.
dialects/icarous
Package icarous contains the icarous dialect.
 Package icarous contains the icarous dialect.
dialects/loweheiser
Package loweheiser contains the loweheiser dialect.
 Package loweheiser contains the loweheiser dialect.
dialects/marsh
Package marsh contains the marsh dialect.
 Package marsh contains the marsh dialect.
dialects/matrixpilot
Package matrixpilot contains the matrixpilot dialect.
 Package matrixpilot contains the matrixpilot dialect.
dialects/minimal
Package minimal contains the minimal dialect.
 Package minimal contains the minimal dialect.
dialects/paparazzi
Package paparazzi contains the paparazzi dialect.
 Package paparazzi contains the paparazzi dialect.
dialects/pythonarraytest
Package pythonarraytest contains the pythonarraytest dialect.
 Package pythonarraytest contains the pythonarraytest dialect.
dialects/standard
Package standard contains the standard dialect.
 Package standard contains the standard dialect.
dialects/stemstudios
Package stemstudios contains the stemstudios dialect.
 Package stemstudios contains the stemstudios dialect.
dialects/storm32
Package storm32 contains the storm32 dialect.
 Package storm32 contains the storm32 dialect.
dialects/test
Package test contains the test dialect.
 Package test contains the test dialect.
dialects/ualberta
Package ualberta contains the ualberta dialect.
 Package ualberta contains the ualberta dialect.
dialects/uavionix
Package uavionix contains the uavionix dialect.
 Package uavionix contains the uavionix dialect.
frame
Package frame contains frame definitions and a frame parser.
 Package frame contains frame definitions and a frame parser.
message
Package message contains the message definition and its parser.
 Package message contains the message definition and its parser.
streamwriter
Package streamwriter contains a message stream writer.
 Package streamwriter contains a message stream writer.
timednetconn
Package timednetconn contains a net.Conn wrapper with deadlines.
 Package timednetconn contains a net.Conn wrapper with deadlines.
tlog
Package tlog contains a Telemetry log reader and writer.
 Package tlog contains a Telemetry log reader and writer.
x25
Package x25 implements the X25 hash.
 Package x25 implements the X25 hash.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.