gomavlib

package module
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Feb 12, 2023 License: MIT Imports: 16 Imported by: 48

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:

  • 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.17.

  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

Other Go libraries

Other non-Go libraries

Standards

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/aler9/gomavlib/tree/master/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 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 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 {
	// 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() 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 {
	// 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 details.

func (*Node) FixFrame added in v1.1.0

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

WriteMessageAll writes a message to all channels.

func (*Node) WriteMessageExcept

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

WriteMessageExcept writes a message to all channels except specified channel.

func (*Node) WriteMessageTo

func (n *Node) WriteMessageTo(channel *Channel, m message.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
dialect-import command
dialect-import command.
dialect-import command.
dialects-gen command
dialects-gen command.
dialects-gen command.
examples
dialect-custom command
dialect-no command
endpoint-custom command
endpoint-serial command
events command
message-read command
message-write command
readwriter command
router command
router-edit command
signature command
stream-requests command
pkg
autoreconnector
Package autoreconnector contains a io.ReadWriteCloser wrapper that implements automatic reconnection.
Package autoreconnector contains a io.ReadWriteCloser wrapper that implements automatic reconnection.
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/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/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/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.
timednetconn
Package timednetconn contains a net.Conn wrapper that calls SetWriteDeadline() before Write().
Package timednetconn contains a net.Conn wrapper that calls SetWriteDeadline() before Write().
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