What is BB-CLI?

BB-CLI is the Brainboxes Command Line Interface, a tool that helps to configure BB-400 settings.

It can be used to get and set the device name, configure network settings, and change serial port settings amongst other things. It can be run from the Linux command line using the prefix bb and also called from other scripts and programs.

The settings are split into 2 general types: Configuration and Status.

• Configuration Settings:
  These are settings which change infrequently and can be known before the device is even switched on. E.g. hostname, ethernet mode (DHCP or static), which IO protocols are enabled, Wi-Fi mode.
• Status Settings:
  these are settings which can change frequently and are only known when the device is switched on. E.g. the current state of DIO 0, version of Brainboxes packages installed.

How it works?

The BB-CLI reads or writes to the configuration file when a command is executed. The configuration file is stored in the /boot partition of the BB-400. The file is in YAML format. See: https://en.wikipedia.org/wiki/YAML to read about YAML.

The configuration file can be accessed from the command line directly by typing:

$ sudo nano /boot/bb_config.yaml

The user can also directly type commands on the BB-400 command line to get/set these settings.

Command Format

The BB_CLI command format is composed of the following parts:

$ bb path.to.property '{optional JSON to set property}'

{JSON response}

What follows is a breakdown of the meaning of each part of the command:

bb – required to initiate the Brainboxes command line interface

path.to.property – this is the path to the property which the user wishes to select. The path conforms to Json. For path rules see http://goessner.net/articles/JsonPath/ for more info. To take effect JSON properties must already exist within the config or status file for them to be set otherwise an error message will be returned.

‘{optional JSON to set property}’ – the payload should be proper JSON (see: https://www.json.org/ and https://en.wikipedia.org/wiki/JSON for more info).

‘{JSON response}’ – The JSON response will always conform to the JSON specification to allow maximum interoperability with other programs.

Helpful Commands:

Commands to get settings:

1. Read the config settings as a JSON string – $ bb config
2. Read the status as a JSON string – $ bb status
3. Read the IO lines configuration settings – $ bb config.io
4. Read the Wi-Fi Access Point settings – $ bb config.network.radio.wifiap
5. List out the serial port configuration – $ bb config.serial

Commands to set settings:

1. Change the time zone –
   $ sudo bb config.system.timezone Europe/Paris
2. Change the debounce value of IO line 5 to 500 ms –
   $ sudo bb config.io.lines.dio5.debounce 500
3. To add a Wi-Fi connection –
   $ sudo bb config.network.radio.wlan0.connections '[{ssid: BB-wifi, password: test12345}]'
4. To set the IO lines output status –
   $ sudo bb status.io.outputs [1,0,1,1,1,0,1,1]
5. Change the serial port type –
   $ sudo bb config.serial.type rs485

All set commands will output a json payload with success and message properties. The success property is always true or false and the message contains extra information if a failure occurs.

$ sudo bb config.io.lines.dio5.debounce 1x00
{
    "message": "1 of the settings failed. Error message: 1. config.io.lines - Invalid debounce input for line 5 - should be a number between 0-4000.",
    "success": false
}

NOTE: To run a set command, root access is required. Therefore, prefix the sudo keyword to the command or login as the root user, otherwise BB-CLI will complain.