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.

We can create a login token and use that for the Freedom Rest API calls to generate a token and secret.

1. For this exercise, create a token you using Freedom's REST API Endpoint. We will want to ensure put is enabled for accounts, device, and device_commands.

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. That will 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 by copy pasting the code into a .sh file:

TOKEN="<<DEVICE_TOKEN>>"
SECRET="<<DEVICE_SECRET>>"
ACCOUNT="<<ACCOUNT>>"
DEVICE="<<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 "<<API_URL>>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="<<USER_TOKEN>>"
SECRET="<<USER_SECRET>>"
ACCOUNT="<<ACCOUNT>>"
DEVICE="<<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 "<<API_URL>>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="<<USER_TOKEN>>"
SECRET="<<USER_SECRET>>"
ACCOUNT="<<ACCOUNT>>"
DEVICE="<<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 "<<API_URL>>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!