151 lines
6.2 KiB
Text
151 lines
6.2 KiB
Text
/**
|
|
* @page telldus_core Telldus Core API
|
|
*
|
|
* \section Introduction
|
|
*
|
|
* This is the guide to Telldus TellStick SDK. Even though all examples are
|
|
* written in C/C++ most of the code has an direct eqvivalent function in the
|
|
* other languages. See \ref sec_other_languages how to use the library in one
|
|
* of the supported languages by Telldus.
|
|
*
|
|
* \section Idea
|
|
*
|
|
* All of the devices used by TellStick must be predefined before they can be
|
|
* used in any software. Under all platforms this can be done with the
|
|
* software TelldusSetup but under Linux this can also be done by editing the
|
|
* file <tt>/etc/tellstick.conf</tt> with your favorite text editor.
|
|
*
|
|
* Having the devices preconfigured is an advantage to both the developer and
|
|
* the end user.
|
|
*
|
|
* \li The end user might use more then one program for controling his/hers
|
|
* TellStick. By having the devices preconfigured he/she doesn't have to
|
|
* reconfigure the same devices twice. If some settings changes in one of the
|
|
* devices, this change will affect all softwares using Telldus TellStick SDK.
|
|
* \li Telldus is adding support for new devices constantly. If every software
|
|
* defines it's own devices it will also mean that the developer has to keep
|
|
* it's software up to date with all the new devices and settings Telldus
|
|
* implements. By querying Telldus Tellstick SDK all the new devices will be
|
|
* available automaticly to the end user.
|
|
*
|
|
* \section sec_basic_usage Basic usage (telldus-core)
|
|
*
|
|
* Telldus provides a non-gui library to list, query and control the devices
|
|
* called telldus-core.
|
|
* To initiate the library a call to tdInit() must be made. This call will
|
|
* open up all controllers (e.g. a TellStick) and start listen for events from
|
|
* them.
|
|
* When you are done with telldus-core, call tdClose() to allow the library to
|
|
* clean up after itself.
|
|
*
|
|
* \subsection sec_bu_listing Listing devices
|
|
*
|
|
* To list all of the configured devices, look at the following example:
|
|
* \code
|
|
* int intNumberOfDevices = tdGetNumberOfDevices();
|
|
* for (int i = 0; i < intNumberOfDevices; i++) {
|
|
* int id = tdGetDeviceId( index );
|
|
* char *name = tdGetName( id );
|
|
* printf("%d\t%s\n", id, name);
|
|
* free(name);
|
|
* }
|
|
* \endcode
|
|
*
|
|
* First, we call tdGetNumberOfDevices(). This returnes the total number of
|
|
* devices configured. We then iterate over all of the devices with the index
|
|
* in the variable \c i.
|
|
* Since the devices could change between run of the program we could not be
|
|
* sure that the index points to the same device between two run of the
|
|
* program. That is why every device has an own unique id that is safe to
|
|
* store in a configuration file. Two different devices could never share the
|
|
* same device id.
|
|
*
|
|
* The call to tdGetDeviceId() returns the id for a specific index. This
|
|
* function should only be called in a loop iterating over all of the devices.
|
|
* After we have found the id for a device it is safe to store this or use it
|
|
* the rest of the program.
|
|
*
|
|
* The next two lines of code queries the device for it's name with a call to
|
|
* tdGetName() and then displays it to stdout. Since telldus-core gives up the
|
|
* ownership of the string we must manualy free up the resource after we are
|
|
* done with it.
|
|
*
|
|
* \subsection sec_bu_sending Sending commands to TellStick
|
|
*
|
|
* \subsubsection sec_bu_sending_features Device features
|
|
*
|
|
* TellStick can control many different types of devices and they
|
|
* all support different features. For example, a bell doesn't support turning
|
|
* on and not all lamp switches support dimming.
|
|
* To find out what a specific device support call tdMethods():
|
|
* \code
|
|
* function checkFeatures( int id ) {
|
|
* int methods = tdMethods( id );
|
|
* if ( methods & TELLSTICK_TURNON ) {
|
|
* printf( "The device %d support tdTurnOn()\n", id );
|
|
* }
|
|
* if ( methods & TELLSTICK_TURNOFF ) {
|
|
* printf( "The device %d support tdTurnOff()\n", id );
|
|
* }
|
|
* if ( methods & TELLSTICK_BELL ) {
|
|
* printf( "The device %d support tdBell()\n", id );
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*
|
|
* When you know which fetures a device support it is safe to call the
|
|
* controlling functions described in \ref sec_bu_controlling_functions.
|
|
*
|
|
* \subsubsection sec_bu_controlling_functions Controlling functions
|
|
*
|
|
* TellStick has a couple of functions for controlling the devices. Each of
|
|
* them should only be called if the device support the feature.
|
|
*
|
|
* These functions all returns zero if the call was successfull and non-zero
|
|
* otherwise.
|
|
*
|
|
* \paragraph tdTurnOn tdTurnOn()
|
|
* Devices supporting \c TELLSTICK_TURNON. Most of the normal switches (for lamp
|
|
* etc.) support this.
|
|
* \paragraph tdTurnOff tdTurnOff()
|
|
* Devices supporting \c TELLSTICK_TURNOFF. Almost all of the devices supporting
|
|
* \c TELLSTICK_TURNON also support this.
|
|
* \paragraph tdDim tdDim()
|
|
* Devices supporting \c TELLSTICK_DIM. This is a quite unusual feature for
|
|
* dimmers. Many dimmers on the market that are dimmable have no way for sending
|
|
* a specific level which means it doesn't support this feature.
|
|
* \paragraph tdBell tdBell()
|
|
* Devices supporting \c TELLSTICK_BELL. This is mostly wireless doorbells.
|
|
*
|
|
* \subsubsection sec_bu_error_codes Error codes
|
|
*
|
|
* If any of the calls in \ref sec_bu_controlling_functions fails it returns
|
|
* a non-zero error code. This values is one of the \c TELLSTICK_ERROR_* defines.
|
|
* To translate the error code to a human readable string call the function
|
|
* tdGetErrorString(). Example:
|
|
* \code
|
|
* printf("Error: %s\n", tdGetErrorString( TELLSTICK_METHOD_NOT_SUPPORTED ) );
|
|
* //Error: The method you tried to use is not supported by the device
|
|
*
|
|
* int retval = tdTurnOn( deviceID );
|
|
* if (retval != TELLSTICK_SUCCESS ) {
|
|
* printf("Error: %s\n", tdGetErrorString( retval ) );
|
|
* }
|
|
* \endcode
|
|
*
|
|
* \section sec_other_languages Notes using other languages than C/C++
|
|
*
|
|
* \subsection sec_ol_java Java
|
|
* \subsection sec_ol_net .Net
|
|
* \subsection sec_ol_php PHP
|
|
* \subsection sec_ol_pyhon Python
|
|
*
|
|
* There is no native Python support for TellStick yet. If you are developing in
|
|
* Windows you can load the TellStick ActiveX and then access the Telldus
|
|
* TellStick SDK.
|
|
*
|
|
* \subsection sec_ol_visualbasic Visual Basic
|
|
*
|
|
* Include the file \c TellStick.bas to your project and all of the functions
|
|
* will be available.
|
|
*/
|