go-multibus

The go-multibus package brings a Multibus Module up after a controller boot, sets what each interface on its connector carries and publishes the battery cell voltages it reads over isoSPI. It runs as a background service on the controller, and its own terminal interface shows and changes the module settings while you commission a machine.

To use the command line interface, a wired ethernet and/or Wi-Fi connection is mandatory.

---

Installation

go-multibus comes from the GOcontroll apt repository. How to set up that repository is described in apt packages.

Refresh the package list:

apt-get update

Install the package:

apt-get install go-multibus

The installation enables the go-multibus service but does not start it, because the service resets the module when it starts.

The module reaches the controller over USB, through the OTG port of the controller, and that port has to be in host mode. When it is not, the installation switches it and reports The controller's OTG port has been switched to host mode. The change takes effect at the next boot; until then no module can enumerate over USB. Reboot the controller once in that case, and the service starts at boot.

Otherwise, start the service straight away:

systemctl start go-multibus

A new version is installed the same way: apt-get update followed by apt-get install go-multibus.

---

Note: the service resets the module whenever it brings it up, and only one program may hold the module at a time. The terminal interface does not start while the service runs, and gocontroll-cellmon serve must never run next to the service.

---

The service

The service is the systemd unit go-multibus.service, which runs go-multibus daemon. For every configured module it resets the module, starts the module application, configures the connector interfaces over SPI, waits for the module on USB, and then reads the cell data and publishes it. When a module disappears, the service starts that sequence again, so the module comes back without any action. If the process itself stops, systemd restarts it after five seconds.

To see what the service is doing, use the status command.

Command:

go-multibus status

Typical output:

state shows where the sequence of the module stands; running means the module is up and its data is published. With module firmware 0.1.0 the module reports no external supply, so the supply line reads not reported by this firmware. The cells line gives the number of cells, the pack voltage and the spread between the highest and lowest cell.

The service writes its messages to the journal:

journalctl -u go-multibus

When the controller is up and running and you only want to start the Multibus service once, while it is disabled, you can use the following command. Be aware that after a reboot of the controller, the service will NOT start again.

systemctl start go-multibus

If you want to start the Multibus service as quick as possible after a controller boot, simply enable the service. The installation already does this.

systemctl enable go-multibus

If you want to stop the Multibus service instantly, you can execute the following command. Be aware that after a controller boot, the Multibus service is starting again.

systemctl stop go-multibus

If you want to prevent the Multibus service from starting at boot, you need to disable the service.

systemctl disable go-multibus

---

The terminal interface

The terminal interface is meant for commissioning. It does not start while the service runs, so stop the service first:

systemctl stop go-multibus

Then open the interface by running go-multibus without a subcommand.

Command:

go-multibus

Typical output:

The list shows the five connector interfaces with their pins and mode, the isoSPI role and the external supply. Move with the arrow keys and press Enter to open the choices for a row; Left or Esc takes you back and q closes the tool. c shows the cell voltages and r restarts the module.

Interface 1 is always CAN. Interface 2 can be RS485, RS232 or off, interfaces 3 and 4 RS485, CAN or off, and interface 5 isoSPI or off.

Applying an interface mode stores it and resets the module, because the interface configuration reaches the module over SPI before USB comes up. The isoSPI role and the external supply are applied without a reset. Opening the interface does not reset the module; only r and applying a choice with Enter touch the hardware.

On module firmware 0.1.0 the supply row reads not supported by this firmware, and a module without a configured isoSPI role shows default with the role its firmware starts in.

Start the service again when you are done:

systemctl start go-multibus

---

Changing the configuration from the command line

Every setting of the terminal interface is also available as a command. For example, to make connector interface 3 a CAN bus:

go-multibus set 3 can

Typical output:

set only stores the change in the configuration file and does not touch a running module. Restart the service to apply it:

systemctl restart go-multibus

supply and role are stored and applied straight away when the module is reachable; when it is not, the next bring-up applies them. The supply takes off or a voltage such as 9, 9V or 9000mv:

go-multibus supply 9V

The isoSPI role is master or slave. Without an argument, role shows the configured role next to the one the module reports. Switching the role needs module firmware 0.3.0 or later.

go-multibus role slave

A role set with gocontroll-cellmon or gocontroll-modulebus only lasts until the module is next reset; the role that go-multibus role stores is pushed again at every bring-up.

---

The configuration file

The settings are stored in /etc/gocontroll/multibus.json. A missing file is a working configuration with the defaults, and a missing key falls back to its default. Show the stored configuration with:

go-multibus config

The keys for one module, with their defaults:

• slot: the controller slot of the module, 1 to 8. Default 8.
• interfaces: five modes, one per connector interface. Default can, rs485, can, rs485, isospi.
• cell_count: how many cells the battery side reports, 1 to 24. Default 12.
• module_poll_ms: how often the module polls the battery over isoSPI, in ms. Default 100.
• publish_interval_s: how often the service reads the module and rewrites the published file, in s. Default 0.5.
• bring_up_can: whether the service brings the CAN interfaces up. Default true.
• can_bitrate: the bitrate for those interfaces. Default 500000.
• output: where the cell data is published. Default /dev/shm/gocontroll/multibus-cells.json.
• supply_enabled and supply_mv: whether the external supply is on, and its setpoint in mV. Default off, 5000.
• isospi_role: master or slave, pushed at every bring-up. Left out, the module keeps the role its firmware starts in.

