gomavlib

A Node is a high-level MAVLink encoder and decoder that manages communication with one or more Endpoints. To use a Node, you must provide at least one Endpoint and specify the OutVersion (e.g., V1 or V2).

Key Configuration Options

• Endpoints: A slice of Endpoint objects to communicate with.
• Dialect: (Optional) A *dialect.Dialect containing the messages to be encoded/decoded. If omitted, messages are handled as MessageRaw.
• OutVersion: The MAVLink version used for encoding (V1 or V2).
• OutSystemID: The system ID added to every outgoing frame.
• OutComponentID: (Optional) The component ID for outgoing frames. Defaults to 1.
• InKey: (Optional) A *frame.V2Key used to validate incoming signed frames. Non-signed or version < 2.0 frames are discarded if this is set.
• OutKey: (Optional) A *frame.V2Key used to sign outgoing frames (requires OutVersion to be V2).
• HeartbeatDisable: (Optional) If true, disables periodic heartbeat sending.
• HeartbeatPeriod: (Optional) Period between heartbeats. Defaults to 5s.
• ReadTimeout, WriteTimeout, IdleTimeout: Timeouts for network operations. Defaults are 10s, 10s, and 60s respectively.

Lifecycle

1. Create a Node instance with your desired configuration.
2. Call n.Initialize() to start the node, initialize endpoints, and start background routines (heartbeats, stream requests, etc.).
3. Use n.Events() to listen for incoming events.
4. Call n.Close() to halt operations and wait for all routines to return.

node := &gomavlib.Node{
	Endpoints: []gomavlib.Endpoint{...},
	OutVersion: gomavlib.V2,
	OutSystemID: 1,
}

err := node.Initialize()
if err != nil {
	// handle error
}

// ... use node ...

node.Close()

The dialects-gen command is a utility used to automate the generation of MAVLink dialect code within the gomavlib repository. It performs the following high-level workflow:

1. Fetches the latest MAVLink definitions: It queries the GitHub API to find the latest commit SHA from the official mavlink/mavlink repository.
2. Downloads XML definitions: It iterates through the message_definitions/v1.0 directory of the MAVLink repository and downloads the .xml files.
3. Imports dialects: For each XML file, it invokes the dialect-import tool (via go run ../../cmd/dialect-import --link <url>) to generate the Go source code.
4. Generates test suites: It automatically creates unit tests for the newly generated dialects, including:
   • dialect_test.go: Tests the dialect.ReadWriter initialization.
   • enum_*_test.go: Tests the MarshalText, UnmarshalText, and String methods for generated enums.
   • package_test.go: Provides common test cases for enum unmarshaling/marshaling.

Note: This tool is designed to be run within the repository structure, as it relies on the relative path ../../cmd/dialect-import to perform the actual code generation.

# This tool is typically run as a command within the repository environment.
# It automates the process of fetching, importing, and testing MAVLink dialects.
# It requires the 'dialect-import' tool to be available at ../../cmd/dialect-import
```bash
go run cmd/dialects-gen/main.go

The Endpoint interface defines the requirements for a transport layer that provides communication channels for MAVLink. To implement a custom transport (e.g., for a specific serial port, network socket, or radio hardware), your type must satisfy the following methods:

• init(node *Node) error: Initializes the endpoint with a reference to the MAVLink Node.
• isEndpoint() : A marker method to identify the type as an endpoint.
• close() : Closes the underlying transport.
• oneChannelAtAtime() bool: Returns true if the endpoint can only support one communication channel at a time.
• isDatagram() bool: Returns true if the endpoint uses a datagram-based protocol (like UDP) rather than a continuous stream.
• provide() (string, io.ReadWriteCloser, error): Returns a unique identifier for the endpoint, an io.ReadWriteCloser for data transmission, and an error if the provider fails.

type MyCustomEndpoint struct {
    // implementation fields
}

func (e *MyCustomEndpoint) init(node *Node) error {
    // initialization logic
    return nil
}

func (e *MyCustomEndpoint) isEndpoint() {}

func (e *MyCustomEndpoint) close() {
    // cleanup logic
}

func (e *MyCustomEndpoint) oneChannelAtAtime() bool {
    return true
}

func (e *MyCustomEndpoint) isDatagram() bool {
    return false
}

func (e *MyCustomEndpoint) provide() (string, io.ReadWriteCloser, error) {
    return "my-endpoint-id", myReadWriteCloser, nil
}

The Node provides several methods to send data through its managed channels. You can send either high-level message.Message objects (which the node will automatically encode using the provided dialect) or low-level frame.Frame objects (used for routing pre-existing frames).

Sending Messages

Use these methods when you have a structured MAVLink message. The node handles encoding and checksums.

• WriteMessageTo(channel *Channel, m message.Message) error: Writes a message to a specific channel.
• WriteMessageAll(m message.Message) error: Writes a message to all active channels.
• WriteMessageExcept(exceptChannel *Channel, m message.Message) error: Writes a message to all channels except the one specified.

Sending Frames

Use these methods when you are routing existing frames (e.g., from another node). Since frames are already formed, the node will recompute checksums and signatures if necessary via FixFrame logic internally.

• WriteFrameTo(channel *Channel, fr frame.Frame) error: Writes a frame to a specific channel.
• WriteFrameAll(fr frame.Frame) error: Writes a frame to all active channels.
• WriteFrameExcept(exceptChannel *Channel, fr frame.Frame) error: Writes a frame to all channels except the one specified.

// Writing a message to a specific channel
err := node.WriteMessageTo(myChannel, myMessage)

// Writing a message to all channels
err := node.WriteMessageAll(myMessage)

// Writing a pre-existing frame to all channels
err := node.WriteFrameAll(myFrame)