Merge pull request #37 from kopp/feature/document-api

document API via doxygen

README.md

@@ -8,6 +8,8 @@ The library will control the last CRC value to check if the received data is cor
 
 It's actively maintained and has already been used in various projects with meters from EMH, EFR, EasyMeter, etc.
 
+The API is described in [`sml.h`](src/sml.h) via doxygen comments.
+
 ## Examples
 
 | Directory                                              | Description                                                    |

src/sml.h

@@ -1,6 +1,19 @@
 #ifndef SML_H
 #define SML_H
 
+/*!
+ * \file Parse and interpret an SML (Smart Message Language) message.
+ *
+ * The library uses shared static memory to store the parsed SML message.
+ * Use \ref smlState to parse the message byte by byte.
+ * This will store the parsed data in static memory.
+ * To access values, check whether the OBIS code you are interested in has just
+ * been parsed via \ref smlOBISCheck and if so, parse that value using \ref
+ * smlOBISByUnit to get the data in full precision or one of the convenience
+ * functions like \ref smlOBISW to get the data directly as double in the
+ * specified unit.
+ */
+
 #include <stdbool.h>
 
 typedef enum {
@@ -92,18 +105,59 @@ typedef enum {
   SML_COUNT = 255
 } sml_units_t;
 
+/*! Parse a single byte of an SML message and return the status after parsing
+ * that. */
 sml_states_t smlState(unsigned char &byte);
+
+/* ! Return whether the 6-character OBIS identifier (binary encoded) matches to
+ * the last received message.
+ * If it does, use one of the specific functions to retrieve the value.
+ *
+ * Calling this function makes sense after a list was received and parsed, i.e.
+ * after the state was \ref SML_LISTEND .
+ *
+ * OBIS (Object Identification System) identifies the kind of message that was
+ * received in the format `A-B:C.D.E*F`, the encoding in \p obis is
+ * an array `{A, B, C, D, E, F}`.
+ * For example `{0x01, 0x00, 0x01, 0x08, 0x01, 0xff}` encodes `1-0:1.8.1*255`,
+ which is the electric meter reading.
+ * If the message matches this particular OBIS identifier, we know that a meter
+ reading in Wh (Watt hours) was received and we can then read it using \ref
+ smlOBISWh.
+ */
 bool smlOBISCheck(const unsigned char *obis);
+
+/*! Copy the first \p maxSize bytes of the name/identifier of the manufacturer
+ * into buffer \p str. Use this after reading OBIS code `{0x81, 0x81, 0xc7,
+ * 0x82, 0x03, 0xff}` i.e. 129-129:199.130.3*255.
+ */
 void smlOBISManufacturer(unsigned char *str, int maxSize);
-void smlOBISByUnit(long long int &wh, signed char &scaler, sml_units_t unit);
+
+/*! Copy the value last read into \p val and the read scaler into \p scaler and
+ * ensure that it has unit \p unit . If the unit was assumed wrongly, set \p val
+ * to -1.
+ * The final value is `val x 10^scaler`.
+ *
+ * There are 'convenience' functions that wrap this function to return the
+ * actual value as double, see below.
+ *
+ * \return nothing, but set \p val to -1 in case of an error.
+ */
+void smlOBISByUnit(long long int &val, signed char &scaler, sml_units_t unit);
 
 // Be aware that double on Arduino UNO is just 32 bit
+
+/*! Convenience function to get a reading in Watt hours.*/
 void smlOBISWh(double &wh);
+/*! Convenience function to get a reading in Watts.*/
 void smlOBISW(double &w);
+/*! Convenience function to get a reading in Volts.*/
 void smlOBISVolt(double &v);
+/*! Convenience function to get a reading in Amperes.*/
 void smlOBISAmpere(double &a);
+/*! Convenience function to get a reading in Hertz.*/
 void smlOBISHertz(double &h);
+/*! Convenience function to get a reading in Degrees.*/
 void smlOBISDegree(double &d);
 
-
 #endif