Bus access API

Functions to access KNX bus via EIBnetmux. More...

Functions
int	enmx_auth (ENMX_HANDLE handle, char *user, char *password)
	authenticate user
int	enmx_L7_connect (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress)
	connect to remote KNX device
int	enmx_L7_disconnect (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress)
	connect to remote KNX device
int	_enmx_L7Passthrough (sConnectionInfo *pConn, ENMX_ADDRESS knxaddress)
	initialise layer 7/passthrough connection to eibnetmux
int	_enmx_L7State (sConnectionInfo *pConn)
	check layer 7 connection state
int	_enmx_L7GetAckNak (sConnectionInfo *pConn)
	get layer 7 Ack/Nak
int	_enmx_L7Response (sConnectionInfo *pConn, ENMX_ADDRESS knxaddress, unsigned char *buf, int *length, uint8_t tpci, uint16_t apci)
	get and check response to last layer 7 request
int	enmx_L7_readmemory (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress, uint16_t offset, uint16_t length, unsigned char *buf)
	read memory of remote KNX device
int	enmx_L7_writememory (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress, uint16_t offset, uint16_t length, unsigned char *buf)
	write memory of remote KNX device
int	enmx_L7_reset (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress)
	reset remote KNX device
unsigned char *	enmx_monitor (ENMX_HANDLE handle, ENMX_ADDRESS mask, unsigned char *buf, uint16_t *buflen, uint16_t *length)
	monitor group addresses
unsigned char *	enmx_read (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress, uint16_t *length)
	read value from group address
int	enmx_write (ENMX_HANDLE handle, ENMX_ADDRESS knxaddress, uint16_t length, unsigned char *value)
	write value to group address

---

Detailed Description

Functions to access KNX bus via EIBnetmux.

This API supports the following features:

• Reading KNX groups
• Writing KNX groups
• Monitoring KNX groups
• Authentication
• Layer 7 connection-less/connection-oriented functions

---

Function Documentation

int _enmx_L7GetAckNak

(

sConnectionInfo *

pConn

)

get layer 7 Ack/Nak

Parameters:

pConn

pointer to connection structure

Returns:

0: Ack received, 1: NAK received, -1: error

int _enmx_L7Passthrough	(	sConnectionInfo *	pConn,
		ENMX_ADDRESS	knxaddress
	)

initialise layer 7/passthrough connection to eibnetmux

Parameters:

	pConn	pointer to connection structure
	knxaddress	physical address of remote device

Returns:

0: ok, -1: error

int _enmx_L7Response	(	sConnectionInfo *	pConn,
		ENMX_ADDRESS	knxaddress,
		unsigned char *	buf,
		int *	length,
		uint8_t	tpci,
		uint16_t	apci
	)

get and check response to last layer 7 request

Parameters:

	pConn	pointer to connection structure
	knxaddress	physical address of remote device
	buf	pointer to buffer receiving data (tpci, apci, data)
	length	pointer to variable specifying maximum size of data buffer, receives actual length of received data
	tpci	required transport control field setting
	apci	required application control field setting

Returns:

0: ok, -1: error (errorcode set accordingly)

int _enmx_L7State

(

sConnectionInfo *

pConn

)

check layer 7 connection state

Parameters:

pConn

pointer to connection structure

Returns:

0: ok, -1: wrong state

int enmx_auth	(	ENMX_HANDLE	handle,
		char *	user,
		char *	password
	)

authenticate user

eibnetmux supports simple, password-based authentication for its socketserver clients. To authenticate, a client must send username and corresponding password (full, not hashed). To protect against network sniffers, secrets are encrypted before transmission.

To calculate the encryption key, the client initiates the Diffie-Hellman-Merkle key exchange. It receives the corresponding DHM parameters from the server, calculates its own public key and sends it to the server. With this, both parties have enough information to independently and secretly compute a shared session key which is used here only for encryption.

The C library only supports authentication if compiled with authentication support which depends on the availability of the PolarSSL library.

Parameters:

	handle	connection handle as returned by enmx_open()
	user	name of user trying to authenticate
	password	user's password

Returns:

0: ok, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle

Examples:

eibcommand.c, eibread.c, eibstatus.c, eibtrace.c, and layer7.c.

int enmx_L7_connect	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress
	)

connect to remote KNX device

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer

Returns:

0: ok, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle

int enmx_L7_disconnect	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress
	)

connect to remote KNX device

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer

Returns:

0: ok, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle

int enmx_L7_readmemory	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress,
		uint16_t	offset,
		uint16_t	length,
		unsigned char *	buf
	)

read memory of remote KNX device

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer
	offset	start address of memory to read
	length	number of bytes to read
	buf	buffer receiving read bytes

Returns:

>=0: number of bytes read, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle if number of bytes read is less then requested length, there was an error

int enmx_L7_reset	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress
	)

reset remote KNX device

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer

Returns:

=0: ok, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle

int enmx_L7_writememory	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress,
		uint16_t	offset,
		uint16_t	length,
		unsigned char *	buf
	)

write memory of remote KNX device

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer
	offset	start address of memory to read
	length	number of bytes to read
	buf	bytes to write

Returns:

>=0: number of bytes written, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle if number of bytes written is less then requested length, there was an error

unsigned char* enmx_monitor	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	mask,
		unsigned char *	buf,
		uint16_t *	buflen,
		uint16_t *	length
	)

monitor group addresses

Use this function to monitor the activity on the KNX bus. This function is similar to a simple read but returns all requests addressed to a set of KNX logical groups.

For each request, the complete CEMI frame is returned. The caller must understand its format and extract the data according to the addressed group's EIS data type.

ATTENTION: caller has to release returned buffer

Parameters:

	handle	connection handle as returned by enmx_open()
	mask	mask of knx group addresses to monitor (as 16-bit integer)
	buf	buffer which will receive byte stream, enlarged if required
	buflen	pointer to current size of buffer, updated if buffer enlarged
	length	pointer to variable which will receive length of byte stream

Returns:

pointer to received byte stream or NULL upon error (get error code with enmx_geterror)

unsigned char* enmx_read	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress,
		uint16_t *	length
	)

read value from group address

Returned data comes directly from the CEMI frame and must be analysed according to the KNX group's EIS data type.

ATTENTION: caller has to release returned buffer

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer
	length	pointer to variable which will receive length of byte stream

Returns:

pointer to received byte stream or NULL upon error (get error code with enmx_geterror)

int enmx_write	(	ENMX_HANDLE	handle,
		ENMX_ADDRESS	knxaddress,
		uint16_t	length,
		unsigned char *	value
	)

write value to group address

The data is used directly for the TPCI, APCI, and DATA part of the CEMI frame. It must be preformatted accordingly. In particular, the data must correspond to the EIS data type assigned to the addressed KNX group.

Parameters:

	handle	connection handle as returned by enmx_open()
	knxaddress	knx group address as 16-bit integer
	value	byte stream
	length	length of byte stream

Returns:

0: ok, -1: error (get error code with enmx_geterror), ENMX_E_NO_CONNECTION: invalid handle