This tutorial shows how to connect with Protobuf using Python. For other languages, please reach out.

Send a message

Let's have your robot send its first message to the cloud! We'll start by sending a GPS position from your robot.

First, create a file called sensor_msgs.proto and copy in the code below to define the message type.

syntax = "proto3";

message NavSatFix {
  float latitude = 1;
  float longitude = 2;
}

Compile your .proto file by running the following command:

protoc --python_out=. sensor_msgs.proto

📘

Compiler installation

If you haven't installed the protocol buffer compiler (protoc), download the package and follow the instructions in the README.

Next, create a Python file called robot.py and use the sample code below.

from sensor_msgs_pb2 import NavSatFix
from freedomrobotics.link_protobuf import LinkProtobuf

# Connect to the cloud with LinkProtobuf
freedom = LinkProtobuf(name="Core")

# Send your GPS position
message = NavSatFix()
message.latitude = 37.778454
message.longitude = -122.389171
freedom.protobuf_message("/location", message)

Next, run your code with python robot.py. The message will show up in the Freedom App in your STREAM dashboard, showing the latitude and longitude of your device under the /location topic.

Receive a message

Let's now send a simple command to your robot.

Set up a callback

To prepare your robot to receive and respond to a command, we'll need to set up a callback.

We'll demonstrate a simple case where the robot responds to a command sent as a string. First, create a file called string.proto and copy in the code below to define the message type.

syntax = "proto3";

message String {
  string data = 1;
}

Compile your .proto file by running the following command:

protoc --python_out=. string.proto

Next, create a file called callback.py and copy in the code below.

from time import sleep

from google.protobuf.json_format import MessageToDict
from freedomrobotics.link_protobuf import LinkProtobuf

from string_pb2 import String

keep_alive = True

# Create a callback to handle remote messages
def callback(msg):
    global keep_alive
    freedom.log("info", "I heard " + str(msg))
    if msg.data == "mission":
        freedom.log("info", "Running mission...")
    elif msg.data == "shutdown":
        freedom.log("info", "Shutting down...")
        keep_alive = False

# Connect to the cloud with LinkProtobuf
freedom = LinkProtobuf(protobuf_command_callback=callback)

while keep_alive:
    sleep(1)

Run the code with python callback.py. Your robot is now waiting patiently for a remote command.

Test the callback

To check that the callback works, we'll send a command to your device using Freedom's REST API.

If you haven't already, click Log In in the top right corner of this page so we can populate the values for your token, secret, account, and device for this example. Once you've logged in, run the following 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\": \"string_pb2.String\",
    \"expiration_secs\": 60,
    \"message\": {\"data\":\"mission\"}
}]"

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

The message will be received in the callback you set up. Once your robot receives the command, it will log Running mission....

Change mission to shutdown and send a new command. Your application will now shut down remotely.

Success! You now know how to use Freedom 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!