Auxiliary functions to the Freescada libmbus library. More...

#include <mbus/mbus.h>
#include <mbus/mbus-protocol.h>
#include <mbus/mbus-serial.h>
#include <mbus/mbus-tcp.h>

Data Structures
struct	_mbus_handle
	Unified MBus handle type encapsulating either Serial or TCP gateway. More...
struct	_mbus_address
	MBus slave address type (primary/secodary address). More...
struct	_mbus_string
	_string type More...
union	_mbus_value
	Quantity value type union. More...
struct	_mbus_record
	Single measured quantity record type. More...
Defines
#define	MBUS_PROBE_NOTHING 0
#define	MBUS_PROBE_SINGLE 1
#define	MBUS_PROBE_COLLISION 2
#define	MBUS_PROBE_ERROR -1
Typedefs
typedef struct _mbus_handle	mbus_handle
	Unified MBus handle type encapsulating either Serial or TCP gateway.
typedef struct _mbus_address	mbus_address
	MBus slave address type (primary/secodary address).
typedef struct _mbus_string	mbus_string
	_string type
typedef union _mbus_value	mbus_value
	Quantity value type union.
typedef struct _mbus_record	mbus_record
	Single measured quantity record type.
Functions
mbus_handle *	mbus_connect_serial (const char *device)
	Connects to serial gateway and initializes MBus handle.
mbus_handle *	mbus_connect_tcp (const char *host, int port)
	Connects to TCP gateway and initializes MBus handle.
int	mbus_disconnect (mbus_handle *handle)
	Disconnects the "unified" handle.
int	mbus_recv_frame (mbus_handle handle, mbus_frame frame)
	Receives a frame using "unified" handle.
int	mbus_send_frame (mbus_handle handle, mbus_frame frame)
	Sends frame using "unified" handle.
int	mbus_send_select_frame (mbus_handle handle, const char secondary_addr_str)
	Sends secodary address selection frame using "unified" handle.
int	mbus_send_data_request_frame (mbus_handle *handle, int address)
	Sends request frame to given slave using "unified" handle.
int	mbus_probe_secondary_address (mbus_handle handle, const char mask, char *matching_addr)
	Probe/address slave by secondary address using "unified" handle.
int	mbus_read_slave (mbus_handle handle, mbus_address address, mbus_frame *reply)
	Read data from given slave using "unified" handle and address types.
mbus_record *	mbus_record_new ()
	Allocate new data record.
void	mbus_record_free (mbus_record *rec)
	Destructor for mbus_record.
mbus_record *	mbus_parse_fixed_record (char statusByte, char medium_unit_byte, u_char *data)
	Create/parse single counter from the fixed data structure.
mbus_record *	mbus_parse_variable_record (mbus_data_record *record)
	Create/parse single counter from the variable data structure record.
int	mbus_data_fixed_normalize (int medium_unit_byte, long medium_value, char *unit_out, double value_out, char **quantity_out)
	Get normalized counter value for a fixed counter.
int	mbus_data_variable_value_decode (mbus_record record, double value_out_real, char *value_out_str, int value_out_str_size)
	Decode value of a variable data structure.
int	mbus_vif_unit_normalize (int vif, double value, char *unit_out, double value_out, char **quantity_out)
	Decode units and normalize value using VIF/VIFE (used internally by mbus_vib_unit_normalize).
int	mbus_vib_unit_normalize (mbus_value_information_block vib, double value, char unit_out, double value_out, char **quantity_out)
	Decode units and normalize value from VIB.
int	mbus_scan_2nd_address_range (mbus_handle handle, int pos, char addr_mask)
	Iterate over secondary addresses, send a probe package to all addresses matching the given addresses mask.

Detailed Description

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"):

 * mbus_handle = mbus_connect_serial(device);
 *   or
 * mbus_handle = mbus_connect_tcp(host, port);
 *
 *  ...
 *
 * 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);
 *

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.)

Define Documentation

#define MBUS_PROBE_COLLISION 2

#define MBUS_PROBE_ERROR -1

#define MBUS_PROBE_NOTHING 0

#define MBUS_PROBE_SINGLE 1

Typedef Documentation

typedef struct _mbus_address mbus_address

MBus slave address type (primary/secodary address).

typedef struct _mbus_handle mbus_handle

Unified MBus handle type encapsulating either Serial or TCP gateway.

typedef struct _mbus_record mbus_record

Single measured quantity record type.

typedef struct _mbus_string mbus_string

_string type

In general support binary strings (octet string, non zero terminated) but so far almost all strings are zero terminated ("texts").

typedef union _mbus_value mbus_value

Quantity value type union.

Function Documentation

mbus_handle* mbus_connect_serial ( const char * device )

Connects to serial gateway and initializes MBus handle.

Parameters:

device

Serial device (like /dev/ttyUSB0 or /dev/ttyS0)

Returns:: Initialized "unified" handler when successful, NULL otherwise;

mbus_handle* mbus_connect_tcp	(	const char *	host,
		int	port
	)

