Troubleshooting

Troubleshooting

Solutions for common issues when using BIT.

Service Issues

Service Won't Start

Check service status:

systemctl status bit_manager

View error logs:

sudo journalctl -u bit_manager -n 100

Common causes:

  1. Missing configuration files
# Check if configs exist
ls -l /etc/bit/*.toml

# Generate if missing
sudo bit-learn
  1. Permission errors

Some tests require root privileges. Ensure service runs as root (default in systemd unit).

  1. Plugin load errors
# Verify plugins exist
ls -l /usr/local/lib/bit_manager/*.so

# Reinstall if missing
sudo dpkg -i bit-manager_*.deb

Service Crashes or Restarts

Check logs for errors:

sudo journalctl -u bit_manager --since "10 minutes ago"

Look for: - Segmentation faults → File a bug report with logs - Configuration errors → Fix invalid TOML syntax - Hardware access errors → Check permissions

Test Discovery Issues

Tests Not Appearing in bit-inspect

Verify plugin directory:

ls -l /usr/local/lib/bit_manager/*.so

Should show 50+ .so files for test plugins.

If plugins are missing:

# Reinstall package
sudo dpkg -i bit-manager_*.deb

Specific Test Not Loading

Check configuration file exists:

ls -l /etc/bit/<test_name>.toml

Regenerate specific test config:

sudo bit-learn

Verify test is enabled:

grep "enabled" /etc/bit/<test_name>.toml

Should show enabled = true.

bit-learn Issues

Permission Denied

Solution:

# Run with sudo
sudo bit-learn

Missing Hardware Tools

Symptoms: lsusb not found or similar warnings

Solution:

# Install utilities
sudo apt install usbutils pciutils

Overwrote Manual Changes

Prevention:

# Always backup before regenerating
sudo cp -r /etc/bit /etc/bit.$(date +%Y%m%d)

Recovery:

# Restore from backup
sudo cp /etc/bit.backup/* /etc/bit/

bit-inspect Issues

Test Not Listed

Check if .so exists:

ls -l /usr/local/lib/bit_manager/libtest_name.so

Config File Not Found

Solution:

# Generate config
bit-learn

Permission Errors

Solution:

# Run with sudo
sudo -E bit-inspect

Configuration Issues

Invalid Configuration

Symptoms: Tests fail to load, service won't start

Check TOML syntax:

# View the problematic config
cat /etc/bit/<test_name>.toml

Common TOML errors: - Missing quotes around strings - Incorrect array syntax ([[device]] vs [device]) - Trailing commas - Mismatched brackets

Fix: Edit manually or regenerate:

sudo nano /etc/bit/<test_name>.toml
# Or
sudo bit-learn

Configuration Changes Not Applied

Restart the service after editing configs:

sudo systemctl restart bit_manager

One-shot mode picks up changes automatically:

sudo bit-manager -o

Lost Configuration After bit-learn

bit-learn overwrites all config files. Always back up before regenerating:

# Backup before regenerating
sudo cp -r /etc/bit /etc/bit.backup

# Restore if needed
sudo cp -r /etc/bit.backup/* /etc/bit/

Permission Issues

Permission Denied Errors

Symptoms: Tests fail with "permission denied" or "operation not permitted"

Affected tests: GPIO, CAN, serial ports, dmesg

Solution: Run as root:

sudo bit-manager -o

Service mode runs as root by default (via systemd unit).

Specific Hardware Tests Fail

Check hardware permissions:

# CAN interfaces
ls -l /dev/can*

# Serial ports
ls -l /dev/ttyS* /dev/ttyUSB*

# GPIO
ls -l /sys/class/gpio/

Grant access (if not running as root):

# Add user to dialout group for serial
sudo usermod -a -G dialout $USER

# Reboot or re-login for changes to take effect

Monitor Issues

Monitors Can't Connect

Symptoms: bit-monitor-cli or bit-monitor-gui show no results

Check bit-manager is running with Zenoh:

# Service mode
systemctl status bit_manager

# Manual mode (must include --zenoh flag)
bit-manager --zenoh -o

Verify Zenoh publishing:

Check logs for "Publishing" messages:

sudo journalctl -u bit_manager -f | grep Publishing

Check hostname match:

Monitors subscribe to bit/<hostname>/* topics. Verify hostnames match:

# On target system
hostname

# On monitor system
bit-monitor-cli --hostname <target-hostname> --listen

GUI Monitor Won't Start

Missing Qt6 dependencies:

sudo apt-get install libqt6core6 libqt6gui6 libqt6widgets6

Display issues (headless systems):

# Use CLI monitor instead
bit-monitor-cli --listen

Test Execution Issues

Tests Always Fail

Check thresholds are realistic:

#Edit config
sudo nano /etc/bit/<test_name>.toml

# Increase threshold
threshold = 90    # Was 80

Check hardware is functional:

# Example: disk health
sudo smartctl -H /dev/sda

# Example: temperature
sensors

Tests Never Run (NotRun status)

CBIT tests wait for interval:

First execution happens after frequency seconds:

[cbit_temperature]
frequency = 30    # Waits 30 seconds before first run

Test is disabled:

grep "enabled" /etc/bit/<test_name>.toml

Should show enabled = true.

Specific Hardware Test Fails

Hardware not present (normal):

Tests pass gracefully when hardware isn't configured:

PBIT:[PASS] pbit_can
INFO: No CAN interfaces configured

This is expected behavior - no action needed.

Hardware present but failing:

Check device-specific logs:

# CAN
ip link show can0

# Ethernet
ip link show eth0

# USB devices
lsusb

# PCI devices
lspci

Performance Issues

High CPU Usage

Reduce CBIT test frequency:

sudo nano /etc/bit/cbit_<test_name>.toml

frequency = 300    # Every 5 minutes instead of 30 seconds

Slow Test Execution

Disable unnecessary tests:

sudo nano /etc/bit/<test_name>.toml

enabled = false

Or remove hardware-specific tests for devices you don't have (GPIO, CAN, etc.).

Getting Help

If you can't resolve the issue:

  1. Collect logs:
sudo journalctl -u bit_manager -n 500 > bit-manager.log
  1. Check test configuration:
cat /etc/bit/<failing_test>.toml > test-config.toml
  1. Get system info:
bit-manager --version
uname -a
  1. File an issue: https://github.com/Astute-Systems/bit/issues

Include logs, configuration, and system information in your report.

Edit this page on GitHub