gomavlib

package module
v3.2.1 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2025 License: MIT Imports: 17 Imported by: 9

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.
    • Emit heartbeats automatically.
    • Send automatic stream requests to Ardupilot devices (disabled by default).
    • Use both domain names and IPs.
  • 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.21.

  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/v3/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 {
	// Conf returns the configuration used to initialize the endpoint
	Conf() EndpointConf
	// contains filtered or unexported methods
}

Endpoint is an endpoint, which provides 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 {
	// 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 {
	// name of the device of the serial port (i.e: /dev/ttyUSB0)
	Device string

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

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 {
	// 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
}

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
	Error   error
}

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 {
	// frame
	Frame frame.Frame

	// 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() 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 the event 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 the event 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 []EndpointConf

	// (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 NewNode deprecated 

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

NewNode allocates a Node. See NodeConf for the options.

Deprecated: replaced by Node.Initialize().

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 added in v3.2.0 

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 NodeConf deprecated 

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

	// (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
}

NodeConf allows to configure a Node.

Deprecated: configuration has been moved inside 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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
examples
pkg

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.