Using bit-learn

Using bit-learn

bit-learn is an interactive configuration generator that automatically detects your system hardware and creates optimized test configurations.

Overview

Instead of manually writing TOML configuration files, bit-learn will:

  1. Detect your hardware - CPUs, disks, network interfaces, USB/PCI devices, sensors
  2. Prompt for settings - Ask for thresholds and frequencies with sensible defaults
  3. Generate configs - Create all TOML files in one pass

Quick Start

# Set configuration directory
export BIT_CONFIG_PATH=/etc/bit

# Run interactive configuration generator
sudo bit-learn

Just press Enter to accept all default values, or type custom values when prompted.

What bit-learn Generates

bit-learn creates configuration files for all 42 tests (21 PBIT + 21 CBIT):

Creating config files in /etc/bit

✓ Created pbit_cpu_usage.toml with threshold 42%
✓ Created cbit_cpu_usage.toml with threshold 32%, frequency 30s
✓ Created pbit_disk_usage.toml
✓ Created cbit_disk_usage.toml
✓ Created pbit_ethernet.toml with 2 interfaces
✓ Created cbit_ethernet.toml with frequency 30s
...
✓ Created pbit_usb_whitelist.toml (15 devices detected)
✓ Created cbit_usb_whitelist.toml
✓ Created pbit_pci_whitelist.toml (28 devices detected)
✓ Created cbit_pci_whitelist.toml

Interactive Prompts

CPU Tests

=== PBIT CPU Usage Configuration ===
Measuring current CPU usage...
Current CPU usage: 32.2%
Set CPU usage threshold in % (usage at boot must be below this) [42]: ⏎

=== CBIT CPU Usage Monitoring Configuration ===
Measuring current CPU usage...
Current CPU usage: 22.3%
Set CPU usage threshold in % (continuous monitoring alert threshold) [32]: ⏎
Set monitoring frequency in seconds (how often to check) [30]: ⏎
Set number of samples to average per check [5]: ⏎

Why these defaults? - PBIT threshold (42%) is higher than current usage with headroom - CBIT threshold (32%) is tighter for ongoing monitoring - Frequency (30s) balances responsiveness with overhead

Disk Tests

pbit_disk_usage: Set disk usage threshold in % for disk /dev/sda1 [80]: ⏎
pbit_disk_usage: Set disk usage threshold in % for disk /dev/shm [80]: ⏎

Auto-detection: - Scans mounted filesystems - Identifies root disk and /dev/shm - Suggests 80% threshold (industry standard)

Network Tests

=== PBIT Ethernet Interface Configuration ===
Discovering network interfaces...
  Found: eth0 [up] - 1000 Mbps
  Found: docker0 [down] - unknown Mbps
✓ Created pbit_ethernet.toml with 2 interfaces

Auto-detection: - Uses ip link to discover interfaces - Detects link speed - Records current UP/DOWN state

Temperature Tests

Detecting thermal sensors...
Detected 8 thermal sensor(s)
  Core 0 : 43.0°C
pbit_temperature: Set threshold for 'Core 0' in °C [85]: ⏎
  Core 1 : 42.0°C
pbit_temperature: Set threshold for 'Core 1' in °C [85]: ⏎

Auto-detection: - Reads from /sys/class/thermal/ - Shows current temperatures - Suggests safe thresholds (85°C for CPUs)

USB/PCI Whitelist Tests

# USB devices detected automatically
pbit_usb_whitelist.toml file created (detected 15 devices)

# PCI devices detected automatically
pbit_pci_whitelist.toml file created (detected 28 devices)

Auto-detection: - Executes lsusb and lspci commands - Parses vendor IDs, device IDs, and descriptions - Creates whitelist of currently connected devices

GPIO/CAN/Serial Tests

# GPIO
Warning: No accessible GPIO pins found
pbit_gpio.toml file created (empty config)

# CAN
Detecting CAN interfaces...
  No CAN interfaces found
pbit_can.toml file created (empty config with examples)

# Serial
pbit_serial_ports.toml file created

Graceful handling: - Tests pass when hardware isn't present - Creates empty configs with helpful comments - Includes examples for manual addition

Configuration Patterns

Auto-Detected

bit-learn automatically discovers:

Test Detection Method Command Used
CPU cores sysinfo crate nproc equivalent
Disks df command df /
Network ip command ip link show
Temperature sysfs /sys/class/thermal/
USB devices lsusb lsusb
PCI devices lspci lspci -mm -nn
GPIO sysfs /sys/class/gpio/
CAN sysfs /sys/class/net/can*
Serial ports sysfs /sys/class/tty/

Prompted Values

bit-learn prompts for:

Setting Default Purpose
CPU threshold 42% (PBIT), 32% (CBIT) Resource limit
Memory threshold 90% Memory usage limit
Disk threshold 80% Disk usage limit
Temperature threshold 85°C (CPU), 75°C (other) Thermal limit
CBIT frequency 30-60s (varies by test) Monitoring interval
Power limits Auto-detected ranges Voltage/power bounds

