FBP Network Protocol

The Flow-Based Programming network protocol (FBP protocol) has been designed primarily for flow-based programming interfaces like the Flowhub to communicate with various FBP runtimes. However, it can also be utilized for communication between different runtimes, for example server-to-server or server-to-microcontroller.

Implementations

Clients

Runtimes

Some examples have also been created, to help implementors.

Test suite

The fbp-protocol tool provides a set of tests for FBP protocol implementations.

Changes

Basics

The FBP protocol is a message-based protocol that can be handled using various different transport mechanisms. The messages are designed to be independent, and not to form a request-response cycle in order to allow highly asynchronous operations and situations where multiple protocol clients talk with the same runtime.

There are currently three transports utilized commonly:

Different transports can be utilized as needed. It could be interesting to implement the FBP protocol using MQTT, for instance.

Sub-protocols

The FBP protocol is divided into four sub-protocols, or “channels”:

Message structure

This document describes all messages as the data structures that are passed. The way these are encoded depends on the transport being used. For example, with WebSockets all messages are encoded as stringified JSON.

All messages consist of three parts:

The keys listed in specific messages are for the message payloads. The values are strings unless stated differently.

Runtime protocol

When a client connects to a FBP procotol it may choose to discover the capabilities and other information about the runtime.

error

Runtime error

getruntime

Request the information about the runtime. When receiving this message the runtime should response with a runtime message.

packet

Runtimes that can be used as remote subgraphs (i.e. ones that have reported supporting the protocol:runtime capability) need to be able to receive and transmit information packets at their exposed ports. These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client.

ports

Message sent by the runtime to signal its available ports. The runtime is responsible for sending the up-to-date list of available ports back to client whenever it changes.

runtime

Response from the runtime to the getruntime request.

Graph protocol

This protocol is utilized for communicating about graph changes in both directions.

error

Graph error

clear

Initialize an empty graph.

addnode

Add node to a graph.

removenode

Remove a node from a graph.

renamenode

Change the ID of a node in the graph

changenode

Change the metadata associated to a node in the graph

addedge

Add an edge to the graph

removeedge

Remove an edge from the graph

changeedge

Change an edge’s metadata

addinitial

Add an IIP to the graph

removeinitial

Remove an IIP from the graph

addinport

Add an exported inport to the graph.

removeinport

Remove an exported port from the graph

renameinport

Rename an exported port in the graph

addoutport

Add an exported outport to the graph.

removeoutport

Remove an exported port from the graph

renameoutport

Rename an exported port in the graph

addgroup

Add a group to the graph

removegroup

Remove a group from the graph

renamegroup

Rename a group in the graph.

changegroup

Change a group’s metadata

Component protocol

Protocol for handling the component registry.

error

Component error

list

Request a list of currently available components. Will be responded with a set of component messages.

getsource

Request for the source code of a given component. Will be responded with a source message.

source

Source code for a component. In cases where a runtime receives a source message, it should do whatever operations are needed for making that component available for graphs, including possible compilation.

component

Transmit the metadata about a component instance.

Network protocol

Protocol for starting and stopping FBP networks, and finding out about their state.

error

An error from a running network, roughly similar to STDERR output of a Unix process, or a line of console.error in JavaScript.’

start

Start execution of a FBP network based on a given graph.

getstatus

Get the current status of the runtime. The runtime should respond with a status message.

stop

Stop execution of a FBP network based on a given graph.

persist

Tells the runtime to persist the current state of graphs and components so that they are available between restarts. Requires the network:persist capability.

debug

Set a network into debug mode

edges

List of edges user has selected for inspection in a user interface or debugger, sent from UI to a runtime.

stopped

Inform that a given network has stopped.

started

Inform that a given network has been started.

status

Response to a getstatus message.

output

An output message from a running network, roughly similar to STDOUT output of a Unix process, or a line of console.log in JavaScript. Output can also be used for passing images from the runtime to the UI.’

processerror

When in debug mode, a network can signal an error happening inside a process.

icon

Icon of a component instance has changed.

connect

Beginning of transmission on an edge.

begingroup

Beginning of a group (bracket IP) on an edge.

data

Data transmission on an edge.

endgroup

Ending of a group (bracket IP) on an edge.

disconnect

End of transmission on an edge.

Trace protocol

This protocol is utilized for triggering and transmitting Flowtraces

start

Tracing was started

stop

Tracing was stopped

dump

undefined

clear

Tracing buffer was cleared