Skip to content

README.md

Latest commit

 

History

History
139 lines (98 loc) · 3.84 KB

README.md

File metadata and controls

139 lines (98 loc) · 3.84 KB
Raw

HamBot_Deploy

Deployment scripts for setting up the HamBot robotics environment and the optional OLED network display on a Raspberry Pi 4 running 64-bit Raspberry Pi OS (Bookworm).

These scripts automate:

  • Cloning the relevant repositories
  • Creating Python virtual environments with system packages enabled
  • Installing required Python dependencies (pip install .)
  • Configuring global venv auto-activation (HamBot)
  • Installing/removing systemd + NetworkManager hooks (OLED)

Requirements

This project assumes you are running a Raspberry Pi 4 with 64-bit Bookworm OS.
The following packages are already included in the default image and do not need to be installed separately:

  • git
  • python3-venv
  • python3-pip
  • python3-picamera2
  • python3-numpy

You only need to install:

sudo apt update
sudo apt install -y \
    python3-opencv \
    network-manager \
    wireless-tools

Installation

All scripts live in the scripts/ folder.

Install HamBot only

bash scripts/setup_hambot.sh
  • Clones https://github.com/biorobaw/HamBot into ~/HamBot
  • Creates hambot_venv inside that repo
  • Installs the robot_systems package
  • Modifies ~/.bashrc so all new terminals auto-activate the venv

Notes:

  • python and pip use the venv by default
  • python3 and pip3 remain the system defaults

Install OLED only

bash scripts/setup_oled.sh
  • Clones https://github.com/biorobaw/HamBot_OLED into the hambot user’s home directory
  • Creates a .venv in that repo and installs the OLED package
  • Installs a NetworkManager dispatcher hook (/etc/NetworkManager/dispatcher.d/99-hambot-oled)
  • Installs and enables a systemd oneshot service (hambot_oled.service) that runs at boot

Combined installer

Use the dispatcher script to install both components at once:

bash scripts/install.sh both

Options:

  • bash scripts/install.sh hambot
  • bash scripts/install.sh oled
  • bash scripts/install.sh both (default)

Uninstall

To remove installed components and undo the setup:

bash scripts/uninstall.sh hambot   # removes HamBot repo, venv, and .bashrc snippet
bash scripts/uninstall.sh oled     # removes OLED repo, venv, service + dispatcher hook
bash scripts/uninstall.sh both     # removes everything

Notes:

  • uninstall.sh is idempotent (safe to run multiple times).
  • After uninstalling HamBot, open a new terminal to reload your .bashrc without the venv auto-activation snippet.
  • After uninstalling OLED, the hambot_oled.service and dispatcher hook are gone, and NetworkManager is restarted.

Development Notes

  • setup_hambot.sh uses --system-site-packages for the venv so it can see system-wide libraries.
  • It is critical that picamera2, numpy, and opencv are installed via apt (system packages) and not via pip.
    • Installing these with pip will cause the HamBot environment to fail because they depend on Raspberry Pi–specific builds and drivers provided only by the system packages.
    • Correct install: 
      sudo apt install -y python3-picamera2 python3-numpy python3-opencv
  • Both setup scripts explicitly cd into the cloned repo before running pip install . so the correct pyproject.toml is picked up.
  • The installer is safe to re-run: existing repos will git pull, and existing venvs will be reused.

Quick sanity check

After installing HamBot:

# Open a new terminal
echo $VIRTUAL_ENV    # should show ~/HamBot/hambot_venv
which python         # should be ~/HamBot/hambot_venv/bin/python
which python3        # remains /usr/bin/python3

python -c "import robot_systems; print('HamBot OK')"

After installing OLED:

systemctl status hambot_oled.service --no-pager
ls /etc/NetworkManager/dispatcher.d/99-hambot-oled

License

MIT