Temboo returns Choreo result data to the Yún 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 Yún 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 Yún 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);
}
}
The complete sketch should now look like:
/*
YahooWeather
This example code is in the public domain.
*/
#include <Bridge.h>
#include <Temboo.h>
#include "TembooAccount.h" // contains Temboo account information
// the address for which a weather forecast will be retrieved
String ADDRESS_FOR_FORECAST = "104 Franklin St., New York NY 10013";
int numRuns = 1; // execution count, so that this doesn't run forever
int maxRuns = 10; // max number of times the Yahoo WeatherByAddress Choreo should be run
void setup() {
Serial.begin(9600);
// for debugging, wait until a serial console is connected
delay(4000);
while(!Serial);
Bridge.begin();
}
void loop()
{
// while we haven't reached the max number of runs...
if (numRuns <= maxRuns) {
// print status
Serial.println("Running GetWeatherByAddress - Run #" + String(numRuns++) + "...");
// create a TembooChoreo object to send a Choreo request to Temboo
TembooChoreo GetWeatherByAddressChoreo;
// invoke the Temboo client
GetWeatherByAddressChoreo.begin();
// add your temboo account info
GetWeatherByAddressChoreo.setAccountName(TEMBOO_ACCOUNT);
GetWeatherByAddressChoreo.setAppKeyName(TEMBOO_APP_KEY_NAME);
GetWeatherByAddressChoreo.setAppKey(TEMBOO_APP_KEY);
// set the name of the choreo we want to run
GetWeatherByAddressChoreo.setChoreo("/Library/Yahoo/Weather/GetWeatherByAddress");
// set choreo inputs; in this case, the address for which to retrieve weather data
// the Temboo client provides standardized calls to 100+ cloud APIs
GetWeatherByAddressChoreo.addInput("Address", ADDRESS_FOR_FORECAST);
// add an output filter to extract the name of the city.
GetWeatherByAddressChoreo.addOutputFilter("city", "/rss/channel/yweather:location/@city", "Response");
// add an output filter to extract the current temperature
GetWeatherByAddressChoreo.addOutputFilter("temperature", "/rss/channel/item/yweather:condition/@temp", "Response");
// add an output filter to extract the date and time of the last report.
GetWeatherByAddressChoreo.addOutputFilter("date", "/rss/channel/item/yweather:condition/@date", "Response");
// run the choreo
GetWeatherByAddressChoreo.run();
// parse the results and print them to the serial monitor
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);
}
}
Serial.println("");
Serial.println("Waiting...");
Serial.println("");
delay(30000); // wait 30 seconds between GetWeatherByAddress calls
}
}
Save and upload your sketch. You should now see the parsed individual result components printed to the serial monitor.
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
If you're working with the Yún Shield paired with another Arduino board, you'll need to make some small changes to the Yún sketch above it so that it's compatible with the Arduino Yún Shield.
1First, change the include statement #include <Temboo.h> to #include <TembooYunShield.h>. Your include statements should look like this:
#include <Bridge.h> #include <TembooYunShield.h> #include "TembooAccount.h"
2Next, change the Temboo object name from TembooChoreo to TembooYunShieldChoreo. Your code should look like this:
TembooYunShieldChoreo GetWeatherByAddressChoreo;
3Now your code is ready to run on your Yún Shield!
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.