To start docker container for running SDK. This will run on port 8000 by default.
cd $EARTH_ROVER_SDK_DIR
./scripts/run_docker.sh
ssh -L 8000:0.0.0.0:8000 $SERVERNAMEWhile in the docker container, run the following command to start the earth-rovers-sdk.
cd earth-rovers-sdk
hypercorn main:app --reloadTo build docker container for running SDK.
cd $EARTH_ROVER_SDK_DIR
./build_docker.sh-
Acquire one of our Earth Rovers in here: Earth Rovers Shop.
-
Complete your Bot activation.
-
After completing your bot activation. Get your SDK Access token in here.
- Python 3.9 or higher
- Frodobots API key
- Google Chrome (Or any browser) installed
For full details on the hardware specifications, please refer to the Frodobots Hardware Specifications.
More details about the bot sensors and actuators can be found here.
- Write once your .env variables provided by Frodobots team your SDK API key and the name of the bot you've got.
SDK_API_TOKEN=
BOT_SLUG=
CHROME_EXECUTABLE_PATH=
# Default value is MAP_ZOOM_LEVEL=18 https://wiki.openstreetmap.org/wiki/Zoom_levels
MAP_ZOOM_LEVEL=
MISSION_SLUG=- Install the SDK
pip3 install -r requirements.txt- Run the SDK
hypercorn main:app --reload- Now you can check the live streaming of the bot in the following URL: http://localhost:8000
This SDK is meant to control the bot and at the same time monitor its status. The SDK has the following open endpoints:
With this endpoint you can send linear and angular values to move the bot. The values are between -1 and 1.
curl --location 'http://localhost:8000/control' \
--header 'Content-Type: application/json' \
--data '{
"command": { "linear": 1, "angular": 1 }
}'Example response:
{
"message": "Command sent successfully"
}With this endpoint you can retrieve the latest data from the bot. (e.g. battery level, position, etc.)
curl --location 'http://localhost:8000/data'Example Response:
{
"battery": 100,
"signal_level": 5,
"orientation": 128,
"lamp": 0,
"speed": 0,
"gps_signal": 31.25,
"latitude": 22.753774642944336,
"longitude": 114.09095001220703,
"vibration": 0.31,
"timestamp": 1724189733.208559,
"accels": [
[0.998,0.003,0.005,1725434620.858],
[1,0.002,0.005,1725434620.964],
[1,0.002,0.005,1725434620.964],
[1,0.003,0.004,1725434621.079],
[0.997,0.003,0.008,1725434621.192],
[0.998,0.003,0.002,1725434621.294]
],
"gyros": [
[0.521,0.023,0.716,1725434620.913],
[0.552,0.023,0.732,1725434621.02],
[0.483,0.015,0.732,1725434621.122],
[0.407,-0.007,0.747,1725434621.239],
[0.453,0.061,0.724,1725434621.343]
],
"mags": [
[-1002,967,12,1725434621.194]
],
"rpms": [
[0,0,0,0,1725434567.194],
[0,0,0,0,1725434567.218],
[0,0,0,0,1725434597.682],
[0,0,0,0,1725434597.701],
[0,0,0,0,1725434597.726]
],
}With this endpoint you can retrieve the latest emitted frame and timestamp from the bot. The frame is a base64 encoded image. And the timestamp is the time when the frame was emitted (Unix Epoch UTC timestamp). Inside the folder screenshots/ you can find the images.
This endpoint accepts a list of view types as a query parameter (view_types). Valid view types are rear, map, and front. If no view types are provided, it will return all three by default.
curl --location 'http://localhost:8000/screenshot?view_types=rear,map,front'Example Response:
{
"front_frame": "base64_encoded_image",
"rear_frame": "base64_encoded_image",
"map_frame": "base64_encoded_image",
"timestamp": 1724189733.208559
}curl --location 'http://localhost:8000/screenshot?view_types=rear'Example Response:
{
"rear_video_frame": "base64_encoded_image",
"timestamp": 1724189733.208559
}With this endpoint you can retrieve the latest emitted frame and timestamp from the bot. The frame is a base64 encoded image. And the timestamp is the time when the frame was emitted (Unix Epoch UTC timestamp).
This endpoint retrieves the latest emitted frame (both front and rear) and the corresponding timestamp. The frame is provided as a base64 encoded image, and the timestamp is given in Unix Epoch format (Unix Epoch UTC timestamp).
Unlike the standard screenshot method, this version returns frames 15 times faster and always includes both the front and rear frames.
curl --location 'http://localhost:8000/v2/screenshot'Example Response:
{
"front_frame": "base64_encoded_image",
"rear_frame": "base64_encoded_image",
"timestamp": 1724189733.208559
}This endpoint allows you to retrieve the latest frame emitted from the bot's front camera. The frame is provided as a base64 encoded image.
curl --location 'http://localhost:8000/v2/front'Example Response:
{
"front_frame": "base64_encoded_image"
}This endpoint allows you to retrieve the latest frame emitted from the bot's rear camera. The frame is provided as a base64 encoded image.
curl --location 'http://localhost:8000/v2/rear'Example Response:
{
"rear_frame": "base64_encoded_image"
}In order to start a mission you need to call the /start-mission endpoint. This endpoint will let you know if the bot is available or not for the mission.
To enable the missions API you need to set the MISSION_SLUG environment variable to the slug of the mission you want to start.
MISSION_SLUG=mission-1If you just want to experiment with the bot without starting a mission you need to remove the MISSION_SLUG environment variable.
Note: Bots that are controlled by other players are not available for missions.
curl --location --request POST 'http://localhost:8000/start-mission'Successful Response (Code: 200)
{
"message": "Mission started successfully"
}Unsuccessful Response (Code: 400)
{
"detail": "Bot unavailable for SDK"
}With this endpoint you can retrieve the list of checkpoints for the mission. And the latest checkpoint that was scanned by the bot. If you scan the first checkpoint, the latest_scanned_checkpoint will be 1. If you scan the last checkpoint, the latest_scanned_checkpoint will be the highest sequence number and the mission will be completed.
curl --location 'http://localhost:8000/checkpoints-list'Example Response:
{
"checkpoints_list": [
{
"id": 4818,
"sequence": 1,
"latitude": "30.48243713",
"longitude": "114.3026428"
},
{
"id": 4819,
"sequence": 2,
"latitude": "30.48268318",
"longitude": "114.3026047"
},
{
"id": 4820,
"sequence": 3,
"latitude": "30.48243713",
"longitude": "114.3026428"
}
],
"latest_scanned_checkpoint": 0
}With this endpoint you can send the checkpoint that was scanned by the bot.
curl -X POST 'http://localhost:8000/checkpoint-reached' \
--header 'Content-Type: application/json' \
--data '{}'Successful Response (Code: 200)
{
"message": "Checkpoint reached successfully",
"next_checkpoint_sequence": 2
}Unsuccessful Response (Code: 400)
{
"detail": {
"error": "Bot is not within XX meters from the checkpoint",
"proximate_distance_to_checkpoint": 16.87
}
}With this endpoint you can force the mission to end in case you face some errors. Note that once you run this endpoint, the bot will be disconnected and will be available again for other players to use.
In case you get stucked and don't want to lose your progress, you can use the /start-mission endpoint to refresh it.
⚠️ This endpoint should only be used in case of emergency. If you run this endpoint you will lose all your progress during the mission.
curl --location --request POST 'http://localhost:8000/end-mission'Example Response:
{
"message": "Mission ended successfully"
}With this endpoint you can retrieve the missions history of the bot you've been riding.
curl --location 'http://localhost:8000/missions-history'Example Response:
{
"mission_rides": [
{
"id": 86855,
"mission_slug": "mission-1",
"success": true,
"latest_scanned_checkpoint": 3,
"status": "active",
"start_time": "2024-09-02T07:38:46.755Z",
"end_time": "2024-09-02T07:45:46.755Z"
},
// ...
]
}- v.4.4: Minor Bugfixes. Spectate Rides.
- v.4.3: Missions history and more information on checkpoint reached. Improved /data RTM messages
- v.4.2: Updated Readme.md
- v.4.1: End mission.
- v.4.0: Added the ability to start a mission. Improved screenshots timings. Timestamps accuracy improved.
- v3.3: Improved control speed.
- v3.2: Added the ability to control the zoom level of the map.
- v3.1: Ability to retrieve rear camera frame and map screenshot. Bug fixes.