nils/ebusd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fixed documentation

Browse Source
This commit is contained in:
john30
2014-12-15 20:13:20 +01:00
parent b13e597602
commit 4e81fd842b
18 changed files with 181 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lib/ebus/data.h
+47 -38
View File
@@ -30,57 +30,59 @@
#include <vector>
#include <map>
/** \file data.h */
using namespace std;
/** the separator character used between multiple values (in CSV only). */
/** @brief the separator character used between multiple values (in CSV only). */
#define VALUE_SEPARATOR ';'
/** the separator character used between base type name and length (in CSV only). */
/** @brief the separator character used between base type name and length (in CSV only). */
#define LENGTH_SEPARATOR ':'
/** the replacement string for undefined values (in UI and CSV). */
/** @brief the replacement string for undefined values (in UI and CSV). */
#define NULL_VALUE "-"
/** the separator character used between fields (in UI only). */
/** @brief the separator character used between fields (in UI only). */
#define UI_FIELD_SEPARATOR ';'
/** the message part in which a data field is stored. */
/** @brief the message part in which a data field is stored. */
enum PartType {
pt_any, // stored in any data (master or slave)
pt_masterData, // stored in master data
pt_slaveData, // stored in slave data
pt_any, //!< stored in any data (master or slave)
pt_masterData, //!< stored in master data
pt_slaveData, //!< stored in slave data
};
/** the available base data types. */
/** @brief the available base data types. */
enum BaseType {
bt_str, // text string in a @a StringDataField
bt_hexstr, // hex digit string in a @a StringDataField
bt_dat, // date in a @a StringDataField
bt_tim, // time in a @a StringDataField
bt_num, // numeric value in a @a NumericDataField
bt_str, //!< text string in a @a StringDataField
bt_hexstr, //!< hex digit string in a @a StringDataField
bt_dat, //!< date in a @a StringDataField
bt_tim, //!< time in a @a StringDataField
bt_num, //!< numeric value in a @a NumericDataField
};
/** flags for dataType_t. */
const unsigned int ADJ = 0x01; // adjustable length, numBits is maximum length
const unsigned int BCD = 0x02; // binary representation is BCD
const unsigned int REV = 0x04; // reverted binary representation (most significant byte first)
const unsigned int SIG = 0x08; // signed value
const unsigned int LST = 0x10; // value list is possible (without applied divisor)
const unsigned int DAY = 0x20; // forced value list defaulting to week days
const unsigned int IGN = 0x40; // ignore value during read and write
const unsigned int FIX = 0x80; // fixed width formatting
/* flags for dataType_t. */
static const unsigned int ADJ = 0x01; //!< adjustable length, numBits is maximum length
static const unsigned int BCD = 0x02; //!< binary representation is BCD
static const unsigned int REV = 0x04; //!< reverted binary representation (most significant byte first)
static const unsigned int SIG = 0x08; //!< signed value
static const unsigned int LST = 0x10; //!< value list is possible (without applied divisor)
static const unsigned int DAY = 0x20; //!< forced value list defaulting to week days
static const unsigned int IGN = 0x40; //!< ignore value during read and write
static const unsigned int FIX = 0x80; //!< fixed width formatting
/** the structure for defining field types with their properties. */
/** @brief The structure for defining field types with their properties. */
typedef struct {
const char* name; // field identifier
const unsigned int maxBits; // number of bits (maximum length if @a ADJ flag is set, must be multiple of 8 with flag @a BCD)
const BaseType type; // base data type
const unsigned int 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 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 unsigned int divisor; // @a bt_number: divisor
const unsigned char precisionOrFirstBit; // @a bt_number: precision for formatting or offset to first bit if (@a numBits%8)!=0
const char* name; //!< field identifier
const unsigned int maxBits; //!< number of bits (maximum length if @a ADJ flag is set, must be multiple of 8 with flag @a BCD)
const BaseType type; //!< base data type
const unsigned int 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 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 unsigned int divisor; //!< @a bt_number: divisor
const unsigned char precisionOrFirstBit; //!< @a bt_number: precision for formatting or offset to first bit if (@a numBits%8)!=0
} dataType_t;
@@ -92,6 +94,7 @@ typedef struct {
* @param maxValue the maximum resulting value.
* @param result the variable in which to store an error code when parsing failed or the value is out of bounds.
* @param length the optional variable in which to store the number of read characters.
* @return the parsed value.
*/
unsigned int parseInt(const char* str, int base, const unsigned int minValue, const unsigned int maxValue, result_t& result, unsigned int* length=NULL);
@@ -100,7 +103,9 @@ unsigned int parseInt(const char* str, int base, const unsigned int minValue, co
* @param begin the iterator to the beginning of the items.
* @param end the iterator to the end of the items.
* @param pos the iterator with the erroneous position.
* @param separator the character to place between items.
* @param filename the name of the file being read.
* @param lineNo the current line number in the file being read.
* @param result the result code.
*/
void printErrorPos(vector<string>::iterator begin, const vector<string>::iterator end, vector<string>::iterator pos, string filename, size_t lineNo, result_t result);
@@ -155,6 +160,7 @@ public:
* @param divisor the extra divisor to apply on the value, or 1 for none (if applicable).
* @param values the value=text assignments, or empty to use this fields assignments (if applicable).
* @param fields the @a vector to which created @a SingleDataField instances shall be added.
* @return @a RESULT_OK on success, or an error code.
*/
virtual result_t derive(string name, string comment,
string unit, const PartType partType,
@@ -372,7 +378,7 @@ public:
* @param dataType the data type definition.
* @param partType the message part in which the field is stored.
* @param length the number of symbols in the message part in which the field is stored.
* @param bitCount the number of bits in the binary value.
* @param bitCount the number of bits in the binary value (may be less than @a length * 8).
* @param bitOffset the offset to the first bit in the binary value.
*/
NumericDataField(const string name, const string comment,
@@ -432,6 +438,7 @@ public:
* @param dataType the data type definition.
* @param partType the message part in which the field is stored.
* @param length the number of symbols in the message part in which the field is stored.
* @param bitCount the number of bits in the binary value (may be less than @a length * 8).
* @param divisor the extra divisor to apply on the value, or 1 for none.
*/
NumberDataField(const string name, const string comment,
@@ -483,6 +490,7 @@ public:
* @param dataType the data type definition.
* @param partType the message part in which the field is stored.
* @param length the number of symbols in the message part in which the field is stored.
* @param bitCount the number of bits in the binary value (may be less than @a length * 8).
* @param values the value=text assignments.
*/
ValueListDataField(const string name, const string comment,
@@ -520,7 +528,7 @@ private:
/**
* @brief A set of DataFields.
* @brief A set of @a DataField instances.
*/
class DataFieldSet : public DataField
{
@@ -600,7 +608,7 @@ public:
/**
* @brief Constructs a new instance.
*/
DataFieldTemplates() : FileReader(false) {}
DataFieldTemplates() : FileReader<void*>::FileReader(false) {}
/**
* @brief Destructor.
*/
@@ -616,11 +624,12 @@ public:
* @return @a RESULT_OK on success, or an error code.
* Note: the caller may not free the added instance on success.
*/
result_t add(DataField* message, bool replace=false);
result_t add(DataField* field, bool replace=false);
// @copydoc
virtual result_t addFromFile(vector<string>& row, void* arg, vector< vector<string> >* defaults, const string& filename, unsigned int lineNo);
/**
* @brief Gets the template @a DataField instance with the specified name.
* @param name the name of the template to get.
* @return the template @a DataField instance, or NULL.
* Note: the caller may not free the returned instance.
*/
src/lib/ebus/filereader.h
+12 -7
View File
@@ -29,13 +29,14 @@
#include <vector>
#include <map>
/** \file filereader.h */
using namespace std;
/** the separator character used between fields. */
/** @brief the separator character used between fields. */
#define FIELD_SEPARATOR ','
/** the separator character used to quote text having the @a FIELD_SEPARATOR in it. */
/** @brief the separator character used to quote text having the @a FIELD_SEPARATOR in it. */
#define TEXT_SEPARATOR '"'
@@ -48,7 +49,7 @@ class FileReader
public:
/**
* @brief Constructs a new instance.
* @brief Construct a new instance.
*/
FileReader(bool supportsDefaults)
: m_supportsDefaults(supportsDefaults) {}
@@ -59,8 +60,9 @@ public:
virtual ~FileReader() {}
/**
* @brief Reads the definitions from a file.
* @param filename the name (and path) of the file to read.
* @brief Read the definitions from a file.
* @param filename the name of the file being read.
* @param arg an argument to pass to @a addFromFile().
* @return @a RESULT_OK on success, or an error code.
*/
virtual result_t readFromFile(const string filename, T arg=NULL)
@@ -146,9 +148,12 @@ public:
}
/**
* @brief Adds a definition that was read from a file.
* @brief Add a definition that was read from a file.
* @param row the definition row read from the file.
* @param arg the argument passed to @a readFromFile().
* @param defaults all previously read default rows (initial star char removed), or NULL if not supported.
* @param filename the name of the file being read.
* @param lineNo the current line number in the file being read.
* @return @a RESULT_OK on success, or an error code.
*/
virtual result_t addFromFile(vector<string>& row, T arg, vector< vector<string> >* defaults, const string& filename, unsigned int lineNo) = 0;
src/lib/ebus/message.h
+14 -6
View File
@@ -28,6 +28,8 @@
#include <deque>
#include <map>
/** \file message.h */
using namespace std;
class MessageMap;
@@ -42,7 +44,7 @@ public:
/**
* @brief Construct a new instance.
* @param class the optional device class.
* @param clazz the optional device class.
* @param name the message name (unique within the same class and type).
* @param isSet whether this is a set message.
* @param isPassive true if message can only be initiated by a participant other than us,
@@ -158,7 +160,7 @@ public:
* @param slaveData the slave data @a SymbolString for writing symbols to.
* @return @a RESULT_OK on success, or an error code.
*/
result_t prepareSlave(SymbolString& masterData);
result_t prepareSlave(SymbolString& slaveData);
/**
* @brief Decode a received message.
@@ -240,9 +242,15 @@ private:
/**
* @brief A function that compares the poll priority of two @a Message instances.
* @brief A function that compares the weighted poll priority of two @a Message instances.
*/
struct compareMessagePriority : binary_function <Message*,Message*,bool> {
/**
* @brief Compare the weighted poll priority of the two @a Message instances.
* @param x the first @a Message.
* @param y the second @a Message.
* @return whether @a x is bigger than or equal to @a y with regard to their weighted poll priority.
*/
bool operator() (Message* x, Message* y) const { return x->isLessPollWeight(y) == false; };
};
@@ -257,7 +265,7 @@ public:
/**
* @brief Construct a new instance.
*/
MessageMap() : FileReader(true), m_minIdLength(4), m_maxIdLength(0), m_messageCount(0) {}
MessageMap() : FileReader<DataFieldTemplates*>::FileReader(true), m_minIdLength(4), m_maxIdLength(0), m_messageCount(0) {}
/**
* @brief Destructor.
*/
@@ -273,7 +281,7 @@ public:
virtual result_t addFromFile(vector<string>& row, DataFieldTemplates* arg, vector< vector<string> >* defaults, const string& filename, unsigned int lineNo);
/**
* @brief Find the @a Message instance for the specified class and name.
* @param class the optional device class.
* @param clazz the optional device class.
* @param name the message name.
* @param isSet whether this is a set message.
* @param isPassive whether this is a passive message.
@@ -283,7 +291,7 @@ public:
Message* find(const string& clazz, const string& name, const bool isSet, const bool isPassive=false);
/**
* @brief Find all active get @a Message instances for the specified class and name.
* @param class the device class, or empty for any.
* @param clazz the device class, or empty for any.
* @param name the message name, or empty for any.
* @param pb the primary ID byte, or -1 for any.
* @return the found @a Message instances.
src/lib/ebus/port.h
+9 -20
View File
@@ -32,16 +32,16 @@ using namespace std;
/** \file port.h */
/** available device types. */
/** @brief available device types. */
enum DeviceType {
dt_serial, /*!< serial device */
dt_network /*!< network device */
};
/** max bytes write to bus. */
/** @brief max bytes write to bus. */
#define MAX_WRITE_SIZE 1
/** max size of receive buffer. */
/** @brief max size of receive buffer. */
#define MAX_READ_SIZE 100
@@ -66,6 +66,7 @@ public:
* @brief virtual open function for opening file descriptor
* @param deviceName to determine device type.
* @param noDeviceCheck en-/disable device check.
* @return the @a result_t code.
*/
virtual result_t openDevice(const string deviceName, const bool noDeviceCheck) = 0;
@@ -146,16 +147,10 @@ public:
*/
~DeviceSerial() { closeDevice(); }
/**
* @brief open function for opening file descriptor
* @param deviceName to determine device type.
* @param noDeviceCheck en-/disable device check.
*/
// @copydoc
virtual result_t openDevice(const string deviceName, const bool noDeviceCheck);
/**
* @brief close function for closing opened file descriptor
*/
// @copydoc
void closeDevice();
private:
@@ -176,16 +171,10 @@ public:
*/
~DeviceNetwork() { closeDevice(); }
/**
* @brief open function for opening file descriptor
* @param deviceName to determine device type.
* @param noDeviceCheck en-/disable device check.
*/
// @copydoc
virtual result_t openDevice(const string deviceName, const bool noDeviceCheck);
/**
* @brief close opened file descriptor
*/
// @copydoc
void closeDevice();
private:
@@ -271,7 +260,7 @@ public:
/**
* @brief Enable or disable logging of raw data.
* @param logRawData true to enable logging of raw data, false to disable it.
* @param logRaw true to enable logging of raw data, false to disable it.
*/
void setLogRaw(bool logRaw=true) { m_logRaw = logRaw; }
src/lib/ebus/result.h
+26 -24
View File
@@ -20,34 +20,36 @@
#ifndef LIBEBUS_RESULT_H_
#define LIBEBUS_RESULT_H_
static const int RESULT_OK = 0; // success
/** \file result.h */
static const int RESULT_IN_ESC = 1; // start of escape sequence received
static const int RESULT_SYN = 2; // regular SYN after message received
static const int RESULT_EMPTY = 3; // empty result
static const int RESULT_OK = 0; //!< success
static const int RESULT_ERR_GENERIC_IO = -1; // generic I/O error (usually fatal)
static const int RESULT_ERR_DEVICE = -2; // generic device error (usually fatal)
static const int RESULT_ERR_SEND = -3; // send error
static const int RESULT_ERR_ESC = -4; // invalid escape sequence
static const int RESULT_ERR_TIMEOUT = -5; // read timeout
static const int RESULT_IN_ESC = 1; //!< start of escape sequence received
static const int RESULT_SYN = 2; //!< regular SYN after message received
static const int RESULT_EMPTY = 3; //!< empty result
static const int RESULT_ERR_NOTFOUND = -6; // file/element not found or not readable
static const int RESULT_ERR_EOF = -7; // end of input reached
static const int RESULT_ERR_INVALID_ARG = -8; // invalid argument
static const int RESULT_ERR_INVALID_NUM = -9; // invalid numeric argument
static const int RESULT_ERR_INVALID_ADDR = -10; // invalid address
static const int RESULT_ERR_INVALID_POS = -11; // invalid position
static const int RESULT_ERR_OUT_OF_RANGE = -12; // argument value out of valid range
static const int RESULT_ERR_INVALID_PART = -13; // invalid part type value
static const int RESULT_ERR_MISSING_TYPE = -14; // missing data type
static const int RESULT_ERR_INVALID_LIST = -15; // invalid value list
static const int RESULT_ERR_DUPLICATE = -16; // duplicate entry
static const int RESULT_ERR_GENERIC_IO = -1; //!< generic I/O error (usually fatal)
static const int RESULT_ERR_DEVICE = -2; //!< generic device error (usually fatal)
static const int RESULT_ERR_SEND = -3; //!< send error
static const int RESULT_ERR_ESC = -4; //!< invalid escape sequence
static const int RESULT_ERR_TIMEOUT = -5; //!< read timeout
static const int RESULT_ERR_BUS_LOST = -17; // arbitration lost
static const int RESULT_ERR_CRC = -18; // CRC error
static const int RESULT_ERR_ACK = -19; // ACK error
static const int RESULT_ERR_NAK = -20; // NAK received
static const int RESULT_ERR_NOTFOUND = -6; //!< file/element not found or not readable
static const int RESULT_ERR_EOF = -7; //!< end of input reached
static const int RESULT_ERR_INVALID_ARG = -8; //!< invalid argument
static const int RESULT_ERR_INVALID_NUM = -9; //!< invalid numeric argument
static const int RESULT_ERR_INVALID_ADDR = -10; //!< invalid address
static const int RESULT_ERR_INVALID_POS = -11; //!< invalid position
static const int RESULT_ERR_OUT_OF_RANGE = -12; //!< argument value out of valid range
static const int RESULT_ERR_INVALID_PART = -13; //!< invalid part type value
static const int RESULT_ERR_MISSING_TYPE = -14; //!< missing data type
static const int RESULT_ERR_INVALID_LIST = -15; //!< invalid value list
static const int RESULT_ERR_DUPLICATE = -16; //!< duplicate entry
static const int RESULT_ERR_BUS_LOST = -17; //!< arbitration lost
static const int RESULT_ERR_CRC = -18; //!< CRC error
static const int RESULT_ERR_ACK = -19; //!< ACK error
static const int RESULT_ERR_NAK = -20; //!< NAK received
/** type for result code. */
typedef int result_t;
src/lib/ebus/symbol.h
+10 -6
View File
@@ -26,13 +26,15 @@
#include <sstream>
#include <queue>
/** \file symbol.h */
using namespace std;
static const unsigned char ESC = 0xA9; // escape symbol, either followed by 0x00 for the value 0xA9, or 0x01 for the value 0xAA
static const unsigned char SYN = 0xAA; // synchronization symbol
static const unsigned char ACK = 0x00; // positive acknowledge
static const unsigned char NAK = 0xFF; // negative acknowledge
static const unsigned char BROADCAST = 0xFE; // the broadcast destination address
static const unsigned char ESC = 0xA9; //!< escape symbol, either followed by 0x00 for the value 0xA9, or 0x01 for the value 0xAA
static const unsigned char SYN = 0xAA; //!< synchronization symbol
static const unsigned char ACK = 0x00; //!< positive acknowledge
static const unsigned char NAK = 0xFF; //!< negative acknowledge
static const unsigned char BROADCAST = 0xFE; //!< the broadcast destination address
/**
@@ -54,6 +56,8 @@ public:
/**
* @brief Creates a new escaped or unescaped instance from another @a SymbolString and adds the calculated CRC.
* @param str the @a SymbolString top copy from.
* @param escape true for an escaped instance, false for an unescaped instance.
* @param addCrc whether to add the calculated CRC as last symbol.
*/
SymbolString(const SymbolString& str, const bool escape, const bool addCrc=true);
/**
@@ -103,7 +107,7 @@ public:
* @brief Appends a the symbol to the end of the symbol string and escapes/unescapes it if necessary.
* @param value the symbol to append.
* @param isEscaped whether the symbol is escaped.
* @param updateCrc whether to update the calculated CRC in @a m_crc.
* @param updateCRC whether to update the calculated CRC in @a m_crc.
* @return RESULT_OK if another symbol was appended,
* RESULT_IN_ESC if this is an unescaped instance and the symbol is escaped and the start of the escape sequence was received,
* RESULT_ERR_ESC if this is an unescaped instance and an invalid escaped sequence was detected.