gomavlib

package module
Version: v0.0.0-...-219f145 Latest Latest
Warning

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

 Go to latest Published: May 11, 2022 License: MIT Imports: 16 Imported by: 43

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

  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

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

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.

Source Files

View all

Directories

Path Synopsis
cmd
dialect-import
dialects-gen
examples
dialect-custom
dialect-no
endpoint-custom
endpoint-serial
endpoint-tcp-client
endpoint-tcp-server
endpoint-udp-broadcast
endpoint-udp-client
endpoint-udp-server
events
message-read
message-write
parser
router
signature
stream-requests
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.
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/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/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 python_array_test dialect.
 Package pythonarraytest contains the python_array_test dialect.
dialects/standard
Package standard contains the standard dialect.
 Package standard contains the standard 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 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.
parser
Package parser contains a Mavlink reader and writer.
 Package parser contains a Mavlink reader and writer.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL