From ac5f4f25b1dca4a3945f9c857488ab14c2c80f8b Mon Sep 17 00:00:00 2001 From: john30 Date: Sun, 15 Nov 2015 14:42:58 +0100 Subject: [PATCH] extended documentation --- src/lib/ebus/data.h | 43 +++++++++++++++++++++++++++++++++--------- src/lib/ebus/message.h | 25 +++++++++++++++++++++++- src/lib/ebus/result.h | 8 +++++++- src/lib/ebus/symbol.h | 36 ++++++++++++++++++++++++++++++++++- 4 files changed, 100 insertions(+), 12 deletions(-) diff --git a/src/lib/ebus/data.h b/src/lib/ebus/data.h index 28bb23dd..7668e95c 100644 --- a/src/lib/ebus/data.h +++ b/src/lib/ebus/data.h @@ -29,7 +29,32 @@ #include #include -/** \file data.h */ +/** @file data.h + * Classes, functions, and constants related to decoding/encoding of symbols + * on the eBUS to/from readable values. + * + * A @a DataField is either a @a SingleDataField or a list of + * @a SingleDataField instances in a @a DataFieldSet. + * + * A @a SingleDataField is either a string based one or a numeric one. Due to + * their text nature, date and time fields are also treated as + * @a StringDataField. + * + * The basic field types are just @a StringDataField, @a NumberDataField, and + * @a ValueListDataField. The particular eBUS specification types like e.g. + * @a D1C are defined by using one of these basic field types (see #BaseType) + * with certain flags, such as #BCD, #FIX, #REQ, see #dataType_s. + * + * The list of available base types is defined an array of #dataType_s + * structures and can easily be extended if necessary. + * + * Each @a DataField can be converted from a @a SymbolString to an + * @a ostringstream (see @a DataField#read() methods) or vice versa from an + * @a istringstream to a @a SymbolString (see @a DataField#write()). + * + * The @a DataFieldTemplates allow definition of derived types as well as + * combined types based on the list of available base types. + */ using namespace std; @@ -79,18 +104,18 @@ static const unsigned int DAY = 0x20; //!< forced value list defaulting to week static const unsigned int IGN = 0x40; //!< ignore value during read and write static const unsigned int FIX = 0x80; //!< fixed width formatting static const unsigned int REQ = 0x100;//!< value may not be NULL -static const unsigned int HCD = 0x200; //!< binary representation is hex converted to decimal and interpreted as 2 digits (also requires @a BCD) +static const unsigned int HCD = 0x200; //!< binary representation is hex converted to decimal and interpreted as 2 digits (also requires #BCD) -/** The structure for defining field types with their properties. */ -typedef struct { - const char* name; //!< field identifier - const unsigned char bitCount; //!< number of bits (maximum length if @a ADJ flag is set, must be multiple of 8 with flag @a BCD) +/** The structure for defining data types with their properties. */ +typedef struct dataType_s { + const char* name; //!< data type identifier + const unsigned char bitCount; //!< number of bits (maximum length if #ADJ flag is set, must be multiple of 8 with flag #BCD) const BaseType type; //!< base data type - const unsigned short flags; //!< flags (e.g. @a BCD) - const unsigned int replacement; //!< replacement value (fill-up value for @a bt_str / @a bt_hexstr, no replacement if equal to @a minValueOrLength for @a bt_num) + const unsigned short flags; //!< flags (like #BCD) + const unsigned int replacement; //!< replacement value (fill-up value for #bt_str / #bt_hexstr, no replacement if equal to #minValueOrLength for #bt_num) const unsigned int minValueOrLength; //!< minimum binary value (minimum length of string for @a StringDataField) const unsigned int maxValueOrLength; //!< maximum binary value (maximum length of string for @a StringDataField) - const short divisorOrFirstBit; //!< @a bt_number: divisor (negative for reciprocal) or offset to first bit (if (@a bitCount%8)!=0) + const short divisorOrFirstBit; //!< #bt_num: divisor (negative for reciprocal) or offset to first bit (if (#bitCount%8)!=0) } dataType_t; /** the maximum allowed position within master or slave data. */ diff --git a/src/lib/ebus/message.h b/src/lib/ebus/message.h index c39d4ee0..b9942288 100644 --- a/src/lib/ebus/message.h +++ b/src/lib/ebus/message.h @@ -27,7 +27,30 @@ #include #include -/** \file message.h */ +/** @file message.h + * Classes, functions, and constants related to decoding/encoding of complete + * messages on the eBUS to/from readable values. + * + * A @a Message has a unique numeric key (see Message#getKey()) as well as a + * unique name and circuit (@see Message#getCircuit() and Message#getName()). + * The numeric key is built from the message type (active/passive, read/write), + * the source and destination address, the primary and secondary command byte, + * as well as additional command ID bytes (see Message#getId()). + * + * Whenever a @a Message gets decoded from a master and slave @a SymbolString + * (see Message#decode()), it stores these strings for later retrieval from + * cache (see Message#decodeLastData()). + * + * In order to make a @a Message available (see Message#isAvailable()) under + * certain conditions only, it may have assigned a @a Condition instance. + * + * A @a Condition is either a @a SimpleCondition referencing another + * @a Message, field, and field value, or a @a CombinedCondition referencing + * two or more other @a Condition instances. + * + * The @a MessageMap stores all @a Message and @a Condition instances by their + * unique keys, and also keeps track of messages with polling enabled. + */ using namespace std; diff --git a/src/lib/ebus/result.h b/src/lib/ebus/result.h index 0d10faf7..78f51f35 100644 --- a/src/lib/ebus/result.h +++ b/src/lib/ebus/result.h @@ -19,7 +19,13 @@ #ifndef LIBEBUS_RESULT_H_ #define LIBEBUS_RESULT_H_ -/** \file result.h */ +/** @file result.h + * Functions, and constants related to execution results. + * + * The #result_t codes defined here are used by many functions to emit the + * result of the function call. Zero and positive values indicate success, + * whereas negative values indicate failure. + */ /** type for result code. */ enum result_t { diff --git a/src/lib/ebus/symbol.h b/src/lib/ebus/symbol.h index 296cbf87..dfd8abdf 100644 --- a/src/lib/ebus/symbol.h +++ b/src/lib/ebus/symbol.h @@ -25,7 +25,41 @@ #include #include -/** \file symbol.h */ +/** @file symbol.h + * Classes, functions, and constants related to symbols on the eBUS. + * + * The @a SymbolString class is used for escaping or unescaping a sequence of + * bytes in preparation for sending to the bus or after reception of bytes from + * the bus, as well as calculating and verifying the CRC of a message part. + * + * A message on the bus always consists of a command part, i.e. the data sent + * from a master to the bus. The command part starts with the sending master + * address followed by the destination address. Both addresses are not allowed + * to be escaped and whenever a #SYN symbol appears, the sending has to be + * treated as timed out, as only the auto-SYN generator will do so when there + * was no symbol on the bus for a certain period of time. + * + * The remaining bytes of the command part are the primary and secondary + * command byte, the number of data bytes, the data bytes themselves, and the + * final CRC. + * + * When the destination is the #BROADCAST address, then the messages consists + * of the command part only. + * + * When the destination address is a master (see @a isMaster()), the receiving + * master has to acknowledge the correct reception of the command with either + * the #ACK (if the CRC was valid) or the #NAK symbol (if the received CRC did + * not match the calculated one). In case of a non-acknowledge #NAK symbol, the + * command part has to be repeated once (and once only) by the sender. + * + * When the destination address is a slave, the receiving slave has to + * acknowledge the reception of the command as described above. After a + * positive #ACK symbol, the receiving slave has to send its response data. + * The response data consists of the number of data bytes, the data bytes + * themselves, and the final CRC. The sending master has to acknowledge the + * correct reception of the response as described above and in case of a + * non-acknowledge, the receiving slave has to repeat its data once. + */ using namespace std;