feat: update setup script and installation instructions for easier setup

.github/workflows/setup-script.yml

@@ -0,0 +1,25 @@
+name: Setup script
+
+on:
+  schedule:
+    # Run approximately twice a month.
+    - cron: "17 4 1,15 * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    env:
+      PSModulePath: ""  # Otherwise colcon might think that PowerShell is being used
+
+    steps:
+      - name: Download and run setup script
+        run: |
+          cd "$RUNNER_TEMP"
+          curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
+            --output bitbots_setup.sh
+          bash ./bitbots_setup.sh --https

README.md

@@ -17,17 +17,28 @@ The workspace is managed using the [pixi](https://pixi.sh) package manager. This
 
 Full step-by-step instructions for installing the Bit-Bots software stack and ROS 2 can be found in our [documentation](https://docs.bit-bots.de/meta/manual/tutorials/install_software_ros2.html).
 
+We assume a modern Linux distribution with a recent version of `curl` and `git` installed. The setup script should work on any Linux distribution, but we only test on Ubuntu.
+
+From the directory where you want to clone `bitbots_main`, download and run the setup script:
+
+```shell
+curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
+  --output /tmp/bitbots_setup.sh
+bash /tmp/bitbots_setup.sh
+```
+
+This clones the repository using SSH, installs Pixi and all dependencies, and builds the workspace.
+If cloning with SSH fails, the script offers to retry using HTTPS.
+Pass `--https` to clone with HTTPS immediately; `--ssh` explicitly selects the default SSH method.
+
+## Using the workspace
+
 Run the following command inside this repository to build the workspace.
-All dependencies will be installed automatically.
-Make sure you have [pixi](https://pixi.sh) installed.
-A few optional proprietary dependencies will be needed for full functionality, see the documentation for details.
 
 ``` shell
 pixi run build
 ```
 
-## Using the workspace
-
 To activate the workspace run the following command in the terminal you want to use:
 
 ``` shell

scripts/bitbots_setup.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+readonly DEFAULT_BRANCH="main"
+readonly REPO_URL_SSH="git@github.com:bit-bots/bitbots_main.git"
+readonly REPO_URL_HTTPS="https://github.com/bit-bots/bitbots_main.git"
+
+branch="$DEFAULT_BRANCH"
+branch_explicit=false
+clone_method="ssh"
+clone_method_explicit=false
+
+usage() {
+    echo "Usage: $0 [--ssh | --https] [branch]" >&2
+}
+
+parse_args() {
+    for arg in "$@"; do
+        case "$arg" in
+            --ssh | --https)
+                local method="${arg#--}"
+                if $clone_method_explicit && [[ "$clone_method" != "$method" ]]; then
+                    echo "Only one clone method can be selected." >&2
+                    usage
+                    exit 2
+                fi
+                clone_method="$method"
+                clone_method_explicit=true
+                ;;
+            -*)
+                echo "Unknown option: $arg" >&2
+                usage
+                exit 2
+                ;;
+            *)
+                if $branch_explicit; then
+                    echo "Only one branch can be selected." >&2
+                    usage
+                    exit 2
+                fi
+                branch="$arg"
+                branch_explicit=true
+                ;;
+        esac
+    done
+}
+
+ask_question() {
+    local response
+
+    while true; do
+        read -r -p "$1 [Y/n]: " response
+        case "$response" in
+            [Yy] | [Yy][Ee][Ss] | "") return 0 ;;
+            [Nn] | [Nn][Oo]) return 1 ;;
+            *) echo "Please answer yes or no." ;;
+        esac
+    done
+}
+
+setup_pixi() {
+    command -v pixi >/dev/null && return
+
+    command -v curl >/dev/null || {
+        echo "Required command not found: curl" >&2
+        exit 1
+    }
+    echo "Installing Pixi..."
+    curl -fsSL https://pixi.sh/install.sh | bash
+    export PATH="$HOME/.pixi/bin:$PATH"
+    command -v pixi >/dev/null || {
+        echo "Pixi installation completed, but pixi is not available on PATH." >&2
+        exit 1
+    }
+}
+
+clone_repo() {
+    local target="$PWD/bitbots_main"
+
+    if [[ -e "$target" ]]; then
+        git -C "$target" rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
+            echo "Cannot clone: $target already exists and is not a Git repository." >&2
+            exit 1
+        }
+
+        if git -C "$target" remote get-url origin >/dev/null 2>&1; then
+            git -C "$target" config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+            git -C "$target" fetch --prune origin
+        fi
+
+        if git -C "$target" show-ref --verify --quiet "refs/heads/$branch"; then
+            git -C "$target" switch "$branch"
+        else
+            git -C "$target" switch --track -c "$branch" "origin/$branch"
+        fi
+        return
+    fi
+
+    echo "Cloning bitbots_main branch '$branch'..."
+    if [[ "$clone_method" == "https" ]]; then
+        git clone --branch "$branch" "$REPO_URL_HTTPS" "$target"
+    elif git clone --branch "$branch" "$REPO_URL_SSH" "$target"; then
+        :
+    else
+        echo "SSH clone failed. This may mean your SSH keys are not set up for GitHub."
+        echo "See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh"
+        if [[ ! -t 0 ]]; then
+            echo "Cannot ask to retry with HTTPS because standard input is not interactive." >&2
+            echo "Re-run the script with --https." >&2
+            exit 1
+        fi
+        if ask_question "Continue with an HTTPS clone instead?"; then
+            git clone --branch "$branch" "$REPO_URL_HTTPS" "$target"
+        else
+            echo "Set up your SSH keys and re-run this script." >&2
+            exit 1
+        fi
+    fi
+}
+
+main() {
+    parse_args "$@"
+
+    command -v git >/dev/null || {
+        echo "Required command not found: git" >&2
+        exit 1
+    }
+    setup_pixi
+
+    clone_repo
+
+    cd "$PWD/bitbots_main"
+    echo "Installing dependencies..."
+    pixi install
+    echo "Running full build..."
+    echo "If the build exhausts memory on this system, retry inside bitbots_main with:"
+    echo "pixi run -e default build --parallel-workers 2"
+    pixi run -e default build
+}
+
+main "$@"

src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst

@@ -8,16 +8,19 @@ In this tutorial, we will learn how to install all dependencies and build our so
 
 **Prerequisites**
 
-- You have an existing GitHub account and added a SSH key to your account.
+- Modern Linux distribution with a recent version of ``curl`` and ``git`` installed.
 
-If you have not previously set up any of our software stack, you can use the following command to install and setup everything in one go:
+To install our software at your current directory, run the following command:
 
 .. code-block:: bash
 
-  mkdir -p ~/git/bitbots \
-    && cd ~/git/bitbots \
-    && curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/setup.sh > /tmp/setup.sh \
-    && bash /tmp/setup.sh
+  curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
+    --output /tmp/bitbots_setup.sh
+  bash /tmp/bitbots_setup.sh
+
+This clones the repository using SSH, installs Pixi and all dependencies, and builds the workspace.
+If cloning with SSH fails, the script offers to retry using HTTPS.
+Pass ``--https`` to clone with HTTPS immediately; ``--ssh`` explicitly selects the default SSH method.
 
 Manual steps with in depth explanation
 --------------------------------------