Skip to content

Commit b16d3e7

Browse files
jaagutjaagut
authored
Fix/docs (#734)
2 parents 3072979 + eb7856a commit b16d3e7

22 files changed

Lines changed: 262 additions & 292 deletions

‎README.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,17 @@ All code is written as individual ROS 2 packages.
1515

1616
The workspace is managed using the [pixi](https://pixi.sh) package manager. This allows us to have reproducible builds and easy user space dependency management similar to tools like `uv` or `cargo`. This also means that no system wide ROS installation or superuser privileges are required to install or run the code.
1717

18-
Full step-by-step instructions for installing the Bit-Bots software stack and ROS 2 can be found in our documentation [here](https://docs.bit-bots.de/meta/manual/tutorials/install_software_ros2.html).
18+
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).
1919

20-
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.
20+
Run the following command inside this repository to build the workspace.
21+
All dependencies will be installed automatically.
22+
Make sure you have [pixi](https://pixi.sh) installed.
23+
A few optional proprietary dependencies will be needed for full functionality, see the documentation for details.
2124

2225
``` shell
2326
pixi run build
2427
```
2528

26-
The first build will take a while as all dependencies are built from source.
27-
Subsequent builds will be much faster.
2829
The first build might fail due to missing dependencies.
2930
Run `pixi run basler` to install the Basler pylon camera driver.
3031

@@ -42,7 +43,13 @@ alternatively, you can run individual commands inside the workspace without acti
4243
pixi run <command>
4344
```
4445

45-
To see some predefined / commands, run
46+
To build the workspace, run the following command in the terminal:
47+
48+
``` shell
49+
pixi run build
50+
```
51+
52+
To see some predefined tasks / commands, run
4653

4754
``` shell
4855
pixi task list
@@ -53,7 +60,7 @@ pixi task list
5360
To deploy the software to a robot, run
5461

5562
``` shell
56-
pixi run deploy <robot_ip|robot_name>
63+
pixi run deploy
5764
```
5865

5966
For more information on the deployment tooling, see [this documentation](scripts/README.md).

‎scripts/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,12 @@ This tool is also callable via `pixi run deploy <arguments>`.
88

99
Deploy, configure, and launch the Bit-Bots software remotely on a robot.
1010
This tool can target all, multiple, or single robots at once, specified by their hostname, robot name, or IP address.
11-
Five different tasks can be performed:
11+
These different tasks can be performed:
1212

1313
1. Synchronize the local source code to the target workspace
14-
3. Configure game-settings and wifi on the target
15-
4. Build (compile) the workspace on the target
16-
5. Launch the teamplayer software on the target
14+
2. Configure game-settings and wifi on the target
15+
3. Build (compile) the workspace on the target
16+
4. Launch the teamplayer software on the target
1717

1818
### Example usage
1919

‎scripts/make_basler.sh‎

Lines changed: 84 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -8,52 +8,106 @@ set -eEo pipefail
88
PYLON_DOWNLOAD_URL="https://data.bit-bots.de/pylon_7_4_0_14900_linux_x86_64_debs.tar.gz.gpg"
99
PYLON_VERSION="7.4.0"
1010

11+
CI=false
12+
SKIP_OS_CHECK=false
13+
SHOW_PROGRESS="--show-progress"
14+
UNKNOWN_ARGS=()
15+
16+
print_help() {
17+
echo "Usage: $0 [--ci] [--skip-os-check] [--help]"
18+
echo
19+
echo " --ci Run non-interactively for CI (skips confirmation and progress)"
20+
echo " --skip-os-check Skip the Ubuntu version/OS check"
21+
echo " -h, --help Show this help message and exit"
22+
}
23+
24+
# Parse arguments position-independently
25+
for arg in "$@"; do
26+
case "$arg" in
27+
--ci)
28+
CI=true
29+
SHOW_PROGRESS=""
30+
;;
31+
--skip-os-check)
32+
SKIP_OS_CHECK=true
33+
;;
34+
-h|--help)
35+
print_help
36+
exit 0
37+
;;
38+
*)
39+
UNKNOWN_ARGS+=("$arg")
40+
;;
41+
esac
42+
done
43+
44+
# If unknown arguments were passed, warn and show help
45+
if [[ ${#UNKNOWN_ARGS[@]} -gt 0 ]]; then
46+
echo "Unknown argument(s): ${UNKNOWN_ARGS[*]}"
47+
echo
48+
print_help
49+
exit 1
50+
fi
51+
1152
# Check let the user confirm that they read the license agreement on the basler website and agree with it.
1253
echo "You need to confirm that you read the license agreements for pylon $PYLON_VERSION on the basler download page (https://www.baslerweb.com/en/downloads/software-downloads/) and agree with it."
13-
14-
# Check --ci flag for automatic confirmation in the ci
15-
if [[ $1 == "--ci" ]]; then
16-
echo "Running in a CI environment, continuing..."
17-
SHOW_PROGRESS=""
18-
else
19-
# Ask the user if they want to continue and break if they don't
54+
# If not running in CI, ask the user to confirm license agreement
55+
if [[ "$CI" != true ]]; then
2056
read -p "Do you want to continue? [y/N] " -n 1 -r
21-
57+
echo
2258
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
2359
echo "Aborting..."
2460
exit 1
2561
fi
26-
SHOW_PROGRESS="--show-progress"
2762
fi
2863

64+
check_os_is_required_ubuntu_version () {
65+
# Check if the OS is ubuntu
66+
echo "Checking for compatible OS..."
67+
if [[ "$(lsb_release -is)" != "Ubuntu" ]]; then
68+
echo "This driver package only supports Ubuntu (and some Debian derivatives)."
69+
echo "Please install Ubuntu >= 18.04 and try again OR try it on a compatible Debian derivative with --skip-os-check."
70+
exit 1
71+
fi
72+
}
73+
2974
check_internet_connection () {
3075
# Check if we have an internet connection, except in the ci as azure does not support ping by design
31-
if [[ $1 != "--ci" ]] && ! ping -q -c 1 -W 1 google.com > /dev/null; then
76+
if [[ "$CI" != true ]] && ! ping -q -c 1 -W 1 google.com > /dev/null; then
3277
echo "No internet connection. Please check your internet connection to install the basler drivers."
3378
exit 1
3479
fi
3580
}
3681

37-
# Check if the correct pylon driver PYLON_VERSION is installed (apt)
38-
if apt list pylon --installed | grep -q $PYLON_VERSION; then
82+
# Check if the correct pylon driver PYLON_VERSION is installed (use dpkg-query)
83+
INSTALLED_VERSION=$(dpkg-query -W -f='${Version}' pylon 2>/dev/null || true)
84+
if [[ -n "$INSTALLED_VERSION" && "$INSTALLED_VERSION" == *"$PYLON_VERSION"* ]]; then
3985
echo "Pylon driver $PYLON_VERSION is already installed."
86+
exit 0
87+
fi
88+
89+
echo "Pylon driver $PYLON_VERSION is not installed. Installing..."
90+
# Check if the OS is the required ubuntu version
91+
if [[ "$SKIP_OS_CHECK" != true ]]; then
92+
check_os_is_required_ubuntu_version
4093
else
41-
echo "Pylon driver $PYLON_VERSION is not installed. Installing..."
42-
# Check if we have an internet connection
43-
check_internet_connection "$1"
44-
# Check if the url exist
45-
if ! curl --output /dev/null --silent --head --fail "$PYLON_DOWNLOAD_URL"; then
46-
echo "Pylon download url does not exist. Please check the url and update the 'PYLON_DOWNLOAD_URL' variable in the 'make_basler.sh' script. The website might have changed."
47-
exit 1
48-
fi
49-
# Download the pylon driver to temp folder
50-
wget --no-verbose $SHOW_PROGRESS $PYLON_DOWNLOAD_URL -O /tmp/pylon_${PYLON_VERSION}.tar.gz.gpg
51-
# Extract the pylon driver
52-
mkdir -p /tmp/pylon
53-
# Decrypt the pylon driver
54-
gpg --batch --yes --passphrase "12987318371043223" -o /tmp/pylon_${PYLON_VERSION}.tar.gz -d /tmp/pylon_${PYLON_VERSION}.tar.gz.gpg
55-
# Extract the pylon driver
56-
tar -xzf /tmp/pylon_${PYLON_VERSION}.tar.gz -C /tmp/pylon/
57-
# Install the pylon driver
58-
sudo apt-get install /tmp/pylon/pylon_${PYLON_VERSION}*.deb -y
94+
echo "Skipping OS check."
95+
fi
96+
97+
# Check if we have an internet connection
98+
check_internet_connection
99+
# Check if the url exist
100+
if ! curl --output /dev/null --silent --head --fail "$PYLON_DOWNLOAD_URL"; then
101+
echo "Pylon download url does not exist. Please check the url and update the 'PYLON_DOWNLOAD_URL' variable in the 'make_basler.sh' script. The website might have changed."
102+
exit 1
59103
fi
104+
# Download the pylon driver to temp folder
105+
wget --no-verbose $SHOW_PROGRESS $PYLON_DOWNLOAD_URL -O /tmp/pylon_${PYLON_VERSION}.tar.gz.gpg
106+
# Extract the pylon driver
107+
mkdir -p /tmp/pylon
108+
# Decrypt the pylon driver
109+
gpg --batch --yes --passphrase "12987318371043223" -o /tmp/pylon_${PYLON_VERSION}.tar.gz -d /tmp/pylon_${PYLON_VERSION}.tar.gz.gpg
110+
# Extract the pylon driver
111+
tar -xzf /tmp/pylon_${PYLON_VERSION}.tar.gz -C /tmp/pylon/
112+
# Install the pylon driver
113+
sudo apt-get install /tmp/pylon/pylon_${PYLON_VERSION}*.deb -y

‎scripts/setup.sh‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ set -eEuo pipefail
44
# static/global variables
55
DIR="$(dirname "$(readlink -f "$0")")"
66
BRANCH="${1:-main}"
7-
REPO_URL="git@github.com:bit-bots/bitbots_main.git"
7+
REPO_URL_SSH="git@github.com:bit-bots/bitbots_main.git"
8+
REPO_URL_HTTPS="https://github.com/bit-bots/bitbots_main.git"
89

910
ask_question() {
1011
while true; do
@@ -19,40 +20,62 @@ ask_question() {
1920
}
2021

2122
setup_pixi() {
22-
curl -fsSL https://pixi.sh/install.sh | sh
23+
if ! type pixi &> /dev/null; then
24+
curl -fsSL https://pixi.sh/install.sh | sh
25+
export PATH="$PATH:$HOME/.pixi/bin"
26+
fi
2327
}
2428

2529
setup_repo() {
2630
echo "Setting up bitbots_main repository..."
2731

2832
if (( in_repo )); then
29-
cd "$meta_dir" || exit
33+
cd "$main_dir" || exit
3034
git checkout "$BRANCH"
3135
else
3236
if [[ ! -d "$PWD/bitbots_main" ]]; then
33-
git clone "$REPO_URL"
37+
echo "Cloning repository bitbots_main..."
38+
# Try to clone via SSH first. If it fails, warn and ask user how to proceed.
39+
if ! git clone "$REPO_URL_SSH"; then
40+
echo "SSH clone failed. This may mean your SSH keys are not set up for GitHub."
41+
echo "See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh"
42+
if ask_question "Do you want to continue with an HTTPS clone instead of fixing SSH keys now?"; then
43+
echo "Cloning via HTTPS..."
44+
git clone "$REPO_URL_HTTPS"
45+
else
46+
echo "Please set up your SSH keys and re-run this script. Exiting."
47+
exit 1
48+
fi
49+
fi
3450
git checkout "$BRANCH"
3551
fi
3652

37-
meta_dir="$(realpath "$PWD/bitbots_main")"
38-
cd "$meta_dir" || exit
53+
main_dir="$(realpath "$PWD/bitbots_main")"
54+
cd "$main_dir" || exit
3955
fi
4056

4157
echo "Installing dependencies..."
42-
$HOME/.pixi/bin/pixi install
58+
install
4359
}
4460

4561
setup_host() {
4662
echo "Setting up system dependencies not covered by pixi. This may require sudo rights. For non-Ubuntu systems, please install the required packages manually."
4763
if (( has_sudo )); then
48-
$meta_dir/scripts/make_basler.sh
64+
$main_dir/scripts/make_basler.sh
65+
basler_installed=1
4966
fi
5067
}
5168

5269
build_repository() {
53-
echo "Running full colcon build..."
70+
echo "Running full build..."
5471
set +u
55-
$HOME/.pixi/bin/pixi run build
72+
73+
# Append "--packages-skip bitbots_basler_camera" to the build command if setup_host was skipped or failed
74+
if (( basler_installed )); then
75+
pixi run build
76+
else
77+
pixi run build --packages-skip bitbots_basler_camera
78+
fi
5679
}
5780

5881
has_sudo=0
@@ -63,13 +86,15 @@ if (( ! has_sudo )); then
6386
echo "Because, you don't have sudo rights, no host dependencies will be installed."
6487
fi
6588

89+
basler_installed=0
90+
6691
in_repo=1
67-
meta_dir="$(realpath "$DIR/../")"
68-
if [[ ! -d "$meta_dir/.git" ]]; then
92+
main_dir="$(realpath "$DIR/../")"
93+
if [[ ! -d "$main_dir/.git" ]]; then
6994
in_repo=0
7095
fi
7196

72-
setup_ros
97+
setup_pixi
7398
setup_repo
7499
setup_host
75100
build_repository

‎src/bitbots_misc/bitbots_docs/CMakeLists.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ find_package(ament_cmake REQUIRED)
77
# then, we can't build the documentation in this package
88
file(COPY files DESTINATION ${CMAKE_INSTALL_PREFIX}/share/${PROJECT_NAME})
99

10-
# we cannot use the compiled catkin package of bitbots_docs since that would
11-
# require this package to depend on itself. therefore we need to compile the sub
12-
# cmake file ourselves and include it manually
10+
# we cannot use the compiled package of bitbots_docs since that would require
11+
# this package to depend on itself. therefore we need to compile the sub cmake
12+
# file ourselves and include it manually
1313
configure_file(cmake/enable_bitbots_docs.cmake.in
1414
${CMAKE_BINARY_DIR}/enable_bitbots_docs.cmake @ONLY)
1515
include(${CMAKE_BINARY_DIR}/enable_bitbots_docs.cmake)

‎src/bitbots_misc/bitbots_docs/cmake/enable_bitbots_docs.cmake.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
function(enable_bitbots_docs)
2-
# create directories neccessary for sphinx
2+
# create directories necessary for sphinx
33
file(MAKE_DIRECTORY ${CMAKE_SOURCE_DIR}/docs/_build/doxyoutput)
44
file(COPY @CMAKE_INSTALL_PREFIX@/share/bitbots_docs/files/_static DESTINATION ${CMAKE_SOURCE_DIR}/docs)
55

‎src/bitbots_misc/bitbots_docs/docs/_static/bitbots_cpp_style.xml‎

Lines changed: 0 additions & 59 deletions
This file was deleted.

‎src/bitbots_misc/bitbots_docs/docs/_static/bitbots_python_style.xml‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)