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 plugin which is used to send LIN traffic to a physical Kvaser adapter.

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 VCAN network with plugin.* options is created via the Docker API, RemotiveBus sends a start message to the plugin and waits up to 5 seconds for a response. If the plugin responds with "success": false or doesn't respond within the timeout, the network creation fails and Docker receives an error.
2. Network removal: Before the network is removed, RemotiveBus sends a stop message to the plugin. Stop errors are logged but don't prevent the network from being removed (best-effort).

Request message structure

Messages sent to the plugin are json objects:

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

Field	Type	Required	Description
version	number	yes	Version of the message format. Always 1 for now.
action	string	yes	Command type, must be start or stop.
bus.type	string	yes	CAN bus type, is currently 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 (e.g. kvaser). This is used to find the domain socket of the plugin
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:

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

and the corresponding stop command:

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

Response message structure

After receiving a start or stop message, the plugin must write a json response terminated by a newline (\n) back on the same socket connection.

Success:

{"success": true}

Failure:

{"success": false, "error": "Human-readable description of what went wrong"}

Field	Type	Required	Description
success	boolean	yes	true if the operation succeeded, false otherwise.
error	string	no	Human-readable error message. Required when success is false.

Timeout

RemotiveBus waits up to 5 seconds for a response. If no response arrives within that window, the operation is treated as a failure with the error message "Plugin '<driver>' did not respond within 5s".

Error propagation

Operation	Plugin response	Outcome
start	success: true	Network created successfully
start	success: false	Network creation fails; error message returned to Docker
start	No response / timeout	Network creation fails with timeout error
stop	success: true	Network deleted normally
stop	success: false	Error logged; network deleted anyway (best-effort)
stop	No response / timeout	Timeout logged; network deleted anyway (best-effort)

Existing plugins

Kvaser RemotiveBus plugin

The Kvaser RemotiveBus plugin is an open source plugin for sending LIN traffic over Kvaser Hybrid hardware adapters. It also serves as a reference implementation on how to write RemotiveBus plugins.

https://github.com/remotivelabs/kvaser-remotivebus-plugin