Path Planning

This guide covers techniques for planning and executing efficient paths for your mecha using the Gerra API.

Understanding Waypoints

The Gerra API uses a waypoint system for movement. Each waypoint is a coordinate in 2D space relative to the mecha's starting position:

[
  {"x": 0, "y": 0},   // Starting point
  {"x": 2, "y": 0},   // Move 2 meters forward
  {"x": 2, "y": 1.5}, // Move 1.5 meters to the right
  {"x": 0, "y": 1.5}, // Move 2 meters backward
  {"x": 0, "y": 0}    // Return to start
]

Basic Movement Patterns

Simple Linear Movement

curl -X POST "https://api.gerra.com/mecha/action/move?mecha_id=MECHA_ID" \
  -H "Content-Type: application/json" \
  -H "gerra-api-key: YOUR_TOKEN" \
  -d '[{"x": 0, "y": 0}, {"x": 3, "y": 0}]'

Square Pattern

import requests

# Create a 2x2 meter square path
square_path = [
    {"x": 0, "y": 0},   # Starting point
    {"x": 2, "y": 0},   # Move right
    {"x": 2, "y": 2},   # Move up
    {"x": 0, "y": 2},   # Move left
    {"x": 0, "y": 0}    # Return to start
]

headers = {
    "gerra-api-key": "YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.gerra.com/mecha/action/move",
    params={"mecha_id": "MECHA_ID"},
    headers=headers,
    json=square_path
)

Tron1 Stair Climbing Example

The Tron1 model has specialized capabilities for navigating stairs. Here's how to implement a path that involves:

Moving straight
Enabling stair climbing mode
Climbing stairs
Disabling stair mode
Continuing on level ground

import requests
import time

# API configuration
API_TOKEN = "YOUR_TOKEN"
MECHA_ID = "YOUR_TRON1_ID"
BASE_URL = "https://api.gerra.com/mecha"

headers = {
    "gerra-api-key": API_TOKEN,
    "Content-Type": "application/json"
}

# Step 1: Move straight toward stairs (5 meters)
initial_path = [
    {"x": 0, "y": 0},
    {"x": 5, "y": 0}
]

print("Moving toward stairs...")
response = requests.post(
    f"{BASE_URL}/action/move",
    params={"mecha_id": MECHA_ID},
    headers=headers,
    json=initial_path
)

# Step 2: Enable stair climbing mode
print("Enabling stair mode...")
response = requests.post(
    f"{BASE_URL}/tron/set_mode",
    params={
        "mecha_id": MECHA_ID,
        "mode": "stair_climbing"
    },
    headers=headers
)

# Step 3: Climb stairs
# Note: For Tron1, the Z coordinate is automatically managed in stair mode
stair_path = [
    {"x": 5, "y": 0},  # Current position
    {"x": 8, "y": 0}   # Top of stairs (3 meters forward)
]

print("Climbing stairs...")
response = requests.post(
    f"{BASE_URL}/action/move",
    params={
        "mecha_id": MECHA_ID,
        "speed": 0.3    # Slower speed for stability on stairs
    },
    headers=headers,
    json=stair_path
)

# Step 4: Disable stair climbing mode
print("Disabling stair mode...")
response = requests.post(
    f"{BASE_URL}/tron/set_mode",
    params={
        "mecha_id": MECHA_ID,
        "mode": "standard"
    },
    headers=headers
)

# Step 5: Continue on level ground
final_path = [
    {"x": 8, "y": 0},   # Current position (top of stairs)
    {"x": 12, "y": 0}   # Final destination (4 more meters forward)
]

print("Continuing on level ground...")
response = requests.post(
    f"{BASE_URL}/action/move",
    params={"mecha_id": MECHA_ID},
    headers=headers,
    json=final_path
)

print("Path completed.")

Key Considerations for Stair Climbing

Mode Switching: Always switch to stair_climbing mode before attempting to climb stairs
Speed Control: Reduce speed (0.2-0.3 m/s) during stair climbing for stability
Straight Approach: Approach stairs head-on for optimal climbing performance
Stair Limitations: Tron1 can handle stairs with:
- Maximum 20cm step height
- Minimum 25cm step depth
- Maximum 35° incline
Sensor Feedback: Monitor diagnostic endpoints to ensure proper stair detection

Advanced Techniques

Curved Paths

For smoother movements, add more waypoints to approximate curves:

import requests
import math

# Create a circular path with 16 points
radius = 2  # 2 meter radius
points = 16  # number of waypoints
circle_path = []

for i in range(points + 1):
    angle = 2 * math.pi * i / points
    x = radius * math.cos(angle)
    y = radius * math.sin(angle)
    circle_path.append({"x": x, "y": y})

headers = {
    "gerra-api-key": "YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.gerra.com/mecha/action/move",
    params={"mecha_id": "MECHA_ID"},
    headers=headers,
    json=circle_path
)

Controlling Speed

You can control the movement speed by adding a speed parameter to your request:

curl -X POST "https://api.gerra.com/mecha/action/move?mecha_id=MECHA_ID&speed=0.5" \
  -H "Content-Type: application/json" \
  -H "gerra-api-key: YOUR_TOKEN" \
  -d '[{"x": 0, "y": 0}, {"x": 3, "y": 0}]'

The speed parameter accepts values between 0.1 and 1.0 meters per second.

Path Planning Algorithms

For complex environments, consider implementing these path planning algorithms:

A Algorithm* - Efficient for finding the shortest path around obstacles
Potential Field Method - Good for dynamic environments
RRT (Rapidly-exploring Random Tree) - Useful for complex spaces

Here's a simple example of generating waypoints to avoid an obstacle:

# Example: Navigate around an obstacle at (1, 1)
obstacle_avoidance_path = [
    {"x": 0, "y": 0},   # Starting point
    {"x": 0, "y": 2},   # Go around obstacle
    {"x": 2, "y": 2},   # Continue path
    {"x": 2, "y": 0}    # Destination
]

Best Practices

Limit Waypoints - Keep waypoint count reasonable (under 50) for optimal performance
Smooth Transitions - Place waypoints closer together for smoother movements
Error Handling - Always check API responses and implement recovery strategies
Test Paths - Start with slow speeds in controlled environments
Monitor Progress - Use the diagnostic endpoints to monitor progress

Next Steps

Check the Action API for all movement command options
Explore WebSocket for real-time control and feedback
Learn about Diagnostics for monitoring mecha state

Path Planning

On this page