wn/libmbus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
libmbus/mbus/mbus-protocol-aux.h
Stefan Wahren f6dcf6e8d1 Fixed naming in declaration 
Signed-off-by: Stefan Wahren <info@lategoodbye.de>
2016-01-31 17:41:08 +00:00

507 lines
15 KiB
C
Executable File
Raw Blame History

//------------------------------------------------------------------------------
// Copyright (C) 2011, Robert Johansson and contributors, Raditex AB
// All rights reserved.
//
// rSCADA
// http://www.rSCADA.se
// info@rscada.se
//
// Contributors:
// Large parts of this file was contributed by Tomas Menzl.
//
//------------------------------------------------------------------------------
/**
* @file mbus-protocol-aux.h
*
* @brief Auxiliary functions to the Freescada libmbus library
*
* The idea is to simplify the basic task of querying MBus slaves and
* the data processing.
* Typical use might be (in oversimplified "pseudocode"):
* \verbatim
* mbus_handle = mbus_context_serial(device);
* or
* mbus_handle = mbus_context_tcp(host, port);
*
* mbus_context_set_option(mbus_handle,option,value); // optional
*
* mbus_connect(mbus_handle);
*
* ...
*
* mbus_read_slave(mbus_handle, addresses, &reply);
* mbus_frame_data_parse(reply, &frameData);
* // check the header / record type (fixed/variable)
*
* // for fixed use mbus_data_fixed_medium and 2x mbus_parse_fixed_record
* mbus_data_fixed_medium
* mbusRecord = mbus_parse_fixed_record() // first record
* // process mbusRecord
* mbusRecord = mbus_parse_fixed_record() // second record
* // process mbusRecord
*
* // for variable use mbus_parse_variable_record
* for each record
* mbusRecord = mbus_parse_variable_record(record)
* // process mbusRecord
*
* ...
*
* mbus_disconnect(mbus_handle);
* mbus_context_free(mbus_handle);
* \endverbatim
*
* Note that the quantity values are partially "normalized". For example energy
* is in Wh even when originally used "decimal" prefixes like MWh. This seems to
* be sensible as it make easier any processing of a dataset with huge
* fluctuation (no need to lookup/convert the prefixes). Also the potential
* conversion to desired units is pretty easy.
*
* On the other hand we acknowledge that use of certain units are expected so we
* do not convert all units to Si (i.e. no conversion from J to Wh or Bar to Pa.)
*/
#ifndef __MBUS_PROTOCOL_AUX_H__
#define __MBUS_PROTOCOL_AUX_H__
#include "mbus-protocol.h"
#ifdef __cplusplus
extern "C" {
#endif
#define MBUS_PROBE_NOTHING 0
#define MBUS_PROBE_SINGLE 1
#define MBUS_PROBE_COLLISION 2
#define MBUS_PROBE_ERROR -1
#define MBUS_FRAME_PURGE_S2M 2
#define MBUS_FRAME_PURGE_M2S 1
#define MBUS_FRAME_PURGE_NONE 0
/**
* Unified MBus handle type encapsulating either Serial or TCP gateway.
*/
typedef struct _mbus_handle {
int fd;
int max_data_retry;
int max_search_retry;
char purge_first_frame;
char is_serial; /**< _handle type (non zero for serial) */
int (*open) (struct _mbus_handle *handle);
int (*close) (struct _mbus_handle *handle);
int (*send) (struct _mbus_handle *handle, mbus_frame *frame);
int (*recv) (struct _mbus_handle *handle, mbus_frame *frame);
void (*free_auxdata) (struct _mbus_handle *handle);
void (*recv_event) (unsigned char src_type, const char *buff, size_t len);
void (*send_event) (unsigned char src_type, const char *buff, size_t len);
void (*scan_progress) (struct _mbus_handle *handle, const char *mask);
void (*found_event) (struct _mbus_handle *handle, mbus_frame *frame);
void *auxdata;
} mbus_handle;
/**
* MBus slave address type (primary/secodary address)
*/
typedef struct _mbus_address {
char is_primary; /**< Address type (non zero for primary) */
union {
int primary; /**< Primary address (for slaves shall be from 1 to 250) */
char * secondary; /**< Secondary address (shall be 16 digits) */
};
} mbus_address;
/**
* _string type
*
* In general support binary strings (octet string, non zero terminated)
* but so far almost all strings are zero terminated ("texts").
*/
typedef struct _mbus_string {
char * value; /**< Buffer */
int size; /**< _size */
} mbus_string;
/**
* Quantity value type union
*/
typedef union _mbus_value {
double real_val; /**< Numerical */
mbus_string str_val; /**< Text/binary */
} mbus_value;
/**
* Single measured quantity record type
*/
typedef struct _mbus_record {
mbus_value value; /**< Quantity value */
char is_numeric; /**< Quantity value type (nonzero is numeric) */
char *unit; /**< Quantity unit (e.g. Wh) */
char *function_medium; /**< Quantity medium or function (e.g. Electricity) */
char *quantity; /**< Quantity type (e.g. Energy) */
int device; /**< Quantity device */
long tariff; /**< Quantity tariff */
long storage_number; /**< Quantity storage number */
} mbus_record;
/**
* MBus handle option enumeration
*/
typedef enum _mbus_context_option {
MBUS_OPTION_MAX_DATA_RETRY, /**< option defines the maximum attempts of data request retransmission */
MBUS_OPTION_MAX_SEARCH_RETRY, /**< option defines the maximum attempts of search request retransmission */
MBUS_OPTION_PURGE_FIRST_FRAME /**< option controls the echo cancelation for mbus_recv_frame */
} mbus_context_option;
/**
* Event register functions
*/
//
// Event register functions
//
void mbus_register_recv_event(mbus_handle *handle, void (*event)(unsigned char src_type, const char *buff, size_t len));
void mbus_register_send_event(mbus_handle *handle, void (*event)(unsigned char src_type, const char *buff, size_t len));
void mbus_register_scan_progress(mbus_handle *handle, void (*event)(mbus_handle *handle, const char *mask));
void mbus_register_found_event(mbus_handle *handle, void (*event)(mbus_handle *handle, mbus_frame *frame));
/**
* Allocate and initialize M-Bus serial context.
*
* @param device Serial device (like /dev/ttyUSB0 or /dev/ttyS0)
*
* @return Initialized "unified" handler when successful, NULL otherwise;
*/
mbus_handle * mbus_context_serial(const char *device);
/**
* Allocate and initialize M-Bus TCP context.
*
* @param host Gateway host
* @param port Gateway port
*
* @return Initialized "unified" handler when successful, NULL otherwise;
*/
mbus_handle * mbus_context_tcp(const char *host, uint16_t port);
/**
* Deallocate memory used by M-Bus context.
*
* @param handle Initialized handle
*
*/
void mbus_context_free(mbus_handle * handle);
/**
* Connect to serial bus or TCP gateway depending on context.
*
* @param handle Initialized handle
*
* @return Zero when successful.
*/
int mbus_connect(mbus_handle * handle);
/**
* Disconnects the "unified" handle.
*
* @param handle Initialized handle
*
* @return Zero when successful.
*/
int mbus_disconnect(mbus_handle * handle);
/**
* Set option of a M-Bus context.
*
* @param handle Initialized handle
* @param option option to set
* @param value value to set
*
* @return Zero when successful.
*/
int mbus_context_set_option(mbus_handle * handle, mbus_context_option option, long value);
/**
* Receives a frame using "unified" handle
*
* @param handle Initialized handle
* @param frame Received frame
*
* @return Zero when successful.
*/
int mbus_recv_frame(mbus_handle * handle, mbus_frame *frame);
/**
* Used for handling collisions. Blocks as long as receiving frames or corrupted data.
*
* @param handle Initialized handle
*
* @return Zero when nothing received, one otherwise.
*/
int mbus_purge_frames(mbus_handle * handle);
/**
* Sends frame using "unified" handle
*
* @param handle Initialized handle
* @param frame Frame to send
*
* @return Zero when successful.
*/
int mbus_send_frame(mbus_handle * handle, mbus_frame *frame);
/**
* Sends secondary address selection frame using "unified" handle
*
* @param handle Initialized handle
* @param secondary_addr_str Secondary address
*
* @return Zero when successful.
*/
int mbus_send_select_frame(mbus_handle * handle, const char *secondary_addr_str);
/**
* Sends application reset to given slave using "unified" handle
*
* @param handle Initialized handle
* @param address Address (0-255)
* @param subcode Subcode (0-255) or no subcode (-1)
*
* @return Zero when successful.
*/
int mbus_send_application_reset_frame(mbus_handle * handle, int address, int subcode);
/**
* Sends switch baudrate frame using "unified" handle
*
* @param handle Initialized handle
* @param address Address (0-255)
* @param baudrate Baudrate (300,600,1200,2400,4800,9600,19200,38400)
*
* @return Zero when successful.
*/
int mbus_send_switch_baudrate_frame(mbus_handle * handle, int address, long baudrate);
/**
* Sends request frame (REQ_UD2) to given slave using "unified" handle
*
* @param handle Initialized handle
* @param address Address (0-255)
*
* @return Zero when successful.
*/
int mbus_send_request_frame(mbus_handle * handle, int address);
/**
* Sends user data frame (SND_UD) to given slave using "unified" handle
*
* @param handle Initialized handle
* @param address Address (0-255)
* @param data User data
* @param data_size Byte count of user data
*
* @return Zero when successful.
*/
int mbus_send_user_data_frame(mbus_handle * handle, int address, const unsigned char *data, size_t data_size);
/**
* Sends a request and read replies until no more records available
* or limit is reached.
*
* @param handle Initialized handle
* @param address Address (0-255)
* @param reply pointer to an mbus frame for the reply
* @param max_frames limit of frames to readout (0 = no limit)
*
* @return Zero when successful.
*/
int mbus_sendrecv_request(mbus_handle *handle, int address, mbus_frame *reply, int max_frames);
/**
* Sends ping frame to given slave using "unified" handle
*
* @param handle Initialized handle
* @param address Address (0-255)
* @param purge_response Response flag (=0 don't receive response, >0 purge response)
*
* @return Zero when successful.
*/
int mbus_send_ping_frame(mbus_handle *handle, int address, char purge_response);
/**
* Select slave by secondary address using "unified" handle
*
* @param handle Initialized handle
* @param mask Address/mask to select
*
* @return See MBUS_PROBE_* constants
*/
int mbus_select_secondary_address(mbus_handle * handle, const char *mask);
/**
* Probe/address slave by secondary address using "unified" handle
*
* @param handle Initialized handle
* @param mask Address/mask to probe
* @param matching_addr Matched address (the buffer has tobe at least 16 bytes)
*
* @return See MBUS_PROBE_* constants
*/
int mbus_probe_secondary_address(mbus_handle * handle, const char *mask, char *matching_addr);
/**
* Read data from given slave using "unified" handle and address types
*
* @param handle Initialized handle
* @param address Address of the slave
* @param reply Reply from the slave
*
* @return Zero when successful.
*/
int mbus_read_slave(mbus_handle *handle, mbus_address *address, mbus_frame *reply);
/**
* Allocate new data record. Use #mbus_record_free when finished.
*
* @return pointer to the new record, NULL when failed
*/
mbus_record * mbus_record_new();
/**
* Destructor for mbus_record
*
* @param rec record to be freed
*/
void mbus_record_free(mbus_record *rec);
/**
* Create/parse single counter from the fixed data structure
*
* @param statusByte status byte
* @param medium_unit_byte medium/unit byte
* @param data pointer to the data counter (4 bytes)
*
* @return Newly allocated record if succesful, NULL otherwise. Later on need to use #mbus_record_free
*/
mbus_record *mbus_parse_fixed_record(char statusByte, char medium_unit_byte, unsigned char *data);
/**
* Create/parse single counter from the variable data structure record
*
* @param record record data to be parsed
*
* @return Newly allocated record if succesful, NULL otherwise. Later on need to use #mbus_record_free
*/
mbus_record * mbus_parse_variable_record(mbus_data_record *record);
/**
* Get normalized counter value for a fixed counter
*
* Get "normalized" value and unit of the counter
*
* @param medium_unit_byte medium/unit byte of the fixed counter
* @param medium_value raw counter value
* @param unit_out units of the counter - use free when done
* @param value_out resulting counter value
* @param quantity_out parsed quantity, when done use "free"
*
* @return zero when OK
*/
int mbus_data_fixed_normalize(int medium_unit_byte, long medium_value, char **unit_out, double *value_out, char **quantity_out);
/**
* Decode value of a variable data structure
*
* @param record record to be decoded
* @param value_out_real numerical counter value output (when numerical)
* @param value_out_str string counter value output (when string, NULL otherwise), when finished use "free *value_out_str"
* @param value_out_str_size string counter value size
*
* @return zero when OK
*/
int mbus_variable_value_decode(mbus_data_record *record, double *value_out_real, char **value_out_str, int *value_out_str_size);
/**
* Decode units and normalize value using VIF/VIFE (used internally by mbus_vib_unit_normalize)
*
* @param vif VIF (including standard extensions)
* @param value already parsed "raw" numerical value
* @param unit_out parsed unit, when done use "free"
* @param value_out normalized value
* @param quantity_out parsed quantity, when done use "free"
*
* @return zero when OK
*/
int mbus_vif_unit_normalize(int vif, double value, char **unit_out, double *value_out, char **quantity_out);
/**
* Decode units and normalize value from VIB
*
* @param vib mbus value information block of the variable record
* @param value already parsed "raw" numerical value
* @param unit_out parsed unit, when done use "free"
* @param value_out normalized value
* @param quantity_out parsed quantity, when done use "free"
*
* @return zero when OK
*/
int mbus_vib_unit_normalize(mbus_value_information_block *vib, double value, char **unit_out, double *value_out, char ** quantity_out);
/**
* Generate XML for normalized variable-length data
*
* @param data variable-length data
*
* @return string with XML
*/
char * mbus_data_variable_xml_normalized(mbus_data_variable *data);
/**
* Return a string containing an XML representation of the normalized M-BUS frame data.
*
* @param data M-Bus frame data
*
* @return string with XML
*/
char * mbus_frame_data_xml_normalized(mbus_frame_data *data);
/**
* Iterate over secondary addresses, send a probe package to all addresses matching
* the given addresses mask.
*
* @param handle Initialized handle
* @param pos current address
* @param addr_mask address mask to
*
* @return zero when OK
*/
int mbus_scan_2nd_address_range(mbus_handle * handle, int pos, char *addr_mask);
/**
* Convert a buffer with hex values into a buffer with binary values.
*
* @param dst destination buffer with binary values
* @param dst_len byte count of destination buffer
* @param src source buffer with hex values
* @param src_len byte count of source buffer
*
* @return byte count of successful converted values
*/
size_t mbus_hex2bin(unsigned char * dst, size_t dst_len, const unsigned char * src, size_t src_len);
#ifdef __cplusplus
}
#endif
#endif // __MBUS_PROTOCOL_AUX_H__
Reference in New Issue View Git Blame Copy Permalink