Robot Documentations/Guides

Start Cruise

This guide shows how to start a cruise (patrol route) on the robot using curl from a bash script.

Prerequisites:

  • The robot API is reachable, e.g., http://192.168.1.100:5000
  • curl and jq are installed on your machine
  • At least one cruise exists or a default cruise route is configured
#!/usr/bin/env bash
set -euo pipefail

# Configuration
ROBOT_URL="${ROBOT_URL:-http://192.168.1.100:5000}"
CRUISE_ROUTE="${CRUISE_ROUTE:-}"   # Optional, leave empty to use default or first available
ROUNDS="${ROUNDS:-2}"               # Number of rounds

command -v jq >/dev/null 2>&1 || { echo "jq is required (sudo apt install jq)"; exit 1; }

echo "============================================================"
echo "Start Cruise"
echo "============================================================"

echo "[1/3] Listing existing cruises..."
cruises_json=$(curl -sS "${ROBOT_URL}/api/v1/cruises")
cruises_count=$(echo "$cruises_json" | jq 'length')

if [ "$cruises_count" -gt 0 ]; then
  echo "✓ Found ${cruises_count} cruises:"; echo
  echo "$cruises_json" | jq -r 'to_entries[] | "\(.key+1). \(.value.name)\n   Site: \(.value.site_floor.site), Floor: \(.value.site_floor.floor)\n   Number of waypoints: \(.value.waypoints | length)\n"'
else
  echo "⚠ No cruises found. You should create a cruise first or ensure a default route exists."
fi

echo
echo "[2/3] Checking default cruise route..."
default_route_resp=$(curl -sS "${ROBOT_URL}/api/v1/config/default-route" || true)
default_route=$(echo "$default_route_resp" | jq -r '.route // empty' || true)
if [ -n "$default_route" ]; then
  echo "✓ Default route: $default_route"
else
  echo "⚠ Default route not found"
fi

# Decide which route to use
route_to_use="$CRUISE_ROUTE"
if [ -z "$route_to_use" ]; then
  if [ "$cruises_count" -gt 0 ]; then
    route_to_use=$(echo "$cruises_json" | jq -r '.[0].name // empty')
    echo "Using first available cruise: $route_to_use"
  else
    route_to_use=""  # leave empty to rely on default route
  fi
fi

if [ -z "$route_to_use" ] && [ -z "$default_route" ]; then
  echo "✗ No cruise available and no default route configured. Aborting."
  exit 1
fi

echo
echo "[3/3] Starting cruise..."
start_body=$(jq -n \
  --arg cmd "CMD_START" \
  --arg route "$route_to_use" \
  --arg rounds "$ROUNDS" \
  '{cruise_cmd:$cmd, cruise_route:$route, number_of_rounds: ($rounds|tonumber)}')

start_resp=$(curl -sS -X POST "${ROBOT_URL}/api/v1/cruises/control" \
  -H 'Content-Type: application/json' \
  -d "$start_body")

ok=$(echo "$start_resp" | jq -r '.success // empty')
msg=$(echo "$start_resp" | jq -r '.message // empty')
if [ "$ok" = "true" ]; then
  using_label="$([ -n "$route_to_use" ] && echo "$route_to_use" || echo "default route")"
  echo "✓ $msg"
  echo
  echo "Cruise started: ${using_label}"
  echo "Robot started patrolling! 🚀"
else
  echo "✗ Error: ${msg}"
fi

echo
echo "============================================================"
echo "You can stop the cruise using the CMD_STOP command."
echo "============================================================"

Notes:

  • You can override ROBOT_URL, CRUISE_ROUTE, and ROUNDS via environment variables.
  • If CRUISE_ROUTE is empty, the script uses the first available cruise; if none is available, it relies on the default route.