Guide
#Embed in a page
Load the library once, from a copy next to your page or from the CDN (see installation), then supply a scenario in one of three ways.
#Inline JSON
<bus-diagram>
<script type="application/json">
{ "formatVersion": 2, "lines": [{ "address": "1.1" }], "devices": [] }
</script>
</bus-diagram>Inline JSON keeps the scenario with the component and works offline. The browser treats the script as data rather than executable JavaScript.
#Another JSON block or a file
<bus-diagram scenario="#example-scenario"></bus-diagram>
<script type="application/json" id="example-scenario">
{ "formatVersion": 2, "lines": [{ "address": "1.1" }], "devices": [] }
</script>
<bus-diagram src="scenarios/status-feedback.json"></bus-diagram>A src file requires an HTTP server in browsers that restrict local file:// reads. If src changes repeatedly, only the latest request is applied.
#JavaScript
const diagram = BusDiagram.create("#example", scenario, {
monitor: false,
toolbar: "compact",
});
diagram.on("telegram", (telegram) => console.log(telegram.destination));The scenario argument can be an object, a JSON URL, or a #id selector for a JSON block. See the JavaScript API.
#Display options
Options can be set as HTML attributes or JavaScript properties. See the options reference.
<bus-diagram toolbar="compact" monitor="false" description="false" speed="0.35"></bus-diagram><bus-diagram toolbar="compact" monitor="false" description="false">
<script type="application/json">
{
"formatVersion": 2,
"title": "Control roller shutters",
"description": "A shutter uses two objects: up/down for a long press and stop/step for a short press. Key 4 lowers the shutter and turns on L1 with one telegram. The supervisor displays the reported position.",
"lines": [{ "address": "1.1", "name": "Example line" }],
"topology": { "ip": "lineCouplers" },
"groupAddresses": [
{ "address": "2/1/1", "name": "Shutter 1 up/down", "dpt": "1.008" },
{ "address": "2/2/1", "name": "Shutter 1 stop/step", "dpt": "1.007" },
{ "address": "2/1/2", "name": "Shutter 1 down + light", "dpt": "1.008" },
{ "address": "2/4/1", "name": "Shutter 1 position", "dpt": "5.001" },
{ "address": "1/1/1", "name": "L1 lighting", "dpt": "1.001" }
],
"devices": [
{
"id": "sup",
"name": "Supervisor",
"kind": "supervisor",
"behavior": "display/v1",
"description": "The supervisor does not control the actuator; it observes commands and displays position feedback.",
"objects": [
{
"id": "md",
"name": "Shutter 1 direction",
"ga": "2/1/1",
"dpt": "1.008",
"port": "display",
"flags": { "W": true, "T": false }
},
{
"id": "pos",
"name": "Shutter 1 position",
"ga": "2/4/1",
"dpt": "5.001",
"port": "display",
"flags": { "W": true, "T": false }
}
]
},
{
"id": "pushButton",
"name": "Push-button",
"address": "1.1.1",
"kind": "pushButton",
"behavior": "pushButton/v1",
"description": "Each key has its own objects, even when they share a group address. Key 1 controls the shutter with one key (long press reverses direction; short press stops). Key 2 raises and Key 3 lowers it (long press moves; short press stops or steps). Key 4 lowers the shutter and turns on the light.",
"objects": [
{
"id": "key1Long",
"name": "Key 1 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key1Short",
"name": "Key 1 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key2Long",
"name": "Key 2 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key2Short",
"name": "Key 2 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key3Long",
"name": "Key 3 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key3Short",
"name": "Key 3 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key4",
"name": "Key 4",
"ga": "2/1/2",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
}
],
"buttons": [
{
"id": "button-0",
"label": "Key 1",
"short": { "object": "key1Short", "value": 0 },
"long": { "object": "key1Long", "value": "toggle" }
},
{
"id": "button-1",
"label": "Key 2",
"icon": "up",
"short": { "object": "key2Short", "value": 0 },
"long": { "object": "key2Long", "value": 0 }
},
{
"id": "button-2",
"label": "Key 3",
"icon": "down",
"short": { "object": "key3Short", "value": 1 },
"long": { "object": "key3Long", "value": 1 }
},
{
"id": "button-3",
"label": "Key 4",
"icon": "down",
"press": { "object": "key4", "value": 1 }
}
]
},
{
"id": "shutterActuator",
"name": "Shutter actuator",
"address": "1.1.3",
"kind": "shutterActuator",
"behavior": "shutterActuator/v1",
"objects": [
{
"id": "md",
"name": "MD 1",
"ga": ["2/1/1", "2/1/2"],
"dpt": "1.008",
"port": "move",
"channel": "shutter1",
"flags": { "W": true, "T": false }
},
{
"id": "st",
"name": "Stop 1",
"ga": "2/2/1",
"dpt": "1.007",
"port": "stopStep",
"channel": "shutter1",
"flags": { "W": true, "T": false }
},
{
"id": "pos",
"name": "Position 1",
"ga": "2/4/1",
"dpt": "5.001",
"port": "positionStatus",
"channel": "shutter1",
"flags": { "W": true, "T": true }
}
],
"channels": [
{
"id": "shutter1",
"label": "Shutter 1",
"parameters": { "estimatedTravelTimeMs": 10000 },
"equipment": { "type": "shutter", "parameters": { "actualTravelTimeMs": 10000 } }
}
]
},
{
"id": "switchActuator",
"name": "Four-output switching actuator",
"address": "1.1.2",
"kind": "switchActuator",
"behavior": "switchActuator/v1",
"objects": [
{
"id": "c1",
"name": "Channel 1",
"ga": ["1/1/1", "2/1/2"],
"dpt": "1.001",
"port": "switch",
"channel": "s1",
"flags": { "W": true, "T": false }
},
{
"id": "c2",
"name": "Channel 2",
"ga": [],
"dpt": "1.001",
"port": "switch",
"channel": "s2",
"flags": { "W": true, "T": false }
},
{
"id": "c3",
"name": "Channel 3",
"ga": [],
"dpt": "1.001",
"port": "switch",
"channel": "s3",
"flags": { "W": true, "T": false }
},
{
"id": "c4",
"name": "Channel 4",
"ga": [],
"dpt": "1.001",
"port": "switch",
"channel": "s4",
"flags": { "W": true, "T": false }
}
],
"channels": [
{ "id": "s1", "label": "L1", "equipment": { "type": "lamp" } },
{ "id": "s2", "label": "L2", "equipment": { "type": "lamp" } },
{ "id": "s3", "label": "L3", "equipment": { "type": "lamp" } },
{ "id": "s4", "label": "L4", "equipment": { "type": "lamp" } }
]
}
],
"options": { "speed": 1, "filterTables": false }
}
</script>
</bus-diagram>#Several diagrams
A page can show several instances, even with the same scenario. Each has an independent clock and state. See the two-instance example.
#Static-site Markdown
Most static-site generators allow HTML elements in Markdown, although some require an explicit setting. Keep the <bus-diagram> and its nested JSON <script> in the same HTML block. Load the bundle once from the site layout:
<script defer src="assets/bus-diagram.js"></script>If a content platform removes scripts, publish a standalone page and link to it or embed it in an iframe.