Here we describe the Temboo Library and client program that comes with your Arduino Yún. This in-depth technical documentation is comprehensive and goes into more detail about features discussed in other examples and tutorials.
Included with the Arduino IDE is a small C++ library named Temboo that contains the TembooChoreo class used by sketches use to execute Temboo Choreos. The Temboo client is a small program that resides on the Linino file system and knows how to talk to the Temboo platform. Your Arduino sketches use a TembooChoreo instance to call the Temboo client via a Process object in the Bridge library that comes with the Arduino IDE. The Temboo client then forwards your sketch's Choreo call to the Temboo platform and returns the results to your sketch via the TembooChoreo object.
Temboo provides a consistent, uniform access to many web services. The idea is that once you learn how to use Temboo, you don't have to know the details of how to use all the other services that Temboo knows about. You'll still have to know what inputs a particular service takes and how to get the information you want from the outputs it provides, but the mechanics of making the actual request and getting the response are handled for you by Temboo. So how do you get your sketch to talk to Temboo?
Temboo provides access to its service by way of a REST web interface. A REST interface basically means that you communicate with a service using the same protocol and techniques that your web browser uses to access ordinary websites. So when you make a call to Temboo asking it to execute a Choreo for you, you're essentially doing the same thing as filling out a web form in your browser and hitting the "Submit" button.
The temboo program that gets installed on the Linino side of your Arduino Yún board is a small Python program that knows how to format information your sketch provides in a way that Temboo understands. It packages your inputs up and sends them to Temboo, waits for the results to come back, and makes that returned data available to your sketch. Your sketch provides the inputs to and reads the outputs from TembooChoreo objects.
The TembooChoreo class is a thin wrapper around the Process class from the Bridge library shipped with the Arduino IDE. It knows what parameters the temboo client program takes and provides easy to use access methods for building Choreo execution requests to be sent to the temboo client.
The basic flow goes like this:
1Your sketch creates an instance of TembooChoreo, initializes, and provides inputs to it. These inputs include:
2You tell the TembooChoreo to run.
3When TembooChoreo.run() returns, you can examine the return code to determine if the call succeeded, and read the output from the TembooChoreo object.
The TembooChoreo class is a thin wrapper around Arduino's Process class. The Process class builds up what is essentially a command line that is sent to the Temboo client program to execute programs on the Linino side of the Yún. Command lines typically consist of the name of the program to be run followed by various options and parameters. The temboo client program takes options and parameters in specific formats. The methods in the TembooChoreo class know about these options and the format of the parameters so you don't have to know the technical details if you don't want to.
The TembooChoreo class extends the Process class from Arduino's Bridge library, so all the public methods of Process are also available to the TembooChoreo class. See the Arduino documentation for details about Process methods.
Calling any of the methods whose name begins with "set" multiple times is not considered an error, but the parameter given in the last invocation is the one that will be used. Likewise, calling any of the "add" methods multiple times with the same input or output filter names is not considered an error, but the input or output filter values given in the last invocation are the ones that will be used. This may be useful for overriding input values that only occasionally differ from a standard value.
TembooChoreo ()
The TembooChoreo constructor takes no parameters, so creating an instance is simply:
TembooChoreo myChoreo;
void begin()
Before calling any other methods on the object, you must initialize it with the begin method. If you want to reuse an instance of TembooChoreo, you must call begin after running it and before populating it with new parameters. Calling begin deletes any existing parameters, so it should be called before any other set or add methods. The begin method takes no parameters.
myChoreo.begin();
These methods tell Temboo who you are so that we can let you run Choreos. These methods must always be called before each run of a Choreo.
void setAccountName(const String& accountName)
Specifies your Temboo account name. Example:
myChoreo.setAccountName("MyTembooAccount");
void setAppKeyName(const String& appKeyName)
Specifies the application key you want to use to authenticate with. Most Temboo accounts have a default application key named myFirstApp. You may have more than one application key in your account. An application key name is like a user name, it identifies who is making the call. Example:
myChoreo.setAppKeyName("myFirstApp");
void setAppKey(const String& appKey)
Specifies the value of the application key named with the setAppKeyName method. An application key is a string of letters and digits, they look like this:
a1b2c3d4-e5f6-7890-a
You can get your application key values by visiting My Account.
Application keys are like passwords, so don't share your application key value with other people!
Example:
myChoreo.setAppKey("a1b2c3d4-e5f6-7890-a");
These methods tell the Temboo client what Choreo you want to run and provide it with inputs and output filter specifications.
void setChoreo(const String& choreo)
The choreo parameter is the path to the Choreo you want to run. Temboo has a growing library of pre-made Choreos for accessing web services. You can see all of these Choreos in our Library.
To specify a Choreo to run, the setChoreo method should called with the Choreo's path in the Library. For example, you can use the Yahoo service to get the weather forecast for your location. You would specify this Choreo like this:
/Library/Yahoo/Weather/GetWeatherByAddress
If you have custom Choreos you have created yourself, they live in the "Choreos" folder in your account. You would specify one like this:
/Choreos/myCustomChoreo
Example:
myChoreo.setChoreo("/Library/Yahoo/Weather/GetWeatherByAddress");
void addInput(const String& inputName, const String& inputValue)
Many Choreos take inputs, perhaps a user name and password for the web service you're accessing, or an address or GPS coordinates to tell it where you are. To find out what inputs your Choreo takes, look it up in the Library.
The Input section of the Choreo description gives the names and descriptions of all the required and optional inputs. You specify an input in your sketch with a call to the addInput method giving the input name and its value as String parameters. For example, the Yahoo GetWeatherByAddress Choreo takes one input named "Address", which lets you specify an address you want the forecast for:
myChoreo.addInput("Address", "New York NY 10013");
Some Choreos may not take any inputs, in which case you don't need to call the addInput method at all.
void addOutputFilter(const String& outputName, const String& filterPath, const String& variableName)
Some web services return data in the form of XML or JSON documents. Very often, these documents contain much more information than your sketch may need. For example, the full response from the Yahoo GetWeatherByAddress Choreo is an XML document containing more than 2,000 characters. If you're only interested in today's expected high temperature, it would be nice to not have to work through the entire XML response to get the one value you're interested in. That's what Temboo's output filters are for.
Output filters contain 3 parts:
These items are specified as parameters to the addOutputFilter method.
The name is any name you like, as long as it starts with a letter or a number and contains only letters, numbers, '-', '.', '+', or '@' characters. The Choreo response will contain an item with this name followed by the contents specified by the path segment.
The path is an XPath query into the XML or JSON document. A complete description of XPath queries is beyond the scope of this document, but an example of a path to extract the first high temperature from the Yahoo Choreo output would look like this:
/rss/channel/item/yweather:forecast[1]/@high
To construct the XPath query, you need to know what the raw XML or JSON data looks like. You can usually find this information in the technical documentation at the web service you're using. An easier way when using Choreos from the Temboo Library is to actually execute the Choreo right from its description page on the Temboo website. You can provide inputs, run the Choreo, and see the resulting output directly in your browser (Note: that you cannot specify output filters via the web).
Finally, the output filter needs to know the name of the Choreo output variable that contains the data to be filtered. For Choreos from the Temboo Library, this will often be "Response". You can find the name of each output variable on the Choreo description page.
So putting it all together, the complete output filter specification to get today's high temperature from the Yahoo GetWeatherByAddress Choreo would look like this:
myChoreo.addOutputFilter("HiTemp", "/rss/channel/item/yweather:forecast[1]/@high", "Response");
Output filters are optional. If you want to process the entire output of a Choreo in your sketch, simply don't specify any output filters.
void setCredential(const String& credentialName)
Some Choreos require username and password inputs. Instead of providing them directly when you execute the Choreo, you can store your username and password in a Temboo Credential object so that you don't have to put them in your sketch. If you have a Credential for a Choreo or service, you can use it instead of providing explicit inputs with the setInput method. The setCredential method takes one parameter which is the name of the credential you want to use. Example:
myChoreo.setCredential("MyYahooCredential");
To learn more about Temboo credential objects, check out this video.
Because many of the parameters needed to execute a Choreo will stay the same every time you run the Choreo, the Temboo client includes the ability to store these parameters on the Linino file system and retrieve them when you execute the Choreo. This lets you set up constant parameters in your setup function and only provide the parameters that change in your loop function. Or you can create constant parameter sets ahead of time and store them on an SD card or USB drive for later use with your sketches.
void setSettingsFileToWrite(const String& filePath)
The filePath is the name of a file in which settings will be stored. Choreos are NOT run when you use the setSettingsFileToWrite method, the only action when you call run is that the settings are stored. The setting-name must be a valid Linux file name with an optional absolute path. If the optional absolute path does not exist, it will be created. If a file of the same name exists at the same location, it will be silently overwritten.
If only a file name is specified, the settings will be stored in a directory named /tmp/temboo in the Linino file system. Anything stored in /tmp will be deleted when you lose power or reset your Yún board. If you wish for the settings file to be persistent across power loss or resets, you should specify a directory on an SD card or USB drive that is plugged into the board (e.g. /arduino/yun/temboo). Using a directory other than /tmp/temboo on the built in Linino file system is possible but not recommended due to the possibility of overwriting critical system files as well as increasing wear on the Linino flash memory.
It is an error to use both setSettingsFileToRead and setSettingsFileToWrite in the same run.
void setSettingsFileToRead(const String& filePath)
The filePath is the name (and path if one was used when written) of a previously saved settings file to use when running the Choreo. When the setSettingsFileToRead method is used, any values explicitly provided by calls to any of the set or add methods will supplement or override any settings read from the settings file. For example if you had a settings file that specified a Choreo input (e.g. myChoreo.setInput("Status", "Normal") and issued commands like this...
myChoreo.addInput("Status", "Error");
myChoreo.setSettingsFileToRead("DefaultSettings");
myChoreo.run();
...then the Choreo would be run with the Status input set to Error.
It is an error to use both setSettingsFileToRead and setSettingsFileToWrite in the same run.
In addition to using the setSettingsFileToWrite method in a sketch to create settings files, you can also create them outside of a sketch using any text editor. Settings files are plain text files with concatenated parameter / value pairs, one per line. The parameters and the format for their values are described below in the section titled "Temboo Client Parameters". For example, a settings file containing your Temboo account information would look like this:
-aMyTembooAccount -umyFirstApp -p1234567-abcd-3
Settings files are normally saved without a file extension (e.g. it's usually "settings", not "settings.txt"), but you can use an extension if you like.
As described above, the TembooChoreo class is a thin wrapper around Arduino's Process class, and Process builds up a command line to be executed by the Linino side of the Yún.
The Temboo client is an executable program named temboo that lives on the Linino side of the Yún board. It is called via a TembooChoreo object in an Arduino sketch from the 32U4 side. This program takes various inputs as documented below, formats them in a way that Temboo can understand, and issues a HTTP POST request to run a Choreo. The temboo program takes parameters and values that correspond directly to the methods of the TembooChoreo class as described below.
-aaccountName equivalent to setAccountName("accountName")
-uappKeyName equivalent to setAppKeyName("appKeyName")
-pappKey equivalent to setAppKey("appKey")
-cchoreo equivalent to setChoreo("choreo")
-iname:value equivalent to addInput("name", "value")
-oname:path:variable equivalent to addOutputFilter("name", "path", "variable")
-ecredentialName equivalent to setCredential("credentialName")
-wfilePath equivalent to setSettingsFileToWrite("filePath")
-rfilePath equivalent to setSettingsFileToRead("filePath")
Except for manually creating settings files, there shouldn't ever be a need to know or use these parameters and their value formats. However, if you really wanted to, you could call the temboo client directly with a Process object like this:
Process myProcess;
myProcess.begin("temboo");
myProcess.addParameter("-aMyTembooAccount");
myProcess.addParameter("-umyFirstApp");
myProcess.addParameter("-pa1b2c3d4-e5f6-7890-a");
myProcess.addParameter("-c/Library/Yahoo/Weather/GetWeatherByAddress");
myProcess.addParameter("-iAddress:New York NY, 10013");
myProcess.addParameter("-oHiTemp:/rss/channel/item/yweather:forecast[1]/@high:Response");
unsigned int rc = myProcess.run();
Data is returned from a Choreo execution as items in a simple name-value format. The item name is output first, followed by newline ('\n') and "Unit Separator" ('\x1F') characters. The value follows the name, followed by newline ('\n') and "Record Separator" ('\x1E') characters. For example:
Response\n\x1Fsuccess\n\x1EHTTP_CODE\n\x1F200\n\x1E
The Unit Separator and Record Separator characters are ignored by the Serial monitor, so you can directly print the output using Serial.print(output);. The above example would look like this when printed to the Serial monitor:
Response success HTTP_CODE 200
In most cases, Choreos will have an output named "Response". However, some Choreos (particularly Utilities and OAuth Choreos) return results with different names, so it's always best to check the Library Choreo documentation to see what outputs a Choreo returns.
The output format when using output filters is the same, except that only names and values specified in your output filters and the HTTP_CODE are returned. The raw Choreo output is NOT returned when you use output filters.
If there is an error executing a Choreo, the client will output an item with the name Error followed by a short message describing the problem. Depending on what the error is, the HTTP_CODE may be 000 in cases where the Tembo client failed to contact Temboo.
The TembooChoreo.run() method returns an unsigned int return code. This code can be used to determine whether the call to the temboo client completed successfully or not. Successful completion is always indicated by a return code of zero (0). Unsuccessful executions will return a non-zero return code. The specific value of the return code can help you diagnose what the problem was.
Here is a list of the return codes you might get back from the temboo client.
0: SUCCESS
The request to execute the Choreo was successfully sent to Temboo and the HTTP response code received indicates the Choreo completed successfully.
201: ACCOUNT MISSING
The request was not sent to Temboo because no account name was given. The account name is specified with the setAccountName method or with the -a settings file parameter. Either setAccountName was not called after begin and a settings file did not include a -a parameter, or a -a parameter was found in a settings file but was not followed by the account name.
202: ACCOUNT INVALID
The request was not sent to Temboo because the account name given was not valid. Specifically, this means that there was an illegal character in the account name. Account names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus the dash character (-).
203: CHOREO MISSING
The request was not sent to Temboo because no Choreo name was given. The Choreo name is specified with the setChoreo method or with the -c parameter in a settings file. Either setChoreo was not called after begin and a settings file did not include a -c parameter, or a -c parameter was found in a settings file but was not followed by the Choreo name.
204: CHOREO INVALID
The request was not sent to Temboo because the Choreo name given was not valid. Specifically, this means that there was an illegal character in the Choreo name. Choreo names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
205: APPLICATION KEY NAME MISSING
The request was not sent to Temboo because no Application Key name was given. The Application Key name is specified with the setAppKeyName method or with the -u parameter in a settings file. Either setAppKeyName was not called after begin and a settings file did not include a -u parameter, or a -u was found in a settings file but was not followed by the Application Key name.
206: APPLICATION KEY NAME INVALID
The request was not sent to Temboo because the Application Key name given was not valid. Specifically, this means that there was an illegal character in the Application Key name. Application Key names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
207: APPLICATION KEY MISSING
The request was not sent to Temboo because no Application Key value was given. The Application Key value is specified with the setAppKey method or with the -p parameter in a settings file. Either setAppKey was not called after begin and a settings file did not include a -p parameter, or a -p was found in a settings file but was not followed by the Application Key value.
208: INPUT MISSING
The request was not sent to Temboo because an input parameter was specified without a name:value argument in a settings file. Input parameters are specified with the -i parameter in settings files and must be immediately followed by a name:value pair specifying the name of the input and its corresponding value.
209: INPUT INVALID
The request was not sent to Temboo because an invalid input was detected in a settings file. Choreo inputs are specified with the -i parameter followed immediately by an input name and corresponding value separated by a colon character (:). This return code indicates that a colon character could not be found in the input argument.
210: INPUT NAME INVALID
The request was not sent to Temboo because the name of the input specified was not valid. Specifically, this means that there was an illegal character in the input name. Input names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
211: OUTPUT MISSING
The request was not sent to Temboo because an output filter parameter was specified without a name:path:variable argument in a settings file. Output filter parameters are specified with the -o parameter and must be immediately followed by a name:path:variable triplet.
212: OUTPUT INVALID
The request was not sent to Temboo because an invalid output filter was detected in a settings file. Output filters are specified with the -o parameter followed immediately by an output filter name, path, and variable name, each separated by a colon character (:). This return code indicates that two colon characters could not be found in the output filter argument.
213: OUTPUT NAME INVALID
The request was not sent to Temboo because the name of the output filter specified (i.e. the first element of the name:path:variable triplet in a settings file or the first parameter in a call to the addOutputFilter method) was not valid. Specifically, this means that there was an illegal character in the output name. Output names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
214: OUTPUT VARIABLE NAME INVALID
The request was not sent to Temboo because the variable name in the output filter specified (i.e. the last element of the name:path:variable triplet in a settings file or the last parameter in a call to the addOutputFilter method) was not valid. Specifically, this means that there was an illegal character in the output variable name. Output variable names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
215: READ FILE MISSING
The request was not sent to Temboo because the name of a settings file to be read was not found. This can only happen if using a Process object to directly call the temboo client program. A "read" parameter (-r) must be immediately followed by the name of the settings file to be read. This return code indicates that a -r parameter was found, but was not followed by a settings file name.
216: READ FILE INVALID
The request was not sent to Temboo because the settings file specified with a call to the setSettingsFileToRead method could not be found or could not be read. Make sure the file exists on the Yun file system and is a valid Temboo settings file.
217: WRITE FILE MISSING
The request was not sent to Temboo because the name of a settings file to be written was not found. A "write" parameter (-w) must be immediately followed by the name of the settings file to be written. This return code indicates that a -w parameter was found, but was not followed by a settings file name.
218: WRITE FILE INVALID
The request was not sent to Temboo because the settings file specified in a call to the setSettingsFileToWrite method could not be written. If you're writing a settings file to a USB drive or an SD card, make sure the drive or card is inserted and is not write-protected.
219: READ AND WRITE SPECIFIED
The request was not sent to Temboo because the client was run with both read (setSettingsFileToRead) and write (setSettingsFileToWrite) methods called in the same run. You can specify read or write, but not both in same run.
220: CREDENTIAL MISSING
The request was not sent to Temboo because a credential parameter was specified without a corresponding credential name argument. Credential parameters are specified with the setCredential method or the -e parameter in a settings file and must be immediately followed by a credential name specifying the name of the credential to be used.
221: CREDENTIAL INVALID
The request was not sent to Temboo because the name of the credential specified was not valid. Specifically, this means that there was an illegal character in the credential name. Credential names must start with a lower or upper case letter, a number, or an underscore character. The rest of the name can contain those characters plus any number of '-', '.', '+', and '@' characters.
223: HTTP ERROR
The request was sent to Temboo, but a non-success HTTP return code was received. This return code is used when a response from Temboo contains a HTTP status code that is not in the range of 200 - 299. Any HTTP status code outside of that range indicates the Choreo was not completed successfully. The actual HTTP status code can be obtained from the HTTP_CODE item of the result (which should always be the last item in the response). See the section on HTTP codes below for more information.
Any non-zero code less than 200: CURL ERROR
Requests are sent to Temboo using the cURL utility included with the Linino operating system on the Yún board. If that utility reports an error trying to communicate with Temboo, the Temboo client will return the curl return code indicating what the error was. Please see the official curl documentation for the meanings of curl exit codes.
A call to the temboo program can complete successfully, but there may be a problem at Temboo or the web service a Choreo uses that prevents your Choreo from being executed successfully. The HTTP response code from Temboo can help you diagnose an unsuccessful execution. This value is always returned as the last name-value pair of the output text from a call to TembooChoreo.run(). Successful calls normally have an HTTP response code in the range of 200 to 299.
The official explanations of HTTP status codes can be found here. These definitions at Wikipedia are easier to understand.
A complete call to execute the Yahoo GetWeatherByAddress example would look like this:
TembooChoreo myChoreo;
myChoreo.begin();
myChoreo.setAccountName("MyTembooAccount");
myChoreo.setAppKeyName("myFirstApp");
myChoreo.setAppKey("a1b2c3d4-e5f6-7890-a");
myChoreo.setChoreo("/Library/Yahoo/Weather/GetWeatherByAddress");
myChoreo.addInput("Address", "New York NY, 10013");
myChoreo.addOutputFilter("HiTemp", "/rss/channel/item/yweather:forecast[1]/@high", "Response");
unsigned int rc = myChoreo.run();
The output available for reading from myChoreo would look like this:
HiTemp\n\x1F 91\n\x1E HTTP_CODE\n\x1F 200\n\x1E
and the rc variable would have a value of 0.
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.