README

gomavlib

Test Lint Dialects CodeCov PkgGoDev

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

  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:

  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

Related projects

Protocol documentation

Other Go libraries

Other non-Go libraries

Conventions

Expand ▾ Collapse ▴

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

    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.

                                                                        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.