Advanced Usage

Non-Interactive Mode

Accept all defaults automatically:

# Pipe empty responses
yes "" | bit-learn

This is useful for: - Automated deployment scripts - CI/CD pipelines - Quick testing

Selective Regeneration

Currently, bit-learn regenerates all configuration files. To preserve manual changes:

# Backup existing configs
sudo cp -r /etc/bit /etc/bit.backup

# Run bit-learn
sudo bit-learn

# Restore specific configs you want to keep
sudo cp /etc/bit.backup/pbit_custom_test.toml /etc/bit/

Custom Defaults

Edit prompts in tools/src/learn.rs to change defaults for your environment:

// Example: Change default CPU threshold
let threshold = ask_integer(
    "Set CPU usage threshold in %",
    50  // Changed from 42 to 50
);

Then rebuild: 

cargo build -p tools

Learn Function Architecture

Each test has a corresponding learn function:

// In tools/src/learn.rs
fn pbit_cpu_usage_learn() {
    // 1. Detect current state
    let current_usage = measure_cpu_usage();

    // 2. Calculate sensible default
    let default_threshold = current_usage + 10;

    // 3. Prompt user
    let threshold = ask_integer("Set threshold", default_threshold);

    // 4. Write config
    write_toml("pbit_cpu_usage.toml", threshold);
}

Learn Function Patterns

Pattern 1: Auto-Detection Only 

// Example: USB whitelist
fn pbit_usb_whitelist_learn() {
    let devices = detect_usb_devices();
    write_device_list("pbit_usb_whitelist.toml", devices);
}

Pattern 2: Detection + Prompts 

// Example: Disk usage
fn pbit_disk_usage_learn() {
    let disks = detect_disks();
    for disk in disks {
        let threshold = ask_integer("Threshold for {disk}", 80);
        write_disk_config(disk, threshold);
    }
}

Pattern 3: CBIT Frequency Only 

// Example: CBIT USB whitelist
fn cbit_usb_whitelist_learn() {
    let freq = ask_integer("Monitoring frequency", 5);
    write_frequency_config("cbit_usb_whitelist.toml", freq);
    // Device list read from pbit_usb_whitelist.toml
}

Configuration Validation

After running bit-learn, validate the generated configs:

# Check all configs were created
ls -1 $BIT_CONFIG_PATH/*.toml | wc -l
# Should show 42+ files (21 PBIT + 21 CBIT + FBIT + custom)

# Inspect specific config
cat $BIT_CONFIG_PATH/pbit_ethernet.toml

# Test with bit-inspect
bit-inspect | head -20

Common Workflows

Initial Setup

# First time setup
export BIT_CONFIG_PATH=/etc/bit
sudo mkdir -p /etc/bit
sudo bit-learn

# Verify
bit-inspect

After Hardware Change

# Added new USB device or network card
sudo bit-learn  # Regenerate to include new hardware

Development Testing

# Use local config directory
export BIT_CONFIG_PATH=./bit_manager/config
./target/debug/bit-learn

# Test with local build
./target/debug/bit-manager -o

Production Update

# Backup existing
sudo cp -r /etc/bit /etc/bit.$(date +%Y%m%d)

# Regenerate
sudo bit-learn

# Review changes
diff -r /etc/bit.$(date +%Y%m%d) /etc/bit

# Test before enabling service
sudo bit-manager -o

# If OK, restart service
sudo systemctl restart bit_manager

Troubleshooting

BIT_CONFIG_PATH not set

Error: BIT_CONFIG_PATH not set

Solution: 

export BIT_CONFIG_PATH=/etc/bit

Permission denied

Error: Failed to create /etc/bit/pbit_cpu_usage.toml

Solution: 

sudo bit-learn  # Run with sudo

Missing hardware tools

Warning: lsusb not found

Solution: 

# Install usbutils
sudo apt install usbutils

# Install pciutils
sudo apt install pciutils

Overwrote manual changes

Prevention: 

# Always backup before regenerating
sudo cp -r $BIT_CONFIG_PATH ${BIT_CONFIG_PATH}.backup

Recovery: 

# Restore from backup
sudo cp ${BIT_CONFIG_PATH}.backup/* $BIT_CONFIG_PATH/

Default Values Reference

Resource Thresholds

Test Default Reasoning
CPU usage (PBIT) Current + 10% Boot-time headroom
CPU usage (CBIT) Current + 10% Runtime tolerance
Memory usage 90% Standard limit
Disk usage 80% Industry standard
Swap usage 50% Conservative

Temperature Thresholds

Component Default Safe Max
CPU cores 85°C 90°C
GPU 75°C 85°C
Other sensors 75°C Varies

CBIT Frequencies

Test Type Default Range
Resource (CPU/mem/disk) 30s 10-300s
Temperature 60s 30-300s
Logs (dmesg/syslog) 60s 30-600s
Security (whitelist) 5s 5-60s
Config monitoring 300s 60-3600s

Next Steps

Edit this page on GitHub