gomavproxy

gomavproxy

gomavproxy is a library that implements a proxy and router functionality for Mavlink protocol. It has a minimalistic and developer-friendly interface for manipulation multiple mavlink streams in runtime. Also, it has flexible filtering functionality which helps to change mavlink streams. Filters support removing, rewriting, and injecting messages.

MAVLink is a very lightweight messaging protocol for communicating with drones (and between onboard drone components).

Features

• Creating multiple listeners and multiple filters in runtime
• Listener supports one upstream and multiple downstream
• Listener can be launched without downstreams. Only for filter processing.
• Upstreams support TCP, UDP, and SERIAL device source
• Downstreams support TCP and UDP in server mode
• Listener can have multiple filters
• Filters can be chained to the listeners by name or label set. It allows flexible configure handler sequences for each listener.
• Filters support rewriting and removing mavlink frames
• Listeners support injecting mavlink frame
• Filters can have multiple mavlink frame handlers
• Frame handlers can be sync and async
• Frame handlers subscribe to frames by payload types. Supports next payload types: any, message id, command id, command id ack.
• Frame handlers sorting by priority when we have several handlers with the same subscription. Handlers with the highest priority will be executed first.
• Frame sequence id control. It rewrites sequence id in a frame for saving packet loss detection behavior when some frames were injected and removed.
• Mavlink dialect agnostic**

** Only if you want to remove or inject frames in some mavlink component that uses custom dialect. You must specify this dialect. In all other cases, it is not necessary.

Install

go get mavpoint.io/gomavproxy

Usage

Creating proxy

proxy := gomavproxy.New(logger)

Adding listener which proxing mavlink stream from serial device to udp port on localhost (port will be selected automatically if it not specify)

listener, err := proxy.RegisterListener(
    &gomavproxy.ListenerMetadata{
        Name: "superlistener",
        Labels: map[string]string{"group":"somegroup","tag":"sometag"},
    },
    &gomavproxy.ListenerSpec{
        Upstream: &gomavproxy.ListenerUpstreamSerial{
            Device: "/path/to/device",
            Baudrate: 57600,
        },
        Downstreams: []gomavproxy.ListenerDownstream{
            &gomavproxy.ListenerDownstreamUDP{Host: "127.0.0.1"},
        },
    },
)

Add filter which will be chained with all listeners (exists and further created) which have label with name "tag" and value "sometag". Filter has one handler which will be processing all frames with heartbeat payload from upstream.

filter, err := proxy.RegisterFilter(
    &gomavproxy.FilterMetadata{Name: "first"},
    &gomavproxy.FilterSpec{
        Listeners: &gomavproxy.ObjectSelector{
            Labels: &metav1.LabelSelector{
                MatchLabels: map[string]string{"tag":"sometag"},
            },
        },
        Handlers: []*gomavproxy.FilterHandler{{
            Spec: &gomavproxy.HandlerSpec{
                Async: false, 
                Priority: 0,
            },
            Frame: &gomavproxy.HandlerFrame{
                Source: gomavproxy.FrameSourceUpstream,
                Payload: gomavproxy.FramePayloadTypeMessage((&common.MessageHeartbeat{}).GetID()),
            },
            Exec: func(
                lm *gomavproxy.ListenerMetadata,
                frm *gomavproxy.Frame,
            ) (gomavproxy.HandlerExecResponse, error) {
                return gomavproxy.HandlerExecResponseRewrite(frm.Payload), nil
            },
        }},
    },
)

Add filter which will be chained with all listeners (exists and further created) which have name "superlistener". Filter has one handler which will be removing all frames with request video stream information payload from downstreams.

filter, err := proxy.RegisterFilter(
    &gomavproxy.FilterMetadata{Name: "first"},
    &gomavproxy.FilterSpec{
        Listeners: &gomavproxy.ObjectSelector{
            Names: []string{"superlistener"},
        },
        Handlers: []*gomavproxy.FilterHandler{{
            Spec: &gomavproxy.HandlerSpec{
                Async: false, 
                Priority: 0,
            },
            Frame: &gomavproxy.HandlerFrame{
                Source: gomavproxy.FrameSourceDownstream,
                Payload: gomavproxy.FramePayloadTypeCommandRequestMessage((&common.MessageVideoStreamInformation{}).GetID()),
            },
            Exec: func(
                lm *gomavproxy.ListenerMetadata,
                frm *gomavproxy.Frame,
            ) (gomavproxy.HandlerExecResponse, error) {
                return gomavproxy.HandlerExecResponseRemove, nil
            },
        }},
    },
)

Frame sequence ID control and checksum recalculation

Each mavlink frame has a sequence id field that takes part in the frame loss detection process. Each vehicle component that produces mavlink messages has its pair systemID and componentID. When it sent a message, the sequenceID counter is incrementing. If the consumer sees a difference greater than one between the sequence id current frame and sequence id previous frame within one component then we lost some frame or frames.

That behavior is very simple and useful. But if we want to implement drop or inject frames we need to deal something with that.

That project has an implementation that stores the shift of sequenceIDs for each component separately and rewrites it if it is necessary. When we rewrite some fields in the frame then it becomes invalid. Because each mavlink frame has a checksum field. This leads to checksum recalculation by the proxy for all frames within components with a non-zero shift of sequence id. But if we make inject after dropping within one component then sequence id will become zero again. The more components with non-zero sequence shifts, the higher the delay will be.

TODO List

• SequenceID auto adjustment by heartbeats
• More flexible handler subscription on frame

Links

Related projects

• https://github.com/aler9/gomavlib
• https://github.com/aler9/mavp2p

Mavlink

• main website https://mavlink.io/en/
• packet format https://mavlink.io/en/guide/serialization.html
• common dialect https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml