Skip to content

HandsOn Tutorial

Jump to bottom
Alexandre Abadie edited this page Jul 10, 2023 · 3 revisions

Hands-On Tutorial

Introduction

This tutorial will help you start playing with real using HTTP REST requests sent to a running dotbot-controller application.

The url of the web application main page is available at https://37cd-128-93-64-23.ngrok-free.app/dotbots/. In the interface, you should see:

  • a list of available DotBots on the left,
  • a square map displaying the position of the DotBots on the ground.

The documentation of the REST API is available at **https://37cd-128-93-64-23.ngrok-free.app/api

Goal of the tutorial

  1. Learn basic requests to get information about available DotBots
  2. Learn how to send requests to the controller to move the DotBots on the ground
  3. Learn how to send requests to let the DotBots navigate following a predefined path

You'll use simple Python scripts with the requests package to send HTTP requests to the controller.

First part: basic get requests

To interact with the controller API, we can start with the following script:

import requests

get_endpoint = "GET/ENDPOINT"  # edit this line with the endpoint you want to query

print(
    requests.get(
        f"https://37cd-128-93-64-23.ngrok-free.app/{get_endpoint}"
    ).json()
)

Let's start by getting some information about the DotBots connected to the controller. The controller/dotbots REST endpoint returns the list of available DotBots. Let's try this one! You should get something like:

[{"address": "5fc92042d8e9f190",
  "application": 0,
  "swarm": "0000",
  "status": 0,
  "mode": 0,
  "last_seen": 1688717778.3574152,
  "waypoints": [],
  "waypoints_threshold": 40,
  "position_history": []},
  ...
  ]

Note the address field of one of the DotBot and use it to get the information of this particular DotBot using controller/dotbots/<address> endpoint (for example: controller/dotbots/5fc92042d8e9f190).

Second part: move one DotBot

Using the controller/dotbots/{address}/{application}/move_raw endpoint, it's possible to move a DotBot. The address parameter in the URL can be retrieved from the list of available DotBots that we got in the previous section. The application parameter is always 0 (DotBot) in our case.

It's important to note that this request, according to the API is a PUT request and requires a payload:

{
  "left_x": 0,
  "left_y": 0,
  "right_x": 0,
  "right_y": 0
}

For the DotBot application type, only left_y and right_y values are useful, left_x and right_x being ignored by the firmware running on the DotBots.

Note 1: left_{x,y} and right_{x,y} values must be within the range [-100, 100] and it's important to know that absolute values < 50 won't move the motors (because of limited power in electronic circuit and internal friction of the motors).

Note 2: The firmware running on the DotBot stops automatically the motors if no move command is received after 20ms. To move the DotBot continuously, several commands must be sent with a delay <20ms between them.

Here is an example Python script to send one "move raw" request to one DotBot:

import requests

ADDRESS = "DOTBOT_ADDRESS_HERE"  # edit this line with the DotBot address you want to control
MOVE_RAW_DATA = {
    "left_x": 0,
    "left_y": 60,
    "right_x": 0,
    "right_y": 60
}

requests.put(
    f"https://37cd-128-93-64-23.ngrok-free.app/controller/dotbots/{ADDRESS}/0/move_raw",
    json=MOVE_RAW_DATA,
)

Adapt the script above to:

  • move a DotBot forward during 10 seconds (use the sleep function from the time module for example)
  • rotate a DotBot during 20 seconds

Third part: DotBot autonomous navigation

The firmware running on the DotBots is capable of autonomously drive to given waypoints using an indoor position system (Lighthouse). Waypoints can be sent to a given DotBot using the /controller/dotbots/{address}/{application}/waypoints endpoint (which is also a PUT request).

Note 1: The (X,Y) coordinate system used on the map goes from [0,0] (top left corner) and [1,1] (bottom right corner).

Note 2: The waypoints endpoint takes a list of (x,y,z) coordinates (he z coordinate is unused and can be 0) which means it's possible to make the DotBot follow a predefined path. Once the last waypoint is reached (e.g. the DotBot position is within a distance threshold around the last waypoint), the DotBot automatically stops.

Note 3: To stop the autonomous navigation, just send an empty list of waypoints.

Here is an example Python script to send a list of 2 waypoints to one DotBot:

import requests

ADDRESS = "DOTBOT_ADDRESS_HERE"  # edit this line with the DotBot address you want to control
WAYPOINTS = {
    "waypoints": [
        {"x": 0.2, "y": 0.2, "z": 0},
        {"x": 0.8, "y": 0.8, "z": 0},
    ],
}

requests.put(
    f"https://37cd-128-93-64-23.ngrok-free.app/controller/dotbots/{ADDRESS}/0/waypoints",
    json=WAYPOINTS,
)

Adapt the script above to:

  • Let the DotBot follow a square within the map (90% of the map)
  • Let the DotBot follow a triangle within the map and reach the center of the map
  • Stop a DotBot while it's still following a list of waypoints

Clone this wiki locally