Added first chapter to 'Telldus TellStick SDK documentation'

docs/telldus-core.txt

@@ -0,0 +1,143 @@
+/**
+ * @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.
+ *
+ * \subsection sec_bu_listing Listing devices
+ *
+ * To list all of the configured devices, look at the following example:
+ * \code
+ * int intNumberOfDevices = devGetNumberOfDevices();
+ * for (int i = 0; i < intNumberOfDevices; i++) {
+ *   int id = devGetDeviceId( index );
+ *   char *name = devGetName( id );
+ *   printf("%d\t%s\n", id, name);
+ * }
+ * \endcode
+ *
+ * First, we call devGetNumberOfDevices(). 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 devGetDeviceId() 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
+ * devGetName() and then displays it to stdout.
+ *
+ * \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 supports dimming.
+ * To find out what a specific device supports call devMethods():
+ * \code
+ * function checkFeatures( int id ) {
+ *   int methods = devMethods( id );
+ *   if ( methods & TELLSTICK_TURNON ) {
+ *     printf( "The device %d supports devTurnOn()\n", id );
+ *   }
+ *   if ( methods & TELLSTICK_TURNOFF ) {
+ *     printf( "The device %d supports devTurnOff()\n", id );
+ *   }
+ *   if ( methods & TELLSTICK_TURNBELL ) {
+ *     printf( "The device %d supports devBell()\n", id );
+ *   }
+ * }
+ * \endcode
+ * 
+ * When you know which fetures a device supports 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 supports the feature.
+ *
+ * These functions all returns zero if the call was successfull and non-zero
+ * otherwise.
+ *
+ * \paragraph devTurnOn devTurnOn()
+ * Devices supporting \c TELLSTICK_TURNON. Most of the normal switches (for lamp
+ * etc.) supports this.
+ * \paragraph devTurnOff devTurnOff()
+ * Devices supporting \c TELLSTICK_TURNOFF. Almost all of the devices supporting
+ * \c TELLSTICK_TURNON also supports this.
+ * \paragraph devDim devDim()
+ * Devices supporting \c TELLSTICK_DIM. This is a quite unusual feature for
+ * dimmers. Many dimmers on the market that is dimmable has no way for sending
+ * a specific level which means it doesn't support this feature.
+ * \paragraph devBell devBell()
+ * 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
+ * devGetErrorString(). Example:
+ * \code
+ * printf("Error: %s\n", devGetErrorString( TELLSTICK_METHOD_NOT_SUPPORTED ) );
+ * //Error: The method you tried to use is not supported by the device
+ *
+ * int retval = devTurnOn( deviceID );
+ * if (retval != TELLSTICK_SUCCESS ) {
+ *   printf("Error: %s\n", devGetErrorString( 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.
+ */