Skip to main content

System Administration

Command Line Interface (BB CLI)​

The BB CLI provides a unified interface for configuring system properties. Settings are stored in /boot/bb_config.yaml, enabling consistent configuration across multiple devices.

Common BB CLI Commands​

bb config                                  # View all configuration
bb config.network.eth0                     # View specific section
bb config.system.hostname newhostname      # Set value
sudo bb reset                              # Reset to factory defaults
sudo bb update                             # Sync settings to config file

Factory Reset​

The factory reset command restores all settings to their default values:

sudo bb reset

This command takes approximately 2 minutes to complete. It resets network configuration, I/O settings, serial port parameters, and system credentials to defaults.

Firmware Backup and Restore​

Creating a complete backup of the BB-400 firmware and configuration is essential before making significant changes or deploying to production.

Backup Procedure​

tip

Disconnect power and wait at least 5 minutes for UPS capacitors to discharge.

  1. Remove the enclosure cover by pressing the release tabs on each side.
  2. Move the MODE jumper from NORMAL to FLASH position.
  3. Remove the USB blanking plate and connect a Micro USB cable to your PC.
  4. Apply power to the BB-400.
  5. Run RPiBoot utility to mount the eMMC as a removable drive.
  6. Use imaging software (Win32DiskImager or dd) to create a backup image.
  7. After backup, restore the MODE jumper to NORMAL and reassemble.
IMPORTANT

Do not format the drive when prompted by Windows. The backup image includes the MAC address - do not deploy a single backup to multiple units.

Flashing New Firmware​

This procedure covers reflashing the BB-400 with the default factory image or a custom backup image. Use this when the software becomes corrupt, when starting fresh after development, or when deploying a tested configuration.

Pre-requisites​

CRITICAL: EEPROM Verification Required

Before flashing, verify the EEPROM is programmed. If not programmed, the device will fail on reboot and will not recover. Run:

cat /usr/share/brainboxes/manuf_info

If this returns an error about a missing file, contact Brainboxes support before proceeding.

Required Software and Equipment:

  • Small flat-blade screwdriver (for case removal and blanking plate)
  • Micro USB to USB cable
  • Base image file (.img) — download from www.brainboxes.com/bb-400
  • Windows: RPiBoot for Windows, Win32DiskImager
  • Linux: RPiBoot (build from source), dd command

Flashing Procedure​

CAUTION

Take extreme care around the large UPS capacitors when the case is removed. Do not damage the ribbon cable when removing or reattaching the outer casing.

  1. Verify EEPROM programming: Access the WebAdmin Terminal and run: cat /usr/share/brainboxes/manuf_info — Confirm manufacturing information is displayed before proceeding.

  2. Power down completely: Disconnect power and wait at least 5 minutes until the STOPPING LED is completely off. The UPS capacitors must fully discharge.

  3. Remove the enclosure: Using a small screwdriver, press down the 2 release notches on each side of the case and slide the cover off.

  4. Set MODE jumper to FLASH: Locate the MODE jumper near the Compute Module and move it from the NORMAL position to the FLASH position.

  5. Access the USB port: Using a small screwdriver, push out the yellow blanking plate located above the yellow terminal block from the inside of the case.

  6. Connect USB and apply power: Connect the Micro USB cable from the BB-400 to your PC, then apply power to the BB-400.

  7. Run RPiBoot: Execute the RPiBoot utility. The BB-400 will appear as a new removable drive within approximately 10 seconds. Do NOT format the drive if Windows prompts you.

  8. Flash the image: Use the appropriate method for your operating system (see below).

Windows Flashing Method:

  1. Open Win32DiskImager
  2. Select the Brainboxes .img file you downloaded
  3. Select the BB-400 drive from the Device dropdown (verify correct drive letter)
  4. Click Write and wait for completion

Linux Flashing Method:

  1. Run lsblk to identify the BB-400 device (e.g., /dev/sdx)
  2. Execute the following command:
sudo dd if=BB-400_Base.img of=/dev/sdx bs=4M status=progress oflag=direct

  1. Wait for dd to complete (may take 30-60 minutes for 32GB)

  2. Power down after flashing: When flashing is complete, disconnect power and wait at least 5 minutes until the STOPPING LED is completely off.

  3. Restore MODE jumper: Move the MODE jumper from FLASH back to the NORMAL position.

  4. Reassemble and power on: Replace the enclosure cover, reconnect power, and allow the device to complete first-time boot.

First-Time Boot Process​

After flashing, the device performs an automatic first-time configuration that takes several minutes. During this process:

  • The A, B, C, and D LEDs will blink rapidly together — this indicates the programming phase is active
  • Do not disconnect power during this phase
  • When LEDs stop blinking, programming is complete and the device will reboot automatically
  • After final reboot, the device will be accessible via Wi-Fi access point, WebAdmin, and Boost.IO software

Troubleshooting Flash Failures​

If problems occur during the first-time boot process:

  • Flashing red LEDs on Ethernet ports: Indicates a boot failure. Try reflashing the image — data integrity issues during transfer can cause this.

  • To retrieve error logs: Put the device back into FLASH mode, run RPiBoot, and copy the file /boot/.one-time-program.log from the boot partition.

  • Persistent failures: Contact Brainboxes support at [email protected] with the log file attached.

Reducing Backup Image Size (Optional)​

Full backup images are the same size as the eMMC storage (8GB or 32GB). To reduce storage requirements and flash times, use the PiShrink utility on a Linux system:

wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
chmod +x pishrink.sh
sudo ./pishrink.sh backup.img

This typically reduces a standard Brainboxes image from 8/32GB to approximately 3GB. The shrunk image will automatically expand to fill the available storage when flashed to a new device.