Skip to main content

Apply one configuration template to many Brainboxes devices with BB-Eco

This guide covers giving many Brainboxes devices the same configuration in one go with the BB-Eco desktop app or CLI. Use it when commissioning a line of identical devices, rolling out a new site standard, or putting a group of devices back on their agreed settings after drift.

Before you start​

Step 1 - Make the template fit every device​

A template exported from one device describes that device, but it is portable: the MAC address, IP address and firmware version are not part of it. Before applying it to many devices:

  1. Set anything that should differ between devices to null, or remove it. A null field or a missing section means don't touch, so each device keeps its own value. The device name is usually one of these.
  2. Leave network.staticIp as null. One address applied to many devices would give them all the same address. See Static IP addresses.
  3. Check the family: an ED template applies only to ED devices and an ES template only to ES devices. To narrow it further, list the models in compatibleModels.

Every key, its factory default and the values the firmware accepts are in the template format reference.

Step 2 - Select the devices​

On the dashboard:

  • Card view: tick the box in the top-right corner of an online card. It shows when you point at a card, and on every online card once one is ticked. Shift-click a box to tick a range, or Cmd-click (macOS) or Ctrl-click (Windows, Linux) a card.
  • List view: click a row, Shift-click to select a range, and Cmd-click or Ctrl-click to add or remove one row.

Both views share one selection, so switching between them keeps it. A new search or filter clears it, and so does Escape. The top bar shows how many devices are selected and an Apply template... button.

Step 3 - Choose the template and preview​

  1. Click Apply template.... The dialog lists every selected device with its model, name and IP address. Devices that have no configuration template (managed switches, BB-400 edge controllers) are marked Not supported, and devices that are offline, upgrading or awaiting recovery are marked as such; they stay in the list but nothing is sent to them.
  2. Click Choose template... and pick the file. BB-Eco checks it straight away and shows its family, models and sections next to the button. If something in the file is wrong, the dialog lists each mistake with the number of errors and a link to the part of the template format that explains it, and Preview stays off until you choose a corrected file.
  3. Leave Preview only (dry run) ticked and click Preview on N devices.

The preview reads each device and makes every comparison the apply would make, and writes nothing. The report groups the devices by outcome:

GroupThe row says
PreviewedHow many settings would change and how many already match, for example 2 settings would change, 1 already match.
FailedWhy this device can't take the template (the wrong family, a value the device doesn't accept, the device didn't answer), with a link to the relevant part of the template format where there is one.
Not supportedThe device has no configuration template.
SkippedThe device was offline, upgrading or awaiting recovery.

Step 4 - Apply​

Click Apply to N devices. The apply goes only to the devices under Previewed: a device that failed the preview would fail again, so it is left out. To apply to the whole selection without a preview, click Back, which returns to the device list with Preview only (dry run) cleared.

For each device BB-Eco writes only the settings that differ, in the apply order that keeps a network change from cutting off the rest. When a change restarts the device, BB-Eco waits for it to come back before reporting it. The report then groups every device under Applied (2 settings applied, 1 already matched), No changes (everything already matched, so nothing was sent) or Failed (with the reason).

Each device that was changed becomes its new baseline, so its Configuration Status reads in sync with the template you just applied. A device under No changes keeps its baseline as it was.

From the CLI​

bb-eco template apply takes several devices before the file and applies to each in turn, with a report row per device:

bb-eco template apply 192.168.1.107 192.168.1.108 192.168.1.109 line-a-standard.json --dry-run
bb-eco template apply 192.168.1.107 192.168.1.108 192.168.1.109 line-a-standard.json
Device            IP             Model   Outcome     Applied  Matched  Failed  Detail
Line 1            192.168.1.107  ES-522  Applied     3        29       0       Applied 3 settings; 29 already matched.
Line 2            192.168.1.108  ES-522  No changes  0        32       0       No changes — all 32 settings already match the device. Nothing was sent.
ES-522 2-Port     192.168.1.109  ES-522  Failed      0        0        32      [compatibility] description.xml: Failed to fetch device description

2 of 3 device(s) applied, 1 failed.

Options worth knowing:

  • --all - apply to every ED and ES device found on the network instead of naming them.
  • --dry-run - preview: report what would change on each device and write nothing.
  • --force - skip the confirmation prompt (for scripts).
  • --json or --csv - the report as one JSON document or as the table alone.

The full option list is in the bb-eco template apply reference.

More resources​