Content
# Ranger Mini 2.0 CAN + ROS 2 Control
This project controls an AgileX Ranger Mini 2.0 over CAN on Ubuntu 22.04 with
ROS 2 Humble.
Software stack:
```text
command/ranger_move.py
↓ /cmd_vel, /odom, /system_state
official ranger_ros2
↓
official ugv_sdk
↓ SocketCAN can0
Ranger Mini 2.0
```
## Daily use
### 1. Check CAN
The USB-CAN interface is `can0` at 500 kbit/s:
```bash
ip -details -statistics link show can0
```
The expected state is:
```text
state UP
can state ERROR-ACTIVE
bitrate 500000
```
To inspect CAN frames without sending commands:
```bash
candump can0
```
Press `Ctrl+C` to stop.
If `can0` is not running:
```bash
cd /home/sqz/projects/ranger_interface
./scripts/setup_can.sh can0
```
The recommended one-command startup is:
```bash
start-ranger
```
`start-ranger` first checks whether `can0` is already `UP`, `ERROR-ACTIVE`, and
configured at 500 kbit/s. If so, it skips redundant CAN setup. Otherwise, it
configures CAN and then always starts ROS 2 command mode. The command occupies
the current terminal; keep that terminal open after startup.
If the current shell has not loaded the shortcuts yet:
```bash
source ~/.bash_aliases
```
The underlying scripts remain available for diagnostics or manual startup:
```bash
cd /home/sqz/projects/ranger_interface
./scripts/setup_can.sh can0
./scripts/start_command_mode.sh can0
```
### 2. Clear startup errors
After the chassis is powered on again, it may show error code `0x03000000`,
which corresponds to `0x0300` in the SDK.
Clear the error as follows:
1. Turn on the remote controller.
2. Move `SWB` to the upper position.
3. Move `SWA` to the lower position.
4. Move the left wheel to its lowest position.
5. Press `KEY1` and wait for steering auto-calibration to finish.
6. Move `SWB` to the middle position to enter RC mode.
7. Hold `KEY1` and move the chassis slightly.
8. Stop the chassis and move `SWB` back to the upper position.
The remote controller can be turned off after the error is cleared. A normal
system-state frame should look similar to:
```text
can0 211 [8] 00 00 ... 00 00 00 00
```
### 3. Start the ROS driver
The recommended command is:
```bash
start-ranger
```
For manual startup, use:
```bash
source /home/sqz/projects/ranger_interface/scripts/setup_workspace.sh
ros2 launch ranger_bringup ranger_mini_v2.launch.py port_name:=can0
```
The equivalent simplified command is:
```bash
cd /home/sqz/projects/ranger_interface
./scripts/start_command_mode.sh can0
```
Wait for:
```text
Ranger accepted CAN control mode; motion commands enabled
```
If the chassis has already been cleared and is in a normal state, pressing
`KEY1` again is usually unnecessary.
### 4. Send motion commands
Open a second terminal. The recommended shortcut for forward motion is:
```bash
move_forward 0.2
```
This automatically loads the ROS environment and runs the odometry-closed-loop
controller to drive 0.2 meters. Rotation is also available:
```bash
rotate 1.570796
```
This means a 90-degree counter-clockwise rotation. `rotate -0.174533` means a
10-degree clockwise rotation. These shortcuts require a Bash terminal with
`~/.bash_aliases` loaded, and the terminal running `start-ranger` must remain
open.
If the shortcuts are not available in the current terminal:
```bash
source ~/.bash_aliases
```
The underlying Python command can also be called directly after loading the
workspace:
```bash
source /home/sqz/projects/ranger_interface/scripts/setup_workspace.sh
```
Without this `source` command, Python cannot find `ranger_msgs` and will report
a missing ROS module. The shortcuts load the environment automatically.
Drive forward 0.2 meters:
```bash
python3 /home/sqz/projects/ranger_interface/command/ranger_move.py drive 0.2
```
Drive backward 0.2 meters:
```bash
python3 /home/sqz/projects/ranger_interface/command/ranger_move.py drive -0.2
```
Rotate counter-clockwise by 10 degrees:
```bash
python3 /home/sqz/projects/ranger_interface/command/ranger_move.py rotate 0.174533
```
Rotate clockwise by 10 degrees:
```bash
python3 /home/sqz/projects/ranger_interface/command/ranger_move.py rotate -0.174533
```
Shortcut-to-Python mapping:
```text
move_forward 0.2 -> ranger_move.py drive 0.2
rotate -0.174533 -> ranger_move.py rotate -0.174533
```
`move_forward` accepts signed distances: positive values drive forward and
negative values drive backward. For example:
```bash
move_forward -0.1
```
Parameter ranges:
```text
drive: [-1.0, 1.0] meters
rotate: [-π, π] radians
```
Positive angles are counter-clockwise; negative angles are clockwise.
### 5. Safe shutdown
Press the following in the terminal running the ROS launch:
```text
Ctrl+C
```
The node will:
1. Send zero velocity repeatedly.
2. Request that the chassis leave CAN command mode.
3. Wait for the chassis to enter `STANDBY`.
4. Shut down the ROS node.
Normal output is:
```text
Safe shutdown: sending zero velocity and requesting STANDBY
Safe shutdown complete: Ranger left CAN control mode
```
Do not close the terminal abruptly, force-kill the process, or unplug the
USB-CAN first. These actions may cause communication error `0x02000000`.
## Control program
The motion program is:
```text
command/ranger_move.py
```
It provides two odometry-closed-loop functions:
```python
rotate(angle_rad)
drive(distance_m)
```
Both functions use `/odom` feedback:
- `rotate()` controls the accumulated yaw change;
- `drive()` projects the position change onto the initial heading to control
the traveled distance.
Safety mechanisms include:
- Motion is allowed only in `NORMAL + CAN + error_code=0`;
- stopping when `/odom` or `/system_state` becomes stale;
- parameter range limits;
- an overall motion timeout;
- repeated zero-velocity commands on normal completion, errors, or `Ctrl+C`.
There is currently no obstacle detection, tactile sensing, or stall detection.
Run motion commands only in a clear area with a human supervising the chassis.
## Build
Install dependencies:
```bash
cd /home/sqz/projects/ranger_interface
./scripts/install_dependencies.sh
```
Build the workspace:
```bash
cd /home/sqz/projects/ranger_interface
./scripts/build.sh
```
The workspace contains two official upstream projects:
- `src/ugv_sdk`: CAN communication and protocol encoding/decoding;
- `src/ranger_ros2`: ROS 2 nodes and topic interfaces.
This project adds Ranger Mini 2.0 parameter fixes, CAN command-mode handshake
retry, a zero-velocity heartbeat, motion-state gating, and safe shutdown
behavior to the upstream code.
`staged_packages/` is an archived prototype excluded by `COLCON_IGNORE`. It is
not part of the current build or runtime workflow. Do not use its control nodes.
## ranger-robot MCP Server
The MCP wrapper is located at:
```text
mcp/ranger_robot/
```
It accesses an already-running `ranger_base_node` through ROS 2. It does not
access CAN directly and does not start or stop `start_command_mode`. The
default Streamable HTTP endpoint is:
```text
http://10.100.6.232:8000/mcp
```
For MCP tools, Bearer Token configuration, systemd deployment, and read-only
tests, see:
```text
mcp/ranger_robot/README.md
```
