RemotiveBus plugin API

Because Docker networks are created and destroyed dynamically, things like monitoring and bridging can be challenging. RemotiveBus supports plugins that are notified of network lifecycle events.

One example is the RemotiveBus Kvaser Lin plugin which is used to bridge CAN traffic to a physical LIN adapter by Kvaser. It waits until it's notified that a CAN network for this purpose is created, then starts forwarding the CAN traffic to LIN. WHen the network is torn down, it gracefully stops the communication.

Plugin communication overview

RemotiveBus plugins communicate with the main service using Unix domain sockets. When a network is created or removed, RemotiveBus sends json messages to the appropriate plugin socket, allowing plugins to react to network lifecycle events.

• Socket location: RemotiveBus is responsible for hosting a directory where the Unix domain sockets are located. This directory is located at /run/remotivebus/plugins/.
• Socket creation: It's the responsibility of the plugin to create and bind to its socket when the plugin starts and to remove it when the plugin stops running.
• Plugin ID / Socket naming: The plugin ID is a short, unique identifier for a particular plugin and specified in the plugin.driver option in the Docker network configuration. The Unix Domain Socket name must be identical to the plugin ID.

Command flow

1. Network creation: When a network with plugin.* options is created, RemotiveBus sends a start message to the plugin.
2. Network removal: Before the network is removed, RemotiveBus sends a stop message to the plugin.

Message structure

Messages sent to the plugin are json objects:

{
  "action": "start" | "stop",
  "bus": {
    "type": "vcan",
    "device": "mybus",
    "baudrate": 19200,
    "host_device": "myhostbus",
    "plugin": {
        "driver": "mypluginid"
        ...
    }
  }
}

Field	Type	Required	Description
action	string	yes	Command type, must be start or stop.
bus.type	string	yes	CAN bus type, always vcan.
bus.device	string	yes	Name of CAN device inside Docker. Docker appends a trailing 0.
bus.host_device	string	no	Name of CAN interface on host machine
bus.baudrate	integer	no	CAN baud rate to apply
bus.baudrate_fd	integer	no	CAN-FD baud rate to apply
bus.txqueuelen	integer	no	Override network interface write buffer size for physical devices
bus.plugin.driver	string	yes	Name of plugin. This is used to find the domain socket
bus.plugin.*	any	no	Additional plugin options

Examples

Given this configuration:

{
	"type": "vcan",
	"device": "mybus",
	"baudrate": "19200",
	"host_device": "myhostbus",
	"plugin.driver": "mypluginid",
	"plugin.name": "My Can"
}

The plugin receives the following start command:

{
	"action": "start",
	"bus": {
		"type": "vcan",
		"device": "mybus",
		"baudrate": 19200,
		"host_device": "myhostbus",
		"plugin": {
			"driver": "mypluginid",
			"name": "My Can"
		}
	}
}

and the corresponding stop command:

{
	"action": "stop",
	"bus": {
		"type": "vcan",
		"device": "mybus",
		"baudrate": 19200,
		"host_device": "myhostbus",
		"plugin": {
			"driver": "mypluginid",
			"name": "My Can"
		}
	}
}