Skip to content

INSTALL.md

Latest commit

 

History

History
222 lines (161 loc) · 6.37 KB

INSTALL.md

File metadata and controls

222 lines (161 loc) · 6.37 KB

INSTALL.md

Table of Contents

Manual Install

Install all required dependencies using pip:

pip install -r requirements.txt

Copy the configuration template and edit as needed:

cp config.template config.ini

Docker Installation

See script/docker/README.md for Docker-based setup instructions.
Docker is recommended for Windows or if you want an isolated environment.

Requirements

  • Python 3.8 or later (Python 3.13+ supported in Docker)
  • All dependencies are listed in requirements.txt and can be installed with: 
    pip install -r requirements.txt
  • To enable emoji in the Debian/Ubuntu console: 
    sudo apt-get install fonts-noto-color-emoji
  • For Ollama LLM support, see the prompts during install.sh or visit https://ollama.com.

install.sh

Purpose

install.sh automates installation, configuration, and service setup for the Meshing Around Bot project. It is designed for Linux systems (Debian/Ubuntu/Raspberry Pi and embedded devices).

Usage

Run from the project root directory:

bash install.sh

To uninstall:

bash install.sh --nope

What it does

  • Checks for existing installations and permissions.
  • Optionally moves the project to /opt/meshing-around.
  • Installs Python and pip if missing (unless on embedded systems).
  • Adds the current user (or a dedicated meshbot user) to necessary groups for serial and Bluetooth access.
  • Copies and configures systemd service files for running the bot as a service.
  • Sets up configuration files, updating latitude/longitude automatically.
  • Offers to create and activate a Python virtual environment, or install dependencies system-wide.
  • Installs optional components (emoji fonts, Ollama LLM) if desired.
  • Sets permissions for log and data directories.
  • Optionally installs and enables the bot as a systemd service.
  • Provides post-installation notes and commands in install_notes.txt.
  • Offers to reboot the system to complete setup.

When to use

  • For first-time installation of the Meshing Around Bot.
  • When migrating to a new device or environment.
  • After cloning or updating the repository to set up dependencies and services.

Note

  • You may be prompted for input during installation (e.g., for embedded mode, virtual environment, or optional features).
  • Review and edit the script if you have custom requirements or are running on a non-standard system.

update.sh

Purpose

update.sh is an update and maintenance script for the Meshing Around Bot project. It automates the process of safely updating your codebase, backing up data, and merging configuration changes.

Usage

Run from the project root directory:

bash update.sh

Or, after making it executable:

chmod +x update.sh
./update.sh

What it does

  • Stops running Mesh Bot services to prevent conflicts during update.
  • Fetches and pulls the latest changes from the GitHub repository (using git pull --rebase).
  • Handles git conflicts, offering to reset to the latest remote version if needed.
  • Copies a custom scheduler template if not already present.
  • Backs up the data/ directory (and custom_scheduler.py if present) to a compressed archive.
  • Merges your existing configuration with new defaults using script/configMerge.py, and logs the process.
  • Restarts services if they were stopped for the update.
  • Provides status messages and logs for troubleshooting.

When to use

  • To update your Mesh Bot installation to the latest version.
  • Before making significant changes or troubleshooting, as it creates a backup of your data.

Note

  • Review ini_merge_log.txt and config_new.ini after running for any configuration changes or errors.
  • You may be prompted if git conflicts are detected.

launch.sh

Purpose

launch.sh is a convenience script for starting the Mesh Bot, Pong Bot, or generating reports within the Python virtual environment. It ensures the correct environment is activated and the appropriate script is run.

How to Use

From your project root, run one of the following commands:

  • Launch Mesh Bot: 
    bash launch.sh mesh
  • Launch Pong Bot: 
    bash launch.sh pong
  • Generate HTML report: 
    bash launch.sh html
  • Generate HTML5 report: 
    bash launch.sh html5
  • Add a favorite (calls script/addFav.py): 
    bash launch.sh add

What it does

  • Ensures you are in the project directory.
  • Copies config.template to config.ini if no config exists.
  • Activates the Python virtual environment (venv).
  • Runs the selected Python script based on your argument.
  • Deactivates the virtual environment when done.

Note

  • The script requires a Python virtual environment (venv) to be present in the project directory.
  • If venv is missing, the script will exit with an error message.
  • Always provide an argument (mesh, pong, html, html5, or add) to specify what you want to launch.

Troubleshooting

Permissions Issues

If you encounter errors related to file or directory permissions (e.g., "Permission denied" or services failing to start):

  • Ensure you are running installation scripts with sufficient privileges (use sudo if needed).

  • The logs, data, and config.ini files must be owned by the user running the bot (often meshbot or your current user).

  • You can manually reset permissions using the provided script:

    sudo bash etc/set-permissions.sh meshbot

  • If you moved the project directory, re-run the permissions script to update ownership.

  • For systemd service issues, check logs with:

    sudo journalctl -u mesh_bot.service

If problems persist, double-check that the user specified in your service files matches the owner of the project files and directories.