4.7 Bridges

A bridge connects a running model to another system. An inbound route turns a message from outside into an event of the model. An outbound route sends a message whenever a property, the active states of a state machine or an event has something new. Bridges run inside the IDE, with a run, and stop with it.

KindInbound messages arrive asOutbound messages go out as
httpPOST or PUT requests to a path of the bridge's own HTTP serverPOST requests to a URL
mqttMessages on an MQTT topic of a brokerMessages published on an MQTT topic
rosMessages on a ROS topic, through a rosbridge serverMessages published on a ROS topic

4.7.1 The bridge file#

A bridge is a JSON file named *.kbridge.json in the project. The Project tool window lists the bridge files in a section of their own at the bottom.

KeyValue
kindhttp, mqtt or ros.
settingsAn object of texts with the settings of the kind, see 4.7.3 Settings.
inboundThe inbound routes, a list of objects.
outboundThe outbound routes, a list of objects.

The keys of an inbound route:

KeyValue
fromWhere the message arrives: a path of the HTTP server such as /press, an MQTT topic filter, or a ROS topic.
eventThe event it becomes, as domain and name with a slash between them, such as switch/press.
payloadOptional. An object that gives each field of the event's payload a value, see 4.7.2 From message to event and back.
policy, limit, periodMsOptional. What happens when messages come too fast, see below.
typeROS only. The type of the messages on the topic, such as std_msgs/msg/Bool.

The keys of an outbound route:

KeyValue
propertyFollows a property, as object key and property with a slash between them, such as bulb/watts.
stateFollows the active states of the state machine attached to the object, such as lamp.
eventFollows an event that a state machine raises, as domain and name, such as switch/press.
toWhere the message goes: a URL for HTTP, a topic for MQTT and ROS.
policy, limit, periodMsOptional, as for inbound routes.
typeROS only. The type of the messages, std_msgs/msg/String if the route names none.

An outbound route has exactly one of property, state and event.

policyEffect
queueKeeps the messages in their order. When more than limit wait, the oldest one is dropped. limit is 64 unless the route sets it. This is the policy of a route without policy.
latestKeeps only the newest message. A message that still waits when the next one arrives is dropped.
sampleHands on at most one message per periodMs milliseconds, always the newest one. periodMs is required.

A route with a problem is left out, and the other routes of the file stay.

4.7.2 From message to event and back#

An inbound route without payload hands the body of the message on. A body that is a JSON object becomes the payload of the event. Any other body, also an empty one, gives an event without a payload. With "payload": {} the event never has a payload.

An inbound route with payload builds the payload field by field. A value that starts with $ is a path into the body, and any other value is taken as it is. A path is $ for the whole body, $.a.b for a member, and $.a[0] for an item of a list. With a path, the body must be JSON and the path must lead to a value. Otherwise the message is refused and counted as failed, with a reason such as The message is not JSON.

{ "from": "/dim", "event": "switch/dim", "payload": { "bright": "$.bright" } }

An outbound route sends JSON. A property route sends the value of the property whenever it changes. A state route sends the names of the active states as a JSON array, outermost first, such as ["on","full"], whenever they change. An event route sends the payload of the event, or {} for an event without one. Property and state routes hear the model only while the run has observation on, see 4.5.4.3 The Model pane.

4.7.3 Settings#

The settings are texts. A missing value or one that makes no sense takes its default.

4.7.3.1 HTTP#

SettingDefaultMeaning
host127.0.0.1The address the server listens on. The default lets only programs on the same machine in.
port8090The port of the server. 0 lets the system pick a free one.
timeoutMs3000How long an outbound POST waits for its answer.

The server answers a POST or PUT to the path of an inbound route with 202 at once, because the model takes the event on a later tick. A path without a route gets 404, and another method on the path of a route gets 405. A GET of / lists the paths of the inbound routes, as {"inbound":["/dim","/press","/smash"]}. An outbound message is a POST of JSON to the URL of its route. An answer in the 200 range counts as delivered. The bridge has no authentication.

{
  "kind": "http",
  "settings": { "port": "8090" },
  "inbound": [
    { "from": "/press", "event": "switch/press" }
  ],
  "outbound": [
    { "property": "bulb/watts", "to": "http://localhost:9000/lamp/watts" }
  ]
}

4.7.3.2 MQTT#

SettingDefaultMeaning
brokertcp://localhost:1883The broker. ssl://, tls:// or mqtts:// encrypts the connection, with 8883 as the default port.
clientIdkarpfen- and the file name without .kbridge.jsonThe name of the bridge at the broker. A broker allows one connection per name.
username, passwordnoneThe login at the broker. The password is stored as plain text in the file.
qos1The quality of service of subscriptions and published messages: 0, 1 or 2.
retainfalsetrue makes the broker keep the last message of each topic.
timeoutMs5000How long the bridge waits for the broker.