Note: the default slot is 8. Set slot to the slot your module is fitted in.

---

CAN interfaces and serial ports

The package installs udev rules that give the module buses fixed names, whatever controller they are on:

• mb_can1, mb_can2 and mb_can3 for CAN 1, CAN 2 and CAN 3;
• /dev/mb_serial1, /dev/mb_serial2 and /dev/mb_serial3 for RS485 1 or RS232 1, RS485 2 and RS485 3;
• /dev/mb_protocol for the protocol port of the module.

mb_can2 and /dev/mb_serial2 use the same connector pins, as do mb_can3 and /dev/mb_serial3; only one of each pair is live. The service only brings up the CAN interfaces whose connector interface is CAN: mb_can1 always, mb_can2 and mb_can3 when connector interfaces 3 and 4 are CAN.

go-multibus decides whether an interface is CAN or RS485. The bitrate and the other bus parameters belong to go-can, for example:

go-can set mb_can1 bitrate 500000

CAN FD on the module buses needs module firmware 0.3.0 or later.

---

Published data

The service publishes two JSON files in /dev/shm/gocontroll/: multibus-cells.json with the cell measurements and multibus-state.json with the state of the bring-up. Both files are replaced in one step, so a reader always sees a complete document and needs no locking.

In the cell document, branch on valid: it is true only when the isoSPI link works and the data is fresh. The cell voltages appear twice: cells_v is rounded for display, cells_100uv is the raw value in units of 100 µV. pack_v, min_v, max_v and spread_v summarise the pack, age_ms says how old the answer of the module is, and simulated marks simulated data.

go-multibus status --json prints both documents. Reading the cell data in Node-RED is described under Multibus Module.

---

More than one module

A controller can carry more than one Multibus Module. Add a module to the configuration with:

go-multibus module add 7

The command turns the configuration into a list of modules, says what changes for the module that was already there, and ends with the hint to restart the service. go-multibus module remove 7 takes a module out again.

With more than one module, every name carries the slot: mb7_can1 to mb7_can3, /dev/mb7_serial1 to /dev/mb7_serial3 and /dev/mb7_protocol, and each module publishes its own pair of files, such as multibus-slot7-cells.json. set, supply and role then need --slot, for example:

go-multibus set --slot 7 3 can

---

Note: more than one Multibus Module on one controller, and setting the isoSPI role at runtime, need Multibus module firmware 0.3.0 or later. With more than one module configured, a module on older firmware stops its bring-up with firmware older than 0.3.0 cannot be told apart from another module; update it.

---

Module firmware updates

The module firmware is installed with go-modules. The published versions are listed under module firmware.

While go-modules 3.3.2 or later works on a slot, it marks that slot as busy. The service then leaves the module in that slot alone, and go-multibus status shows held while go-modules works on the slot. When go-modules is done, the service brings the module up again from the start. The modules in the other slots keep running.

---

The other tools in the package

gocontroll-usb-hostmode reports whether the OTG port of the controller is in host mode. gocontroll-usb-hostmode --apply switches it to host mode, which takes effect after the next reboot, and --revert restores the backups it made. The installation runs it for you, and the unit gocontroll-usb-hostmode.service applies host mode at boot when it is still needed. Removing the package leaves the OTG port in host mode.

gocontroll-cellmon talks to the protocol port of one module. gocontroll-cellmon list shows the modules present, gocontroll-cellmon status the isoSPI link counters and gocontroll-cellmon cells one cell snapshot. With more than one module, --slot picks the module. The package also contains gocontroll-cellmon.service; the installation does not enable it, and it must not run next to the go-multibus service.

gocontroll-modulebus talks to the module in one slot over the SPI module bus, which also works before USB is up, for example gocontroll-modulebus 7 identity for the USB serial number of the module in slot 7.

---

Command reference

• go-multibus: opens the terminal interface.
• go-multibus status: a summary of what the service is doing, for every module. --slot <slot> shows one module, --json prints the published documents.
• go-multibus config: shows the stored configuration.
• go-multibus set <interface> <mode>: stores the mode of connector interface 1 to 5: can, rs485, rs232, isospi or off.
• go-multibus supply <setting>: sets the external supply: off, or a voltage such as 9, 9V or 9000mv.
• go-multibus role [master|slave]: shows the isoSPI role, or stores and applies it.
• go-multibus module add <slot>: adds the module in this slot to the configuration, with every setting at its default.
• go-multibus module remove <slot>: removes the module in this slot from the configuration.
• go-multibus ports: shows the Multibus modules present, with their ports and CAN interfaces.
• go-multibus daemon: runs as the background service; this is what go-multibus.service starts.
• -c or --config <file>: uses another configuration file than /etc/gocontroll/multibus.json.

go-multibus reports its result with an exit code:

• 0: the command finished.
• 1: the request cannot be honoured, or the module answered with an error status.
• 2: a system error, or the module did not answer or answered with something unusable.

Also see Multibus Module for the module itself, systemd services to manage the service, go-modules for the module firmware, and apt packages for the latest version of go-multibus.