Freedom Robotics

Freedom Robotics Developer Hub

Welcome to the Freedom Robotics developer hub!

You'll find comprehensive guides and documentation to help you start working with Freedom Robotics as quickly as possible, as well as support if you get stuck. Let's jump right in!

For guides to setting up a device and using Freedom's core features, choose Get Started. If you'd prefer to jump in by yourself, choose Reference for detailed interface specifications.

Get Started    Reference

Connect with REST API

The Freedom API is organized around REST. The API has predictable resource-oriented URLs, requests and returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

In this guide, we'll walk through a few examples of common API calls. For the full API specification, consult the REST API Reference.

Tokens

The Freedom API uses revokable tokens to define access and permitted actions for users and devices.

To create a token, proceed to MENU → TEAM SETTINGS and click the TOKENS button (please be patient, this will take a few moments to load). You'll see options to create DEVICE, USER, SHARING, and CUSTOM tokens.

For more details about the permissions associated with different types of tokens, see the Access Token Specification section of the API reference.

Keeping secrets safe

Your API token includes a secret. Don't share or post it online (including on public version control repositories).

Send a message to the cloud

Let's have your robot send its first message to the cloud using the Freedom API!

Click Log In in the top right corner of this page so we can fill in the values for your token, secret, account, and device for the next examples.

We'll start by sending a GPS position from your robot. Run the following:

TOKEN=""
SECRET=""
ACCOUNT=""
DEVICE=""
HEADERS="-H content-type:application/json -H mc_token:$TOKEN -H mc_secret:$SECRET"
DATA="[{
    \"platform\": \"custom\", 
    \"utc_time\": `date +%s`,
    \"topic\": \"/location\",
    \"type\": \"sensor_msgs/NavSatFix\",
    \"data\": {\"latitude\":37.778454, \"longitude\":-122.389171}
}]"

curl -v $HEADERS -d "$DATA" -X PUT "accounts/$ACCOUNT/devices/$DEVICE/data"

This code sample sends latitude and longitude data of type sensor_msgs/NavSatFix to the /location topic. The message will show up in the Freedom App in your STREAM dashboard, showing a map with the location of your device.

Send a message to your robot

Let's now send a simple command to your robot. The following code sample sends a "data":"mission" message of type std_msgs/String to the /commands topic.

If you would like your robot to respond, you'll need to set up a callback to receive the command.

TOKEN=""
SECRET=""
ACCOUNT=""
DEVICE=""
HEADERS="-H content-type:application/json -H mc_token:$TOKEN -H mc_secret:$SECRET"
DATA="[{
    \"platform\": \"custom\", 
    \"utc_time\": `date +%s`,
    \"topic\": \"/commands\",
    \"type\": \"std_msgs/String\",
    \"expiration_secs\": 60,
    \"message\": {\"data\":\"mission\"}
}]"

curl -v $HEADERS -d "$DATA" -X PUT "accounts/$ACCOUNT/devices/$DEVICE/commands"

Retrieve your robot's logs

Throughout this guide, the Freedom App has logged all messages sent from your device. It's easy to retrieve those logs! Run the command below to receive a time-ordered list of all messages uploaded from your device in the last 5 minutes.

TOKEN=""
SECRET=""
ACCOUNT=""
DEVICE=""
HEADERS="-H content-type:application/json -H mc_token:$TOKEN -H mc_secret:$SECRET"

# Request the last 5 minutes of data for this device

curl -v $HEADERS -X GET "accounts/$ACCOUNT/devices/$DEVICE/data?utc_start=-5m&pagination=true"

Success! You now know how to use the Freedom API to upload data and communicate with your robot through the cloud.

What's next?

If you would like to read walkthroughs of usage for key aspects of the system, the guides for Monitoring, Alerts and Integrations, and Teleop and Control are a great place to start.

If you prefer reviewing detailed API specs and references, you can do that also.

If you like to poke around applications, go to the Freedom App and explore!

Updated about a month ago

Connect with REST API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.