The bridge speaks MQTT 3.1.1. The from of an inbound route is a topic filter and may use + for one level and # for the rest. The body of a message is read as UTF-8 text. When the connection breaks, the bridge connects again on its own, and outbound messages fail in the meantime.

{
  "kind": "mqtt",
  "settings": { "broker": "tcp://localhost:1883" },
  "inbound": [
    { "from": "home/lamp/press", "event": "switch/press" }
  ],
  "outbound": [
    { "state": "lamp", "to": "home/lamp/state", "policy": "latest" }
  ]
}

4.7.3.3 ROS#

SettingDefaultMeaning
urlws://localhost:9090The WebSocket address of the rosbridge server.
ros1falsetrue for a ROS 1 system.
timeoutMs5000How long connecting to the server may take.

The ROS side needs the package rosbridge_suite, started. A type is written as in ROS 2, std_msgs/msg/Bool, or as in ROS 1, std_msgs/Bool, and the bridge writes it the way the system expects. An inbound route without a type works only for a topic that exists in ROS already. An outbound value that is a JSON object is the message itself. Any other value goes into the member data, as the standard types such as std_msgs/msg/Float64 expect, and for std_msgs/msg/String a value that is no text is written as its JSON text, such as ["on"]. When the connection breaks, the bridge connects again every few seconds.

{
  "kind": "ros",
  "settings": { "url": "ws://localhost:9090" },
  "inbound": [
    { "from": "/lamp/dim", "event": "switch/dim", "payload": { "bright": "$.data" }, "type": "std_msgs/msg/Bool" }
  ],
  "outbound": [
    { "property": "bulb/watts", "to": "/lamp/watts", "type": "std_msgs/msg/Float64", "policy": "latest" }
  ]
}

4.7.4 The bridge form#

A bridge file opens in a form, not as text. A double-click on it in the Project tool window opens it. Run > Configure Bridge asks Choose the bridge to configure: with the entry New bridge among the bridges.

Part of the formContent
Name, KindThe file name without .kbridge.json, and HTTP, MQTT or ROS. Changing the name renames the file.
SettingsThe settings of the kind: Host, Port and Timeout in ms; Broker, Client id, User name, Password, QoS (0, 1 or 2), Timeout in ms and The broker keeps the last message of each topic; Rosbridge server, Timeout in ms and Legacy ROS 1 system. An empty field shows its default.
Messages that become eventsThe inbound routes, each as Inbound route N with From, Event, Payload and for ROS the Message type. Payload is either The body of the message or a list of fields made with Add payload field. Add inbound route adds one.
What the model reportsThe outbound routes, each as Outbound route N with Follows (A property, Active states or An event), the property, state machine or event, To, and for ROS the Message type. Add outbound route adds one.
If too fastThe policy of a route: Queue, Keep the latest or One per period.
PickLists the events, properties and state machines of the project to choose from.
RemoveRemoves a route or a payload field.
Save, CancelWrites the file, or closes the form without writing.

A file that the form cannot read in full opens with the note The file had problems. What could not be read is left out, and saving writes the file without it.

4.7.5 Starting bridges with a run#

The run dialog has one box per bridge file of the project, see 4.5.3 The run dialog. The ticked bridges start once the environment runs and stop with it. A bridge that fails does not stop the run. The bridges key of a descriptor is not used.

4.7.6 The bridges of a run#

The Log pane lists the bridges of the selected run below the deployment, one line each.

LineMeaning
http.kbridge.json: not runningThe bridge has not started or has stopped.
http.kbridge.json: startingThe bridge connects.
http.kbridge.json: running, 3 in, 1 outThe bridge runs and has handed on 3 messages to the model and 1 message out.
http.kbridge.json: failed. <reason>The bridge could not start.

Below a bridge, a route with trouble gets a line such as /dim to switch/dim: 2 dropped, 1 failed, with the last error in parentheses.

4.7.7 Trying the HTTP bridge#

The lamp example has http.kbridge.json with three inbound routes. Run the lamp with the box http.kbridge.json ticked, then in a terminal:

curl http://127.0.0.1:8090/
curl -X POST http://127.0.0.1:8090/press
curl -X POST http://127.0.0.1:8090/dim -d '{"bright": false}'

The first command prints the paths {"inbound":["/dim","/press","/smash"]}. The second presses the wall switch, and the lamp goes on. The third makes it one step dimmer. The events show in the Events pane with the source external.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.