From 953b5eaab6a6e5f5eadeb430b0d5562e211333ca Mon Sep 17 00:00:00 2001 From: euyniy Date: Mon, 18 May 2026 22:38:29 +0900 Subject: [PATCH 1/3] Update structure --- .../docs/api-reference/can/_category_.json | 4 + website/docs/api-reference/{ => can}/can.mdx | 4 +- website/docs/api-reference/{ => can}/cli.mdx | 2 +- website/docs/api-reference/index.mdx | 4 +- website/docs/api-reference/ros2/install.mdx | 2 +- .../docs/api-reference/setup/5-run-demo.mdx | 2 +- website/docs/api-reference/setup/index.md | 2 +- .../docs/api-reference/ubuntu/_category_.json | 4 - website/docs/api-reference/ubuntu/docker.mdx | 152 ------------------ .../docs/api-reference/ubuntu/dual-boot.mdx | 50 ------ website/docs/api-reference/ubuntu/index.mdx | 124 -------------- 11 files changed, 12 insertions(+), 338 deletions(-) create mode 100644 website/docs/api-reference/can/_category_.json rename website/docs/api-reference/{ => can}/can.mdx (99%) rename website/docs/api-reference/{ => can}/cli.mdx (99%) delete mode 100644 website/docs/api-reference/ubuntu/_category_.json delete mode 100644 website/docs/api-reference/ubuntu/docker.mdx delete mode 100644 website/docs/api-reference/ubuntu/dual-boot.mdx delete mode 100644 website/docs/api-reference/ubuntu/index.mdx diff --git a/website/docs/api-reference/can/_category_.json b/website/docs/api-reference/can/_category_.json new file mode 100644 index 00000000..86a97eba --- /dev/null +++ b/website/docs/api-reference/can/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "CAN", + "position": 4, +} diff --git a/website/docs/api-reference/can.mdx b/website/docs/api-reference/can/can.mdx similarity index 99% rename from website/docs/api-reference/can.mdx rename to website/docs/api-reference/can/can.mdx index f73c4b31..f7d82bae 100644 --- a/website/docs/api-reference/can.mdx +++ b/website/docs/api-reference/can/can.mdx @@ -1,6 +1,6 @@ --- title: CAN Library -sidebar_position: 4 +sidebar_position: 1 --- import TOCInline from '@theme/TOCInline'; @@ -13,7 +13,7 @@ The [OpenArm CAN](https://github.com/enactic/openarm_can/) Library serves as the It abstracts CAN bus communication via utilizing Linux's SocketCAN interface, providing an API for motor control and state monitoring. The library allows extensibility for various CAN devices beyond motors. SocketCAN is Linux's implementation of the CAN (Controller Area Network) protocol stack, providing a socket-based interface for CAN communication. -For detailed setup instructions including CAN interface configuration, library build, and verification steps, see [Setup Guide](./setup/index.md). +For detailed setup instructions including CAN interface configuration, library build, and verification steps, see [Setup Guide](../setup/index.md). ## Table of Contents diff --git a/website/docs/api-reference/cli.mdx b/website/docs/api-reference/can/cli.mdx similarity index 99% rename from website/docs/api-reference/cli.mdx rename to website/docs/api-reference/can/cli.mdx index a9c7eb6f..cbbe5a44 100644 --- a/website/docs/api-reference/cli.mdx +++ b/website/docs/api-reference/can/cli.mdx @@ -1,6 +1,6 @@ --- title: OpenArm CAN CLI -sidebar_position: 4 +sidebar_position: 2 --- # OpenArm CAN CLI Tool diff --git a/website/docs/api-reference/index.mdx b/website/docs/api-reference/index.mdx index a9f0bf01..5f3a4dcf 100644 --- a/website/docs/api-reference/index.mdx +++ b/website/docs/api-reference/index.mdx @@ -43,14 +43,14 @@ URDF and XACRO files that provide representations of OpenArm. These models enabl -**[Learn more under SocketCAN Communication →](can)** +**[Learn more under SocketCAN Communication →](can/can)** A C++ library for communicating with OpenArm motors through Linux's SocketCAN interface. Enables real-time control loops and motor coordination. Offers Python bindings for seamless integration with other frameworks. -**[Learn more under CAN CLI →](cli)** +**[Learn more under CAN CLI →](can/cli)** A command-line tool for configuring and monitoring DaMiao motors over CAN/CAN-FD interfaces. Supports motor discovery, parameter read/write, enable/disable, live telemetry, baudrate changes, and ID assignment. diff --git a/website/docs/api-reference/ros2/install.mdx b/website/docs/api-reference/ros2/install.mdx index 97de3696..567e2bdb 100644 --- a/website/docs/api-reference/ros2/install.mdx +++ b/website/docs/api-reference/ros2/install.mdx @@ -15,7 +15,7 @@ ROS 2 (Robot Operating System 2) is a modern, open-source framework for building ### Prerequisites -- Ubuntu ([Install Ubuntu →](../ubuntu/)) +- Ubuntu ### Choose your ROS 2 diff --git a/website/docs/api-reference/setup/5-run-demo.mdx b/website/docs/api-reference/setup/5-run-demo.mdx index 0441838e..5f183c70 100644 --- a/website/docs/api-reference/setup/5-run-demo.mdx +++ b/website/docs/api-reference/setup/5-run-demo.mdx @@ -83,7 +83,7 @@ Gripper Motor: 8 position: 0.789 Before proceeding, ensure you have the required system: -- Linux with SocketCAN support ([Install Ubuntu →](../ubuntu/)) +- Linux with SocketCAN support - CMake 3.22+ - C++17 compiler diff --git a/website/docs/api-reference/setup/index.md b/website/docs/api-reference/setup/index.md index 7dc4689b..2a0c0061 100644 --- a/website/docs/api-reference/setup/index.md +++ b/website/docs/api-reference/setup/index.md @@ -22,4 +22,4 @@ Make sure you have motors and communication devices at your hands. - For motor control and further setup - SocketCAN-compatible interface device - - Computer running Ubuntu 22.04/24.04 or other linux with SocketCAN support ([Install Ubuntu →](../ubuntu/)) + - Computer running Ubuntu 22.04/24.04 or other linux with SocketCAN support diff --git a/website/docs/api-reference/ubuntu/_category_.json b/website/docs/api-reference/ubuntu/_category_.json deleted file mode 100644 index 65f65d1a..00000000 --- a/website/docs/api-reference/ubuntu/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Install Ubuntu", - "position": 6, -} diff --git a/website/docs/api-reference/ubuntu/docker.mdx b/website/docs/api-reference/ubuntu/docker.mdx deleted file mode 100644 index 129971bc..00000000 --- a/website/docs/api-reference/ubuntu/docker.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Docker -sidebar_position: 2 ---- - -# Running Ubuntu with Docker - -You can run Ubuntu in a container using Docker, without installing it as a full OS. - -:::warning -Docker is not ideal for hardware-heavy or GUI-dependent robotics tools. - -Not recommended for: -- ROS 2 GUI tools (`RViz`, `rqt`, etc.) -- Gazebo, MuJoCo, or Isaac Sim -- Direct USB/serial or real-time control -- NVIDIA GPU rendering without [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) -::: - -## Install Docker - -Follow the [official Docker installation guide](https://docs.docker.com/get-started/get-docker/) for your OS. Or use these quick steps: - -### On Ubuntu -```bash -sudo apt update -sudo apt install -y docker.io -sudo systemctl enable --now docker -sudo usermod -aG docker $USER -``` -:::note -You may need to log out and back in to apply group changes. -::: - -### On Other Linux OS (Distrobox) -On other distributions of Linux, [distrobox](https://distrobox.it/) allows for the use of Ubuntu through Docker or Podman. - -After installing distrobox, run: - -```sh -xhost +local:root -``` - -Then run the following command (you may need to [configure credentials to the Github Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)). - -```sh -docker run --env DISPLAY=$DISPLAY \ - --volume /tmp/.X11-unix:/tmp/.X11-unix \ - --network=host \ - -it ghcr.io/enactic/openarm/ros2:latest-humble \ - /bin/bash -``` - -### On Windows - -Download Docker Desktop: https://www.docker.com/products/docker-desktop - -Follow the GUI install instructions - -### On macOS - -If you are using an Apple Silicon Mac, it may be necessary to enable Rosetta for Docker. - -Follow the instructions at [github.com/tiryoh/docker-ros2-desktop-vnc](https://github.com/Tiryoh/docker-ros2-desktop-vnc/tree/master). -:::note -This will not be very performant, but is good enough for simple experiments. -::: - -## Run a Container - -:::tip Supported Ubuntu + ROS 2 Tags - -Common Docker tags for ROS 2: - -- `osrf/ros:humble` (Ubuntu 22.04) -- `osrf/ros:iron` (Ubuntu 22.04) -- `osrf/ros:jazzy` (Ubuntu 24.04) - -Find more at [Docker Hub](https://hub.docker.com/r/osrf/ros/tags) - -::: - - -```bash -# Plain Ubuntu without ROS (replace XX.XX with any version) -docker run -it ubuntu:XX.XX -``` - -```bash -# Ubuntu + ROS 2 base image (replace with humble, jazzy, etc.) -docker run -it osrf/ros: -``` - -Inside the container, you can install packages as needed. - -```bash -apt update -apt install -y curl git sudo build-essential -``` - -## Persistent Containers - -To avoid losing changes, create a named container that persists: - -```bash -# Ubuntu + ROS 2 base image (replace with humble, jazzy, etc.) -docker run -it --name my-ubuntu-dev osrf/ros: -``` - -To stop and resume: -```bash -docker stop my-ubuntu-dev -docker start -ai my-ubuntu-dev -``` - -## Optional: Mount a Local Folder - -To access code on your host machine: -```bash -# Ubuntu + ROS 2 base image (replace with humble, jazzy, etc.) -docker run -it -v ~/my-code:/workspace osrf/ros: -``` - -Inside the container: -```bash -cd /workspace -``` - -## Optional: Create a Dockerfile (for repeatable setups) - -Instead of manually installing packages each time: - -```Dockerfile -ARG ROS_DISTRO= -#(replace with humble, jazzy, etc.) - -FROM osrf/ros:${ROS_DISTRO} - -RUN apt update && apt install -y \ - ros-${ROS_DISTRO}-desktop \ - python3-colcon-common-extensions \ - git curl sudo && \ - apt clean - -``` - -Then build: -```bash -#(replace with humble, jazzy, etc.) -docker build -t my-ubuntu-dev --build-arg ROS_DISTRO= . -docker run -it my-ubuntu-dev -``` diff --git a/website/docs/api-reference/ubuntu/dual-boot.mdx b/website/docs/api-reference/ubuntu/dual-boot.mdx deleted file mode 100644 index 3f415594..00000000 --- a/website/docs/api-reference/ubuntu/dual-boot.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Windows Dual Boot -sidebar_position: 1 ---- - -import TOCInline from '@theme/TOCInline'; - -# Dual Booting With Windows - -You can install Ubuntu alongside Windows using a shared disk with partitioning. - -### Step 1: Prepare Windows - -1. Back up your data (just in case). -2. Open Disk Management (Win + X → Disk Management). -3. Right-click your main drive (usually C:) → Shrink Volume. -4. Free at least 20–50 GB for Ubuntu (recommended). -5. Leave the new space unallocated (do not format it). - -### Step 2: Boot the Ubuntu USB Installer - -1. Insert the USB and reboot the system -2. Enter BIOS/UEFI (usually by pressing F2, Del, F12, or Esc during startup) -3. Set the USB as the first boot device -4. Save changes and reboot - -### Step 3: Install Ubuntu Alongside Windows - -1. Select Try or Install Ubuntu -2. When prompted for installation type, select: **Install Ubuntu alongside Windows Boot Manager** -3. Use the slider to allocate how much space to give to Ubuntu -4. Continue installation as prompted - -### Step 4: Bootloader Setup - -1. After installation, you’ll see the GRUB boot menu at startup -2. Select between Ubuntu and Windows each time you boot - ---- - -### Fixing Boot Issues - -If Windows doesn't show up in the GRUB menu: - -```bash -sudo os-prober -sudo update-grub -``` - -Or use Boot-Repair from a live USB. \ No newline at end of file diff --git a/website/docs/api-reference/ubuntu/index.mdx b/website/docs/api-reference/ubuntu/index.mdx deleted file mode 100644 index e55dadde..00000000 --- a/website/docs/api-reference/ubuntu/index.mdx +++ /dev/null @@ -1,124 +0,0 @@ -import TOCInline from '@theme/TOCInline'; - -# Installing Ubuntu (Quick Guide) - -This guide walks you through downloading and installing Ubuntu on a physical machine or virtual machine. - -## Table of Contents - - !['Table of Contents'].includes(value))} - maxHeadingLevel={2} -/> - ---- - -## Download Ubuntu - -- Visit the official Ubuntu download page: - [https://ubuntu.com/download/desktop](https://ubuntu.com/download/desktop) -- Recommended version: **Ubuntu 22.04 LTS (Jammy Jellyfish)** -You can find previous releases [here](https://ubuntu.com/download/alternative-downloads#past-releases-and-other-flavours) - -:::tip Want a Lightweight Alternative? -If you're only doing development or testing (not using real hardware or GUI tools like RViz), consider using Docker instead of installing Ubuntu directly. -[See Docker Setup →](docker) -::: - ---- - -## Create a Bootable USB -You'll need: -- A USB drive (at least **8 GB**) -- The downloaded Ubuntu `.iso` file - -Choose your OS below for USB creation instructions: - -### On Windows (Rufus) - -1. Download [Rufus](https://rufus.ie) -2. Plug in your USB stick -3. Select: - - **Device**: your USB - - **Boot selection**: Ubuntu `.iso` file - - **Partition scheme**: GPT (recommended for UEFI) -4. Click **Start** and wait for the write to finish -:::tip -If you would like to keep your operating system: -[See Dual Boot Instructions →](dual-boot) -::: - -### On macOS (Etcher or Terminal) - -**Option A: Balena Etcher (GUI)** -1. Download [Balena Etcher](https://www.balena.io/etcher/) -2. Select the Ubuntu `.iso`, choose your USB, and click **Flash** - -**Option B: Terminal** - -```bash -# Convert ISO to IMG if needed -hdiutil convert -format UDRW -o ubuntu.img ubuntu.iso - -# Find your USB (e.g., /dev/disk2), then: -diskutil unmountDisk /dev/diskX -sudo dd if=ubuntu.img.dmg of=/dev/rdiskX bs=1m -sync -``` -:::warning -Replace X with your actual USB disk number — double check! -::: - -### On Linux -```bash -# Replace this with the path to your downloaded ISO file (any version) -ISO=~/Downloads/ubuntu-XX.XX-desktop-amd64.iso # e.g. ubuntu-22.04.4-desktop-amd64.iso - -# Replace /dev/sdX with your USB device (e.g., /dev/sdb — double check!) -sudo dd if=$ISO of=/dev/sdX bs=4M status=progress && sync -``` -:::warning -Be very careful with /dev/sdX — using the wrong drive can erase your system! -::: - ---- - -## Step 2: Boot the Ubuntu USB Installer - -1. Insert the USB and reboot the system -2. Enter BIOS/UEFI (usually by pressing F2, Del, F12, or Esc during startup) -3. Set the USB as the first boot device -4. Save changes and reboot - ---- - -## Install Ubuntu - -Once the installer loads: - -1. Select Try or Install Ubuntu -2. Select "Erase disk and install Ubuntu" (for a clean install) -:::warning -This will erase all data on the selected drive. -If you would like to keep your operating system: [See Dual Boot Instructions](dual-boot) -::: -3. Choose your timezone -4. Create a username and password -5. Click Install - -Wait for the installation to complete, then remove the USB and reboot when prompted. - ---- - -## Post-Install Setup -After booting into your new system: - -```bash -# Update your system -sudo apt update && sudo apt upgrade -y - -# Install common tools -sudo apt install -y curl git build-essential gnome-tweaks -``` - -You're now ready to install ROS 2 or any development tools you need! From a46543b725d45f45de9e14f2d60fa2ec1fef68f7 Mon Sep 17 00:00:00 2001 From: euyniy Date: Mon, 18 May 2026 22:45:21 +0900 Subject: [PATCH 2/3] Fix references --- website/docs/api-reference/index.mdx | 2 +- website/docs/api-reference/setup/2-can-setup.mdx | 2 +- website/docs/api-reference/setup/4-motor-config.mdx | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/api-reference/index.mdx b/website/docs/api-reference/index.mdx index 5f3a4dcf..d5909c30 100644 --- a/website/docs/api-reference/index.mdx +++ b/website/docs/api-reference/index.mdx @@ -43,7 +43,7 @@ URDF and XACRO files that provide representations of OpenArm. These models enabl -**[Learn more under SocketCAN Communication →](can/can)** +**[Learn more under SocketCAN Communication →](can)** A C++ library for communicating with OpenArm motors through Linux's SocketCAN interface. Enables real-time control loops and motor coordination. Offers Python bindings for seamless integration with other frameworks. diff --git a/website/docs/api-reference/setup/2-can-setup.mdx b/website/docs/api-reference/setup/2-can-setup.mdx index dd9ef4cd..51bb43b7 100644 --- a/website/docs/api-reference/setup/2-can-setup.mdx +++ b/website/docs/api-reference/setup/2-can-setup.mdx @@ -46,7 +46,7 @@ openarm-can-configure-socketcan-4-arms openarm-can-configure-socketcan-4-arms -fd -b 1000000 -d 5000000 ``` -Alternatively, use `openarm-can-cli` to configure individual interfaces. For detailed usage, see [CAN CLI Reference ](../cli#can_configure--configure-can-interface). +Alternatively, use `openarm-can-cli` to configure individual interfaces. For detailed usage, see [CAN CLI Reference ](../can/cli#can_configure--configure-can-interface). ```bash # CAN FD at 5Mbps (recommended) diff --git a/website/docs/api-reference/setup/4-motor-config.mdx b/website/docs/api-reference/setup/4-motor-config.mdx index e0a7502a..d8d14e3f 100644 --- a/website/docs/api-reference/setup/4-motor-config.mdx +++ b/website/docs/api-reference/setup/4-motor-config.mdx @@ -31,7 +31,7 @@ Before changing the baudrate, make sure the CAN interface is configured to match ::: -For detailed usage, see [CAN CLI Reference change_baud](../cli#change_baud--change-motor-baudrate). +For detailed usage, see [CAN CLI Reference change_baud](../can/cli#change_baud--change-motor-baudrate). ```bash # Set temporarily @@ -112,7 +112,7 @@ openarm-can-cli -i can0 monitor --id 1,2,3 The output should display the motor's position, velocity, torque, and temperature in real-time. -For detailed usage, see [CAN CLI Reference monitor](../cli#monitor--live-telemetry-dashboard). +For detailed usage, see [CAN CLI Reference monitor](../can/cli#monitor--live-telemetry-dashboard). :::warning It is important to get the motor communication working before running the demo. From d9a91b0d56924adde9af69beefd598bc3f31c12b Mon Sep 17 00:00:00 2001 From: euyniy Date: Mon, 18 May 2026 22:55:40 +0900 Subject: [PATCH 3/3] Fix tags --- website/docs/api-reference/can/can.mdx | 6 ++++-- website/docs/api-reference/ros2/control.mdx | 9 ++++++--- website/docs/api-reference/setup/5-run-demo.mdx | 3 ++- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/website/docs/api-reference/can/can.mdx b/website/docs/api-reference/can/can.mdx index f7d82bae..9c9d2a29 100644 --- a/website/docs/api-reference/can/can.mdx +++ b/website/docs/api-reference/can/can.mdx @@ -87,7 +87,8 @@ The demo (`openarm_can/examples/demo.cpp`) demonstrates the complete OpenArm API The first step involves creating the OpenArm instance and registering all motor devices with their corresponding CAN IDs and types. -:::warning Vector Length Consistency +:::warning +Vector Length Consistency Ensure that `motor_types`, `send_can_ids`, and `recv_can_ids` vectors have the same length. Each motor requires exactly one entry in each vector at the corresponding index. Mismatched vector lengths can result in initialization errors or undefined behavior. ::: @@ -113,7 +114,8 @@ This section demonstrates how to enable motors and query their internal paramete Switch callback mode properly to parse the received frames. -:::warning Timeout Values +:::warning +Timeout Values Use longer timeout values (1000-2000 microseconds) for slow operations like motor enabling and parameter queries. Fast control operations may use shorter timeouts (300-500 microseconds). Insufficient timeout values can result in missed responses and communication failures. ::: diff --git a/website/docs/api-reference/ros2/control.mdx b/website/docs/api-reference/ros2/control.mdx index cfb74f99..4de4cb27 100644 --- a/website/docs/api-reference/ros2/control.mdx +++ b/website/docs/api-reference/ros2/control.mdx @@ -40,7 +40,8 @@ colcon build source ~/ros2_ws/install/setup.bash ``` -:::danger ⚠️ SAFETY REQUIREMENTS FOR HARDWARE OPERATION +:::danger +⚠️ SAFETY REQUIREMENTS FOR HARDWARE OPERATION Before operating with real hardware, you MUST: @@ -59,7 +60,8 @@ The [openarm_bringup](https://github.com/enactic/openarm_ros2/tree/main/openarm_ The bringup package supports both mock hardware (for simulation/testing) and real hardware through a hardware plugin. When using real hardware, you'll need to first install the `openarm_can` library by following the [CAN setup guide](../can). -:::warning Hardware Bridge Status +:::warning +Hardware Bridge Status The hardware bridging components are currently being updated and may be unstable. The gripper bridging logic is particularly under active development. ::: @@ -204,6 +206,7 @@ The default gain is set to a relatively low value for safety. As a result, the a - Edit `assets/robot/openarm_v1.0/config/arm/control_gains.yaml` - Rebuild by `colcon build` -:::danger ⚠️ GAIN TUNING SAFETY +:::danger +⚠️ GAIN TUNING SAFETY Please adjust the gain with great care. **Start with a lower gain and verify the behavior first, then increase it gradually.** If you execute an action with a large position difference while using a high gain, some controllers may generate dangerously high velocities. ::: \ No newline at end of file diff --git a/website/docs/api-reference/setup/5-run-demo.mdx b/website/docs/api-reference/setup/5-run-demo.mdx index 5f183c70..95d20b26 100644 --- a/website/docs/api-reference/setup/5-run-demo.mdx +++ b/website/docs/api-reference/setup/5-run-demo.mdx @@ -16,7 +16,8 @@ Now that your basic communication is working, let's run the full OpenArm demo pr More details for control can be found [here](../can). -:::danger ⚠️ READ BEFORE RUNNING DEMO ⚠️ +:::danger +⚠️ READ BEFORE RUNNING DEMO ⚠️ - **ZERO POSITION**: Ensure you have set safe zero positions for all motors - **EMERGENCY STOP**: Keep emergency stop button within immediate reach at ALL times