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).
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.
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.
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);
}
}
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
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.