Understanding Choreo outputs for Arduino


Temboo returns Choreo result data to the Arduino in a simple key-value format. Each name and value is followed by a newline character (\n), to increase readability, and a record-separator or field-separator hex character (\x1F to delimit names, and \x1E to delimit values). This looks like:

Name1\n\x1F
Value1\n\x1E
Name2\n\x1F
Value2\n\x1E

The Temboo Library provides information on the set of outputs returned by each Choreo. For example, you can see that the Yahoo > Weather > GetWeatherByAddress returns two outputs named Response and WOEID (Yahoo’s “Where On Earth ID” for that address).

Outputs

The outputs returned by the GetWeatherByAddress Choreo

In this case, after running the Yahoo Weather sample sketch in our Getting Started tutorial, the data received by the Arduino would look like:

Response\n\x1F
[a whole bunch of XML here, potentially containing newlines]\n\x1E
WOEID\n\x1F
12761345\n\x1E
HTTP_CODE\n\x1F
200\n\x1E

The last key, HTTP_CODE, is not an explicit output of the GetWeatherByAddress Choreo, but is returned by Temboo to simplify the creation of error handlers (see below). A HTTP code of 200 means that the Choreo executed successfully; any other code indicates that an error occurred.

Output Filter Results

The same format is used whether a particular key/value pair is defined in an output filter or is an unfiltered output from the Choreo. For example, in the Output Filters tutorial, we defined output filters for the Response output of the GetWeatherByAddress Choreo called temperature, date and city. Running this sketch would return something like:

temperature\n\x1F
90\n\x1E
date\n\x1F
Mon, 24 Jun 2013 11:53 am PDT\n\x1E
city\n\x1F
New York\n\x1E
HTTP_CODE\n\x1F
200\n\x1E

Note: Since one or more output filters (temperature, date and city) are defined to filter the Response output, the raw XML value of the Choreo's outputs (Response and WOEID) are not returned.

Reading Results

The key/value format returned by the Temboo server makes it easy to read and use specific results in your Arduino sketch. To demonstrate how this works, we'll modify the sketch from the Output Filters tutorial to read and print individual output values.

To do so, update the contents of the while(GetWeatherByAddressChoreo.available()) loop at the end of the sketch to read:

while(GetWeatherByAddressChoreo.available()) {
    // read the name of the next output item
    String name = GetWeatherByAddressChoreo.readStringUntil('\x1F');
    name.trim(); // use “trim” to get rid of newlines

    // read the value of the next output item
    String data = GetWeatherByAddressChoreo.readStringUntil('\x1E');
    data.trim(); // use “trim” to get rid of newlines

    if (name == "date") {
        Serial.println("The date is " + data);
    } else if (name == "temperature") {
        Serial.println("The temperature is " + data);
    } else if (name == "city") {
        Serial.println("The city is " + data);
    }
}

Error Responses

If an error occurs while running a Choreo (for example, if you comment out the GetWeatherByAddress input that specifies the address to look up), you’ll receive a response like:

Error\n\x1F
"An error has occurred.  Address is required."\n\x1E
HTTP_CODE\n\x1F
500\n\x1E

Need Help?

We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.


Back