From 4f604ee40df861d98bdbbeb7267130d224b06d49 Mon Sep 17 00:00:00 2001 From: Mujtaba Date: Sat, 22 Aug 2026 14:00:29 -0600 Subject: [PATCH 1/2] Fix macOS RViz launch and setup guide --- BuildInstructions.md | 305 ++++++++++++++++++++++++-- scripts/macos.sh | 7 +- waybionic_rviz_plugins/CMakeLists.txt | 6 + 3 files changed, 294 insertions(+), 24 deletions(-) diff --git a/BuildInstructions.md b/BuildInstructions.md index e332d05..340ffb2 100644 --- a/BuildInstructions.md +++ b/BuildInstructions.md @@ -27,52 +27,311 @@ ros2 launch waybionic_bringup ground_station.launch.py ## macOS (Apple Silicon) -The workspace runs natively through RoboStack. Docker and XQuartz are not required. -Intel macOS is not currently verified. +The workspace runs natively through RoboStack. Docker and XQuartz are not +required. Intel macOS is not currently verified. -### Prerequisites +Run every command below separately. If a command fails, stop and use the +matching troubleshooting section before continuing. -Install the Xcode command-line tools, Git, and Miniforge: +### Step 1: Install the prerequisites + +1. Open Terminal. +2. Install the Xcode command-line tools: + + ```bash + xcode-select --install + ``` + + If macOS reports that the tools are already installed, continue to the next + step. + +3. Verify that Homebrew is installed: + + ```bash + brew --version + ``` + + If the command is not found, install Homebrew from + [brew.sh](https://brew.sh/), reopen Terminal, and run the verification + command again. + +4. Install Git: + + ```bash + brew install git + ``` + +5. Install Miniforge: + + ```bash + brew install --cask miniforge + ``` + +6. Close Terminal and open a new Terminal window. +7. Verify the required commands: + + ```bash + git --version + ``` + + ```bash + mamba --version + ``` + + ```bash + xcrun --show-sdk-path + ``` + + Do not continue until all three commands succeed. + +### Step 2: Clone or open the repository + +For a new clone, run: + +```bash +mkdir -p ~/waybionic +``` ```bash -xcode-select --install -brew install git -brew install --cask miniforge +cd ~/waybionic ``` -Reopen the terminal if `mamba` or `conda` is not immediately available. +```bash +git clone https://github.com/Waybionic/waybionic_ground_station.git +``` -### Setup and launch +```bash +cd waybionic_ground_station +``` -For a new clone, run: +For an existing clone, open Terminal and change to its repository root. For +the default location above, run: + +```bash +cd ~/waybionic/waybionic_ground_station +``` + +All remaining commands must be run from this repository root. + +### Step 3: Create the RoboStack environment and build + +Run: + +```bash +./scripts/macos.sh setup +``` + +Wait for all workspace packages to finish building. A successful run ends +with: + +```text +Setup complete. Launch with: ./scripts/macos.sh launch +``` + +Do not source `install/setup.bash` directly from zsh. The helper activates the +RoboStack environment and workspace overlay through Bash. + +### Step 4: Launch the ground station + +Run: + +```bash +./scripts/macos.sh launch +``` + +Keep this Terminal window open while using the application. The helper selects +the active macOS SDK for builds and Cyclone DDS for launches. Do not replace +this command with a direct `colcon` or `ros2 launch` invocation. + +### Step 5: Verify the application + +Within a few seconds: + +1. The RViz splash screen is replaced by the main RViz window. +2. `DiagnosticsPanel` displays **WayBionic Engineering Monitor**. +3. The monitor displays **Current State: NORMAL**. +4. Joint State Publisher displays the `base_to_arm` slider. + +Open a second Terminal window and run: + +```bash +cd ~/waybionic/waybionic_ground_station +``` + +```bash +RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ./scripts/macos.sh run ros2 node list +``` + +The output must include: + +```text +/joint_state_publisher +/robot_state_publisher +/rviz2 +``` + +### Step 6: Close the application + +Return to the Terminal window running the launch command and press +Control+C. Confirm that both RViz and Joint State +Publisher close. + +### Step 7: Update an existing clone + +Change to the repository root: ```bash -git clone https://github.com/Waybionic/waybionic_ground_station.git && cd waybionic_ground_station && ./scripts/macos.sh setup +cd ~/waybionic/waybionic_ground_station ``` -For an existing clone, run `./scripts/macos.sh setup` from the repository root. -The command creates or updates the `waybionic_robostack` environment and builds -the workspace. +Pull the latest changes: + +```bash +git pull +``` + +Update the environment and rebuild: + +```bash +./scripts/macos.sh setup +``` -Launch RViz and Joint State Publisher GUI: +Launch again: ```bash ./scripts/macos.sh launch ``` -Other useful commands: +### Useful commands + +Rebuild the workspace without updating the environment: ```bash -./scripts/macos.sh build # rebuild the workspace -./scripts/macos.sh run ros2 topic list # run any overlaid ROS command +./scripts/macos.sh build ``` -After pulling repository changes, update and rebuild with: +List ROS topics while the ground station is running: ```bash -git pull && ./scripts/macos.sh setup +RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ./scripts/macos.sh run ros2 topic list ``` -If RViz reports a missing workspace package, rerun `./scripts/macos.sh build`. -Do not source `install/setup.bash` directly from zsh; the helper handles the -workspace overlay through Bash. +### macOS troubleshooting + +Run the commands in this section from the repository root. + +#### `mamba` or `conda` is not found + +1. Close Terminal and open a new Terminal window. +2. Run: + + ```bash + mamba --version + ``` + +3. If the command is still missing, reinstall Miniforge: + + ```bash + brew install --cask miniforge + ``` + +4. Close Terminal, reopen it, and restart at Step 2. + +#### Setup cannot solve the environment or reports missing ROS tools + +This recovery applies when setup prints +`Could not solve for environment specs`, `colcon: not found`, or +`xacro: not found`, or reports a missing Joint State Publisher. + +1. Confirm that the environment already exists: + + ```bash + mamba env list + ``` + +2. If the output does not contain `waybionic_robostack`, return to Step 3 and + rerun setup; do not run the repair command below against a new environment. +3. If the environment exists, repair it without upgrading its working ROS + packages: + + ```bash + mamba install --yes --name waybionic_robostack --freeze-installed \ + --channel conda-forge --channel robostack-jazzy \ + colcon-common-extensions ros-jazzy-xacro \ + ros-jazzy-joint-state-publisher-gui + ``` + +4. Rebuild: + + ```bash + ./scripts/macos.sh build + ``` + +5. Launch: + + ```bash + ./scripts/macos.sh launch + ``` + +#### CMake reports a missing OpenGL framework header + +This error names +`/System/Library/Frameworks/OpenGL.framework/Headers`. The current helper +resolves the installed SDK path with `xcrun`. + +1. Pull the latest changes: + + ```bash + git pull + ``` + +2. Rebuild: + + ```bash + ./scripts/macos.sh build + ``` + +3. Launch: + + ```bash + ./scripts/macos.sh launch + ``` + +#### RViz remains on `Initializing` + +A shell override may be forcing Fast DDS instead of Cyclone DDS. + +1. Stop the launch with Control+C. +2. Remove the override: + + ```bash + unset RMW_IMPLEMENTATION + ``` + +3. Launch through the helper: + + ```bash + ./scripts/macos.sh launch + ``` + +#### `DiagnosticsPanel` reports `_PyExc_RuntimeError` + +The error also names `libwaybionic_rviz_plugins.dylib`. + +1. Stop the launch with Control+C. +2. Clean the plugin's CMake cache and rebuild only that package: + + ```bash + ./scripts/macos.sh run colcon build \ + --packages-select waybionic_rviz_plugins \ + --cmake-clean-cache --symlink-install + ``` + +3. Launch: + + ```bash + ./scripts/macos.sh launch + ``` + +4. Confirm that `DiagnosticsPanel` displays **WayBionic Engineering Monitor** + instead of the loader error. diff --git a/scripts/macos.sh b/scripts/macos.sh index dd297ac..69ad5a5 100755 --- a/scripts/macos.sh +++ b/scripts/macos.sh @@ -67,6 +67,10 @@ select_manager() { prepare() { check_host select_manager + if [[ -z "${CONDA_BUILD_SYSROOT:-}" ]]; then + CONDA_BUILD_SYSROOT="$(xcrun --show-sdk-path)" + export CONDA_BUILD_SYSROOT + fi } setup_environment() { @@ -150,7 +154,8 @@ case "$command_name" in ;; launch) prepare - run_workspace ros2 launch waybionic_bringup ground_station.launch.py "$@" + run_workspace env RMW_IMPLEMENTATION="${RMW_IMPLEMENTATION:-rmw_cyclonedds_cpp}" \ + ros2 launch waybionic_bringup ground_station.launch.py "$@" ;; run) [[ $# -gt 0 ]] || fail "run requires a command" diff --git a/waybionic_rviz_plugins/CMakeLists.txt b/waybionic_rviz_plugins/CMakeLists.txt index 2d8ec7f..09030aa 100644 --- a/waybionic_rviz_plugins/CMakeLists.txt +++ b/waybionic_rviz_plugins/CMakeLists.txt @@ -41,6 +41,12 @@ target_include_directories(${PROJECT_NAME} PUBLIC target_link_libraries(${PROJECT_NAME} Qt5::Widgets) ament_target_dependencies(${PROJECT_NAME} ${THIS_PACKAGE_INCLUDE_DEPENDS}) +if(APPLE) + # RoboStack exports optional Python type-support dylibs through RViz targets. + # Do not retain those unused dylibs in this C++-only plugin. + target_link_options(${PROJECT_NAME} PRIVATE "LINKER:-dead_strip_dylibs") +endif() + pluginlib_export_plugin_description_file(rviz_common plugin_description.xml) install( From 5f98816366874e3653bb7f4315cded809ce17737 Mon Sep 17 00:00:00 2001 From: Mujtaba Date: Sat, 22 Aug 2026 14:12:36 -0600 Subject: [PATCH 2/2] Condense macOS setup instructions --- BuildInstructions.md | 302 +++++++++++-------------------------------- 1 file changed, 79 insertions(+), 223 deletions(-) diff --git a/BuildInstructions.md b/BuildInstructions.md index 340ffb2..7a0d6db 100644 --- a/BuildInstructions.md +++ b/BuildInstructions.md @@ -28,135 +28,73 @@ ros2 launch waybionic_bringup ground_station.launch.py ## macOS (Apple Silicon) The workspace runs natively through RoboStack. Docker and XQuartz are not -required. Intel macOS is not currently verified. +required. Intel macOS is not verified. -Run every command below separately. If a command fails, stop and use the -matching troubleshooting section before continuing. +### First-time setup -### Step 1: Install the prerequisites - -1. Open Terminal. -2. Install the Xcode command-line tools: +1. Install the prerequisites: ```bash xcode-select --install - ``` - - If macOS reports that the tools are already installed, continue to the next - step. - -3. Verify that Homebrew is installed: - - ```bash - brew --version - ``` - - If the command is not found, install Homebrew from - [brew.sh](https://brew.sh/), reopen Terminal, and run the verification - command again. - -4. Install Git: - - ```bash brew install git - ``` - -5. Install Miniforge: - - ```bash brew install --cask miniforge ``` -6. Close Terminal and open a new Terminal window. -7. Verify the required commands: + If Homebrew is missing, install it from [brew.sh](https://brew.sh/) first. + If Xcode reports that its tools are already installed, continue. - ```bash - git --version - ``` +2. Close Terminal, open a new Terminal window, and verify Miniforge: ```bash mamba --version ``` +3. Clone the repository: + ```bash - xcrun --show-sdk-path + mkdir -p ~/waybionic + cd ~/waybionic + git clone https://github.com/Waybionic/waybionic_ground_station.git + cd waybionic_ground_station ``` - Do not continue until all three commands succeed. - -### Step 2: Clone or open the repository - -For a new clone, run: - -```bash -mkdir -p ~/waybionic -``` - -```bash -cd ~/waybionic -``` - -```bash -git clone https://github.com/Waybionic/waybionic_ground_station.git -``` - -```bash -cd waybionic_ground_station -``` - -For an existing clone, open Terminal and change to its repository root. For -the default location above, run: - -```bash -cd ~/waybionic/waybionic_ground_station -``` - -All remaining commands must be run from this repository root. - -### Step 3: Create the RoboStack environment and build - -Run: + For an existing clone, skip the clone commands and change to that + repository's root directory. -```bash -./scripts/macos.sh setup -``` - -Wait for all workspace packages to finish building. A successful run ends -with: +4. Create the RoboStack environment and build the workspace: -```text -Setup complete. Launch with: ./scripts/macos.sh launch -``` + ```bash + ./scripts/macos.sh setup + ``` -Do not source `install/setup.bash` directly from zsh. The helper activates the -RoboStack environment and workspace overlay through Bash. + Wait for `Setup complete` before continuing. -### Step 4: Launch the ground station +### Launch -Run: +From the repository root, run: ```bash ./scripts/macos.sh launch ``` -Keep this Terminal window open while using the application. The helper selects -the active macOS SDK for builds and Cyclone DDS for launches. Do not replace -this command with a direct `colcon` or `ros2 launch` invocation. +Keep this Terminal window open. Within a few seconds: -### Step 5: Verify the application +- The RViz splash screen is replaced by the main window. +- `DiagnosticsPanel` displays **WayBionic Engineering Monitor** and + **Current State: NORMAL**. +- Joint State Publisher displays the `base_to_arm` slider. -Within a few seconds: +To stop the application, return to the launch Terminal and press +Control+C. -1. The RViz splash screen is replaced by the main RViz window. -2. `DiagnosticsPanel` displays **WayBionic Engineering Monitor**. -3. The monitor displays **Current State: NORMAL**. -4. Joint State Publisher displays the `base_to_arm` slider. +Always use `scripts/macos.sh`. It selects the macOS SDK and Cyclone DDS and +loads the workspace correctly. Do not source `install/setup.bash` from zsh or +replace the helper with direct `colcon` or `ros2 launch` commands. -Open a second Terminal window and run: +### Verify ROS nodes -```bash -cd ~/waybionic/waybionic_ground_station -``` +While the application is running, open a second Terminal, change to the +repository root, and run: ```bash RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ./scripts/macos.sh run ros2 node list @@ -170,168 +108,86 @@ The output must include: /rviz2 ``` -### Step 6: Close the application - -Return to the Terminal window running the launch command and press -Control+C. Confirm that both RViz and Joint State -Publisher close. - -### Step 7: Update an existing clone - -Change to the repository root: - -```bash -cd ~/waybionic/waybionic_ground_station -``` +### Update or rebuild -Pull the latest changes: +After pulling repository changes: ```bash git pull -``` - -Update the environment and rebuild: - -```bash ./scripts/macos.sh setup ``` -Launch again: +To rebuild without updating the environment: ```bash -./scripts/macos.sh launch +./scripts/macos.sh build ``` -### Useful commands +### Troubleshooting -Rebuild the workspace without updating the environment: +Run these commands from the repository root. After applying a fix, use the +single command in the **Launch** section. -```bash -./scripts/macos.sh build -``` +#### `mamba` is not found -List ROS topics while the ground station is running: +Close and reopen Terminal. If `mamba --version` still fails, reinstall +Miniforge and reopen Terminal again: ```bash -RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ./scripts/macos.sh run ros2 topic list +brew install --cask miniforge ``` -### macOS troubleshooting - -Run the commands in this section from the repository root. - -#### `mamba` or `conda` is not found - -1. Close Terminal and open a new Terminal window. -2. Run: - - ```bash - mamba --version - ``` - -3. If the command is still missing, reinstall Miniforge: - - ```bash - brew install --cask miniforge - ``` - -4. Close Terminal, reopen it, and restart at Step 2. - #### Setup cannot solve the environment or reports missing ROS tools -This recovery applies when setup prints -`Could not solve for environment specs`, `colcon: not found`, or -`xacro: not found`, or reports a missing Joint State Publisher. - -1. Confirm that the environment already exists: +Use this for `Could not solve for environment specs`, `colcon: not found`, +`xacro: not found`, or a missing Joint State Publisher. - ```bash - mamba env list - ``` - -2. If the output does not contain `waybionic_robostack`, return to Step 3 and - rerun setup; do not run the repair command below against a new environment. -3. If the environment exists, repair it without upgrading its working ROS - packages: - - ```bash - mamba install --yes --name waybionic_robostack --freeze-installed \ - --channel conda-forge --channel robostack-jazzy \ - colcon-common-extensions ros-jazzy-xacro \ - ros-jazzy-joint-state-publisher-gui - ``` +First confirm that `waybionic_robostack` appears in: -4. Rebuild: +```bash +mamba env list +``` - ```bash - ./scripts/macos.sh build - ``` +If it exists, repair and rebuild it: -5. Launch: +```bash +mamba install --yes --name waybionic_robostack --freeze-installed \ + --channel conda-forge --channel robostack-jazzy \ + colcon-common-extensions ros-jazzy-xacro \ + ros-jazzy-joint-state-publisher-gui +./scripts/macos.sh build +``` - ```bash - ./scripts/macos.sh launch - ``` +If the environment does not exist, rerun the first-time setup command instead. #### CMake reports a missing OpenGL framework header -This error names -`/System/Library/Frameworks/OpenGL.framework/Headers`. The current helper -resolves the installed SDK path with `xcrun`. - -1. Pull the latest changes: +If the error names +`/System/Library/Frameworks/OpenGL.framework/Headers`, update and rebuild: - ```bash - git pull - ``` - -2. Rebuild: - - ```bash - ./scripts/macos.sh build - ``` - -3. Launch: - - ```bash - ./scripts/macos.sh launch - ``` +```bash +git pull +./scripts/macos.sh build +``` #### RViz remains on `Initializing` -A shell override may be forcing Fast DDS instead of Cyclone DDS. - -1. Stop the launch with Control+C. -2. Remove the override: - - ```bash - unset RMW_IMPLEMENTATION - ``` +Stop the application with Control+C, remove any Fast DDS +override, and use the launch command above: -3. Launch through the helper: - - ```bash - ./scripts/macos.sh launch - ``` +```bash +unset RMW_IMPLEMENTATION +``` #### `DiagnosticsPanel` reports `_PyExc_RuntimeError` -The error also names `libwaybionic_rviz_plugins.dylib`. - -1. Stop the launch with Control+C. -2. Clean the plugin's CMake cache and rebuild only that package: +Stop the application, clean the plugin's CMake cache, and rebuild it: - ```bash - ./scripts/macos.sh run colcon build \ - --packages-select waybionic_rviz_plugins \ - --cmake-clean-cache --symlink-install - ``` - -3. Launch: - - ```bash - ./scripts/macos.sh launch - ``` +```bash +./scripts/macos.sh run colcon build \ + --packages-select waybionic_rviz_plugins \ + --cmake-clean-cache --symlink-install +``` -4. Confirm that `DiagnosticsPanel` displays **WayBionic Engineering Monitor** - instead of the loader error. +The panel should display **WayBionic Engineering Monitor** after the next +launch.