Connects to TCP gateway and initializes MBus handle.

Parameters:

	host	Gateway host
	port	Gateway port

Returns:: Initialized "unified" handler when successful, NULL otherwise;

int mbus_data_fixed_normalize	(	int	medium_unit_byte,
		long	medium_value,
		char **	unit_out,
		double *	value_out,
		char **	quantity_out
	)

Get normalized counter value for a fixed counter.

Get "normalized" value and unit of the counter

Parameters:

	medium_unit_byte	medium/unit byte of the fixed counter
	medium_value	raw counter value
	unit_out	units of the counter - use free when done
	value_out	resulting counter value
	quantity_out	parsed quantity, when done use "free"

Returns:: zero when OK

int mbus_data_variable_value_decode	(	mbus_record *	record,
		double *	value_out_real,
		char **	value_out_str,
		int *	value_out_str_size
	)

Decode value of a variable data structure.

Parameters:

	record	record to be decoded
	value_out_real	numerical counter value output (when numerical)
	value_out_str	string counter value output (when string, NULL otherwise), when finished use "free *value_out_str"
	value_out_str_size	string counter value size

Returns:: zero when OK

int mbus_disconnect ( mbus_handle * handle )

Disconnects the "unified" handle.

Parameters:

handle

Initialized handle

Returns:: Zero when successful.

mbus_record* mbus_parse_fixed_record	(	char	statusByte,
		char	medium_unit_byte,
		u_char *	data
	)

Create/parse single counter from the fixed data structure.

Parameters:

	statusByte	status byte
	medium_unit_byte	medium/unit byte
	data	pointer to the data counter (4 bytes)

Returns:: 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 )

Create/parse single counter from the variable data structure record.

Parameters:

data

record data to be parsed

Returns:: Newly allocated record if succesful, NULL otherwise. Later on need to use mbus_record_free

< raw value

< normalized value

int mbus_probe_secondary_address	(	mbus_handle *	handle,
		const char *	mask,
		char *	matching_addr
	)

Probe/address slave by secondary address using "unified" handle.

Parameters:

	handle	Initialized handle
	mask	Address/mask to probe
	matching_addr	Matched address (the buffer has tobe at least 16 bytes)

Returns:: See MBUS_PROBE_* constants

int mbus_read_slave	(	mbus_handle *	handle,
		mbus_address *	address,
		mbus_frame *	reply
	)

Read data from given slave using "unified" handle and address types.

Parameters:

	handle	Initialized handle
	address	Address of the slave
	reply	Reply from the slave

Returns:: Zero when successful.

void mbus_record_free ( mbus_record * rec )

Destructor for mbus_record.

Parameters:

rec

record to be freed

mbus_record* mbus_record_new ( )

Allocate new data record.

Use mbus_record_free when finished.

Returns:: pointer to the new record, NULL when failed

int mbus_recv_frame	(	mbus_handle *	handle,
		mbus_frame *	frame
	)

Receives a frame using "unified" handle.

Parameters:

	handle	Initialized handle
	frame	Received frame

Returns:: Zero when successful.

int mbus_scan_2nd_address_range	(	mbus_handle *	handle,
		int	pos,
		char *	addr_mask
	)

Iterate over secondary addresses, send a probe package to all addresses matching the given addresses mask.

Parameters:

	pos	current address
	addr_mask	address mask to

Returns:: zero when OK

int mbus_send_data_request_frame	(	mbus_handle *	handle,
		int	address
	)

Sends request frame to given slave using "unified" handle.

Parameters:

	handle	Initialized handle
	address	Address (0-255)

Returns:: Zero when successful.

int mbus_send_frame	(	mbus_handle *	handle,
		mbus_frame *	frame
	)

Sends frame using "unified" handle.

Parameters:

	handle	Initialized handle
	frame	Frame to send

Returns:: Zero when successful.

int mbus_send_select_frame	(	mbus_handle *	handle,
		const char *	secondary_addr_str
	)

Sends secodary address selection frame using "unified" handle.

Parameters:

	handle	Initialized handle
	secondary_addr_str	Secondary address

Returns:: Zero when successful.

int mbus_vib_unit_normalize	(	mbus_value_information_block *	vib,
		double	value,
		char **	unit_out,
		double *	value_out,
		char **	quantity_out
	)

Decode units and normalize value from VIB.

Parameters:

	vib	mbus value information block of the variable record
	value	already parsed "raw" numerical value
	unit_out	parsed unit, when done use "free"
	value_out	normalized value
	quantity_out	parsed quantity, when done use "free"

Returns:: 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 using VIF/VIFE (used internally by mbus_vib_unit_normalize).

Parameters:

	vif	VIF (including standard extensions)
	value	already parsed "raw" numerical value
	unit_out	parsed unit, when done use "free"
	value_out	normalized value
	quantity_out	parsed quantity, when done use "free"

Returns:: zero when OK

mbus/mbus-protocol-aux.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation