Installation & Setup

Installation & Setup

Get BIT running on your system in 5 minutes.

Prerequisites

  • Operating System: Linux (Ubuntu 22.04+, Debian-based systems)
  • Architecture: x86_64, ARM64
  • Systemd: Recommended for continuous monitoring
  • Permissions: Root access required for certain tests (GPIO, CAN, serial ports)

Install the Package

Download the latest .deb package from the releases page:

# Install bit-manager (required)
sudo dpkg -i bit-manager_*.deb

# Optional: Install monitors
sudo dpkg -i bit-monitor-cli_*.deb
sudo dpkg -i bit-monitor-gui_*.deb

This installs:

  • Binaries: /usr/bin/bit-manager, /usr/bin/bit-learn, /usr/bin/bit-inspect
  • Test Plugins: /usr/local/lib/bit_manager/*.so
  • Configuration Directory: /etc/bit/ (created empty)
  • Systemd Service: /lib/systemd/system/bit_manager.service

Default Paths:

The tools use these default paths when installed system-wide:

  • BIT_TEST_PATH: /usr/local/lib/bit_manager (test plugin directory)
  • BIT_CONFIG_PATH: /etc/bit (configuration directory)

These defaults work automatically after .deb installation. You can override them using environment variables if needed:

# Override plugin directory
BIT_TEST_PATH=/custom/plugins bit-manager

# Override config directory
BIT_CONFIG_PATH=/custom/config bit-learn

See tool-specific sections in the User Guide for more environment variable options.

Verify installation:

bit-manager --version
bit-learn --version
bit-inspect --version

Generate Configuration

Configure tests for your hardware:

sudo bit-learn

The tool will:

  1. Auto-detect hardware: CPUs, disks, network interfaces, USB/PCI devices, sensors
  2. Prompt for thresholds: CPU/memory/disk limits with sensible defaults
  3. Generate TOML files: One configuration file per test in /etc/bit/

Example prompts:

pbit_cpu_usage: Set CPU usage threshold in % [42]: ⏎
cbit_disk_usage: Set test frequency in seconds [30]: ⏎
pbit_disk_usage: Set disk usage threshold in % for /dev/sda1 [80]: ⏎

Press Enter to accept defaults. The tool detects your specific hardware and pre-fills sensible values.

Verify configuration:

# List all available tests
bit-inspect

# Inspect a specific test
bit-inspect pbit_cpu_usage

Run Tests

You can run tests in two modes:

One-Shot Mode

Run all tests once and exit (useful for validation, CI/CD, debugging):

sudo bit-manager -o

Example output:

2025-12-08 03:25:30.717 PBIT:[PASS] pbit_cpu_usage
2025-12-08 03:25:30.850 PBIT:[PASS] pbit_memory_usage
2025-12-08 03:25:31.123 PBIT:[PASS] pbit_disk_usage
2025-12-08 03:25:31.456 PBIT:[PASS] pbit_ethernet
2025-12-08 03:25:31.789 PBIT:[FAIL] pbit_gpu_loading
2025-12-08 03:25:32.012 CBIT:[PASS] cbit_temperature

Run specific tests:

# Single test
bit-manager -t pbit_cpu_usage -o

# Multiple tests
bit-manager -t pbit_cpu_usage -t cbit_memory_usage -o

Service Mode (Optional)

For continuous monitoring, run as a systemd service:

# Enable service to start on boot
sudo systemctl enable bit_manager

# Start service now
sudo systemctl start bit_manager

# Check status
sudo systemctl status bit_manager

When running as a service: - PBIT tests run once at system startup - CBIT tests run continuously at configured intervals (e.g., every 30 seconds) - Logs written to systemd journal

Note: Service mode is recommended for production systems. One-shot mode works fine for testing and development.

View Results

Real-Time Logs

# Follow logs in real-time
sudo journalctl -u bit_manager -f

# View last 50 lines
sudo journalctl -u bit_manager -n 50

# View logs since boot
sudo journalctl -u bit_manager -b

Using Monitors

Install and run monitors to view results graphically:

# CLI monitor (subscribes to Zenoh)
bit-monitor-cli --list-tests
bit-monitor-cli --listen

# GUI monitor (requires Qt6)
bit-monitor-gui

See bit-monitor-cli Guide and bit-monitor-gui Guide for details.

Understanding Results

  • PASS ✓ - Test completed successfully
  • FAIL ✗ - Issue detected, action may be required
  • NotRun - Test waiting for next interval (CBIT only)

Common Scenarios:

Hardware not present (normal):

PBIT:[PASS] pbit_can
INFO: No CAN interfaces configured - test passes

Threshold exceeded (action needed):

CBIT:[FAIL] cbit_disk_usage
ERROR: Disk /dev/sda1 usage 85% exceeds threshold 80%

Permission issue:

Permission issue: 

ERROR: pbit_dmesg_check requires root privileges

Customize Configuration

To adjust test settings:

# Edit specific test
sudo nano /etc/bit/cbit_disk_usage.toml

# Or regenerate all configs (overwrites existing)
sudo bit-learn

See Configuration Reference for detailed configuration options.

Update or Uninstall

Update to new version:

sudo systemctl stop bit_manager
sudo dpkg -i bit-manager_<new-version>_amd64.deb
sudo systemctl start bit_manager

Configuration files in /etc/bit/ are preserved during updates.

Uninstall:

sudo systemctl stop bit_manager
sudo systemctl disable bit_manager
sudo dpkg -r bit-manager

# Optional: Remove configuration
sudo rm -rf /etc/bit/

Next Steps

Edit this page on GitHub