REST

While connected to a DotBot gateway, the dotbot-controller application provides a REST server to send commands to and receive information from connected DotBots.

The REST API is documented in the running dotbot-controller application itself at http://localhost:8000/api. This page also allows you to play with the API directly from the browser.

Prerequisites

Make sure you already followed the getting started page and have a functional setup with dotbot-controller running and connected to a nRF DK gateway.

To interact with the REST API, you will use the Python requests package. You can install it on your computer using pip:

pip install -U requests

The basics

First, let’s start by fetching the information about available DotBots using the following script:

import json
import requests

get_endpoint = "controller/dotbots"

print(
    json.dumps(
        requests.get(
            f"http://localhost:8000/{get_endpoint}"
        ).json()
    )
)

If a DotBot is connected, this script should give an output similar to:

[
  {
    "address": "9903ef26257feb31",
    "application": 0,
    "swarm": "0000",
    "status": 2,
    "mode": 0,
    "last_seen": 1701244665.8099585,
    "waypoints": [],
    "waypoints_threshold": 40,
    "position_history": []
  }
]

This is a list of all DotBots connected to the dotbot-controller. In the example above, there is only one DotBot connected. The 8-byte address uniquely identifies a DotBot in the controller. The status indicates whether the DotBot is Alive (value=0, the DotBot has been seen within the last 5 seconds), Lost (value=1, the DotBot hasn’t been seen within the last 5 sec) or Dead (value=2, the DotBot hasn’t been seen for more than 60 sec).

If the DotBot address is already known by the controller, e.g. it identifies one of the DotBots returned a the previous request, use the controller/dotbots/<address> to fetch information about that particular DotBot (for example controller/dotbots/9903ef26257feb31).

Change the color of the RGB LED

Use the controller/dotbots/{address}/{application}/rgb_led endpoint to change the RGB LED color on the 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 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:

{
  "red": 0,
  "green": 0,
  "blue": 0
}

Here is an example Python script to send a “RGB LED” request to one DotBot:

import requests

ADDRESS = "DOTBOT_ADDRESS_HERE"  # edit this line with the DotBot address you want to control
RGB_LED_VALUE = {
    "red": 255,
    "green": 0,
    "blue": 0,
}

requests.put(
    f"http://localhost:8000/controller/dotbots/{ADDRESS}/0/rgb_led",
    json=RGB_LED_VALUE,
)

Play with the red/green/blue values to change the DotBot RGB LED.

Move one DotBot

Use the controller/dotbots/{address}/{application}/move_raw endpoint to move a DotBot.

This request, according to the API is also a PUT request and requires a payload:

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

To control the DotBot motors, 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 below 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 200ms. To move the DotBot continuously, several commands must be sent with a delay below 200ms between them.

Here is an example Python script to send a “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_VALUE = {
    "left_x": 0,
    "left_y": 60,
    "right_x": 0,
    "right_y": 60
}

requests.put(
    f"http://localhost:8000/controller/dotbots/{ADDRESS}/0/move_raw",
    json=MOVE_RAW_VALUE,
)

Adapt the script above to:

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

• rotate a DotBot during 20 seconds