Changeset 290a80

Timestamp:

10/28/11 15:41:28 (19 months ago)

Author:

Micke Prag <micke.prag@…>

Branches:

('master', '033cf796174446f5fff5bbfad1cbf1e4af35c0d8')('controller-upgrade', '72b31cc86eeeef18f1371a3067b6e8a5ca21abfc')('windows_service_fixes', 'df6bd2788365991d36d5af2a75833b8de2a5860f')

Children:

4b37109f279b3517d8d152423aa0b8d6245954b7

Parents:

f207af7462b3b50299c33c8d76d6045061bd4455

git-author:

Micke Prag <micke.prag@telldus.se>2011-10-27 11:12:51+02:00

git-committer:

Micke Prag <micke.prag@telldus.se>2011-10-28 15:41:28+02:00

Message:

Added documentation for sensors, this closes #110.

File:

• docs/telldus-core.dox (modified) (4 diffs)

docs/telldus-core.dox

@@ -188 +188 @@
  * \endcode
  *
+ * \subsection sec_bu_sensors Sensors
+ *
+ * Retrieving sensor values can be done in two ways. Either by a polling
+ * interface or by callbacks. The client application can implement one or both
+ * of these interfaces. For callbacks, read more under \ref sec_events.
+ *
+ * Each of the sensors can have one or several value types. Currently only
+ * temperature and humidity are implemented.
+ *
+ * There is no API to add, remove or edit sensors. Each sensor that
+ * TellStick Duo has got any data from is added to an internal list. It is up to
+ * the client application to filter and only show the sensors your are
+ * interested in.
+ *
+ * To iterate over the list of sensors, call tdSensor() repeatedly as long as it
+ * returns \c TELLSTICK_SUCCESS. The parameters \c protocol, \c model,
+ * \c sensorId, and \c dataTypes are sent by reference and will be filled with
+ * the values.
+ *
+ * Example:
+ * \code
+ * char protocol[DATA_LENGTH], model[DATA_LENGTH];
+ * int sensorId = 0, dataTypes = 0;
+ * while(tdSensor(protocol, DATA_LENGTH, model, DATA_LENGTH, &sensorId, &dataTypes) == TELLSTICK_SUCCESS) {
+ *   //Print the sensor
+ *   printf("%s,\t%s,\t%i\n", protocol, model, sensorId);
+ * }
+ * \endcode
+ *
+ * The type of sensor values the sensor supports are stored as flags in the
+ * parameter \c sensorId. Call tdSensorValue() for each type.
+ *
+ * Example:
+ * \code
+ * char value[DATA_LENGTH];
+ * char timeBuf[80];
+ * time_t timestamp = 0;
+ * if (dataTypes & TELLSTICK_TEMPERATURE) {
+ *   tdSensorValue(protocol, model, sensorId, TELLSTICK_TEMPERATURE, value, DATA_LENGTH, (int *)&timestamp);
+ *   strftime(timeBuf, sizeof(timeBuf), "%Y-%m-%d %H:%M:%S", localtime(&timestamp));
+ *   printf("Temperature:\t%sº\t(%s)\n", value, timeBuf);
+ * }
+ * \endcode
+ *
  * \section sec_events Events
  *
- * To get events from either a TellStick Duo or if another software changes the
- * status of a device you have to register for a callback.
+ * To get events from either a TellStick Duo, another software changes the
+ * status of a device, or new sensors values you have to register for a callback.
  *
  * \subsection sec_events_registering Registering for callbacks
@@ -199 +243 @@
  * \li tdRegisterDeviceChangeEvent()
  * \li tdRegisterRawDeviceEvent()
+ * \li tdRegisterSensorEvent()
  *
  * These all work in the same way. The first parameter is a function-pointer to
@@ -220 +265 @@
  * \subsection sec_events_callbacks Callbacks
  *
- * telldus-core currently implements three different callback function for
+ * telldus-core currently implements four different callback function for
  * different purposes.
  *
@@ -273 +318 @@
  * - void *context - see \ref sec_events_registering for description
  *
+ * \subsubsection sec_events_callbacks_sensorevent SensorEvent
+ *
+ * This event is fired when a new sensor value is retrieved.
+ *
+ * Parameters:
+ * - const char *protocol - The sensors protocol
+ * - const char *model - The model of the sensor
+ * - int id - The unique id for the sensor.
+ * - int dataType - Flags for which types of data the sensor supports
+ * - const char *value - A human readable string of the data
+ * - int timestamp - The timestamp when the latest value was received
+ * - int callbackId - id of callback
+ * - void *context - See \ref sec_events_registering for description
+ *
  * \subsection sec_events_example Example
  *