tuwien.auto.calimero.mgmt
Interface ManagementClient

All Known Implementing Classes:

ManagementClientImpl

public interface ManagementClient

Application layer services providing management related tasks in a KNX network for a client.

Method Summary

byte	authorize(Destination dst, byte[] key) Authorizes at a communication partner using an authorization key to obtain a certain access level.
Destination	createDestination(IndividualAddress remote, boolean connectionOriented) Creates a new destination using the remote KNX address for management communication.
Destination	createDestination(IndividualAddress remote, boolean connectionOriented, boolean keepAlive, boolean verifyMode) Creates a new destination using the remote KNX address and connection settings for management communication.
KNXNetworkLink	detach() Detaches the network link from this management client.
Priority	getPriority() Returns the current used KNX message priority for KNX messages.
int	getResponseTimeout() Returns the response timeout used when waiting for a KNX response message to arrive.
boolean	isOpen() Returns whether a network link is attached to this management client.
int	readADC(Destination dst, int channelNr, int repeat) Reads the value of the A/D converter of a communication partner.
IndividualAddress[]	readAddress(boolean oneAddressOnly) Reads the individual address of a communication partner in the KNX network.
IndividualAddress	readAddress(byte[] serialNo) Reads the individual address of a communication partner identified using an unique serial number in the KNX network.
byte[]	readDeviceDesc(Destination dst, int descType) Reads the device descriptor information of a communication partner its controller.
java.util.List	readDomainAddress(boolean oneAddressOnly) Reads the domain address of a communication partner in the KNX network.
java.util.List	readDomainAddress(byte[] domain, IndividualAddress startAddress, int range) Reads the domain address of a communication partner identified using an address range.
byte[]	readMemory(Destination dst, int startAddr, int bytes) Reads memory data from the address space of a communication partner its controller.
byte[]	readProperty(Destination dst, int objIndex, int propID, int start, int elements) Reads the value of a property of an interface object of a communication partner.
byte[]	readPropertyDesc(Destination dst, int objIndex, int propID, int propIndex) Reads the description of a property of an interface object of a communication partner.
void	restart(Destination dst) Initiates a reset of the controller of a communication partner.
void	setPriority(Priority p) Sets the KNX message priority for KNX messages to send.
void	setResponseTimeout(int timeout) Sets the response timeout to wait for a KNX response message to arrive to complete a message exchange.
void	writeAddress(byte[] serialNo, IndividualAddress newAddress) Modifies the individual address of a communication partner identified using an unique serial number in the KNX network.
void	writeAddress(IndividualAddress newAddress) Modifies the individual address of a communication partner in the KNX network.
void	writeDomainAddress(byte[] domain) Modifies the domain address of a communication partner in the KNX network.
void	writeKey(Destination dst, int level, byte[] key) Modifies or deletes an authorization key associated to an access level of a communication partner.
void	writeMemory(Destination dst, int startAddr, byte[] data) Writes memory data in the address space of a communication partner its controller.
void	writeProperty(Destination dst, int objIndex, int propID, int start, int elements, byte[] data) Modifies the value of a property of an interface object of a communication partner.

Method Detail

authorize

byte authorize(Destination dst,
               byte[] key)
               throws KNXException

Authorizes at a communication partner using an authorization key to obtain a certain access level.

This service uses point-to-point connection-oriented communication mode.
The returned access level is between 0 (maximum access rights) and 3 (i.e. minimum access rights) or 0 (maximum access rights) and 15 (minimum access rights).
If no authorization is done at all or the supplied key is not valid, the default access level used is set to minimum. A set access level is valid until disconnected from the partner or a new authorization request is done.

Parameters:

dst - destination at which to authorize

key - byte array containing authorization key

Returns:

the granted access level

Throws:

KNXTimeoutException - on a timeout during send

KNXInvalidResponseException - if the received access level is out of the allowed value range

KNXDisconnectException - on disconnect during authorize

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other authorization error

createDestination

Destination createDestination(IndividualAddress remote,
                              boolean connectionOriented)

Creates a new destination using the remote KNX address for management communication.

A management client will use the transport layer for creating the destination.

Parameters:

remote - destination KNX individual address

connectionOriented - true for connection oriented mode, false for connectionless mode

Returns:

destination representing the logical connection

createDestination

Destination createDestination(IndividualAddress remote,
                              boolean connectionOriented,
                              boolean keepAlive,
                              boolean verifyMode)

Creates a new destination using the remote KNX address and connection settings for management communication.

A management client will use the transport layer for creating the destination.

Parameters:

remote - destination KNX individual address

connectionOriented - true for connection oriented mode, false for connectionless mode

keepAlive - true to prevent a timing out of the logical connection in connection oriented mode, false to use default connection timeout

verifyMode - true to indicate the destination has verify mode enabled, false otherwise

Returns:

destination representing the logical connection

detach

KNXNetworkLink detach()

Detaches the network link from this management client.

A detach will also detach an internally used transport layer with all its consequences. If no network link is attached, no action is performed.

Note that a detach does not trigger a close of the used network link.

Returns:

the formerly attached KNX network link, or null if already detached

See Also:

TransportLayer.detach()

getPriority

Priority getPriority()

Returns the current used KNX message priority for KNX messages.

Returns:

message Priority

getResponseTimeout

int getResponseTimeout()

Returns the response timeout used when waiting for a KNX response message to arrive.

Returns:

timeout in seconds

isOpen

boolean isOpen()

Returns whether a network link is attached to this management client.

Returns:

true if link attached, false if detached

readADC

int readADC(Destination dst,
            int channelNr,
            int repeat)
            throws KNXException

Reads the value of the A/D converter of a communication partner.

This service uses point-to-point connection-oriented communication mode.

Parameters:

dst - destination to read from

channelNr - channel number of the A/D converter

repeat - number of consecutive converter read operations

Returns:

the calculated A/D conversion value

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - on remote converter read problem (e.g. overflow or wrong channel)

KNXDisconnectException - on disconnect during read

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read A/D converter error

readAddress

IndividualAddress[] readAddress(boolean oneAddressOnly)
                                throws KNXException

Reads the individual address of a communication partner in the KNX network.

This service uses broadcast communication mode.
The communication partner is a device in programming mode. In situations necessary to know whether more than one device is in programming mode, oneAddressOnly is set to false and the device addresses are listed in the returned address array. In this case, the whole response timeout is waited for read responses. If oneAddressOnly is true, the array size of returned addresses is 1, and the method returns after receiving the first read response.

Parameters:

oneAddressOnly - true if method should return after receiving the first read response, false to wait the whole response timeout for read responses

Returns:

array of individual addresses, in the order of reception

Throws:

KNXTimeoutException - on a timeout during send or no address response was received

KNXInvalidResponseException - on invalid read response message

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read address errors

readAddress

IndividualAddress readAddress(byte[] serialNo)
                              throws KNXException

Reads the individual address of a communication partner identified using an unique serial number in the KNX network.

This service uses broadcast communication mode.

Parameters:

serialNo - byte array with serial number, serialNo.length = 6

Returns:

the individual address

Throws:

KNXTimeoutException - on a timeout during send or no address response was received

KNXInvalidResponseException - on invalid read response message

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read address errors

readDeviceDesc

byte[] readDeviceDesc(Destination dst,
                      int descType)
                      throws KNXException

Reads the device descriptor information of a communication partner its controller.

This service uses point-to-point connectionless or connection-oriented communication mode.

The returned descriptor information format for device descriptor type 0 is as follows (MSB to LSB):
| mask type (8 bit) | firmware version (8 bit) |
with the mask type split up into
| Medium Type (4 bit) | Firmware Type (4 bit)|
and the firmware version split up into
| version (4 bit) | sub code (4 bit) |

The returned descriptor information format for device descriptor type 2 is as follows (MSB to LSB):
| application manufacturer (16 bit) | device type (16 bit) | version (8 bit) | misc. (2 bit) + LT base (6 bit) | CI 1 (16 bit) | CI 2 (16 bit) | CI 3 (16 bit) | CI 4 (16 bit) |
with CI = channel info

Parameters:

dst - destination to read from

descType - device descriptor type, 0 for type 0 or 2 for type 2

Returns:

byte array containing device descriptor information

Throws:

KNXTimeoutException - on a timeout during send

KNXInvalidResponseException - on invalid read response message

KNXDisconnectException - on disconnect in connection oriented mode

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read device descriptor errors

readDomainAddress

java.util.List readDomainAddress(boolean oneAddressOnly)
                                 throws KNXException

Reads the domain address of a communication partner in the KNX network.

This service uses system broadcast communication mode.
The communication partner is a device in programming mode. In situations necessary to read domain addresses from more than one device in programming mode, oneAddressOnly is set to false and all received domain addresses are returned in the list. In this case, the whole response timeout is waited for address responses. If oneAddressOnly is true, the method returns after receiving the first read response, and the list contains one domain address.

Parameters:

oneAddressOnly - true if method should return after receiving the first read response, false to wait the whole response timeout for read responses

Returns:

list of byte arrays with domain addresses, ordered according to time of reception

Throws:

KNXTimeoutException - on a timeout during send or no address response was received

KNXInvalidResponseException - on invalid read response message

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read domain address errors

readDomainAddress

java.util.List readDomainAddress(byte[] domain,
                                 IndividualAddress startAddress,
                                 int range)
                                 throws KNXException

Reads the domain address of a communication partner identified using an address range.

This method is used to check existence of a device with the specified domain on a powerline medium and paying attention to more installations.
This service uses system broadcast communication mode.

A note on answering behavior when the specified range is < 255:
If an answering device 'A' receives a domain address response from another answering device 'B', 'A' will terminate the transmission of its response.

Parameters:

domain - byte array with domain address to check for, domain.length = 2 (powerline medium only)

startAddress - start from this individual address, lower bound of checked range

range - address range, specifies upper bound address (startAddress + range)

Returns:

list of byte arrays with domain addresses, ordered according to time of reception

Throws:

KNXTimeoutException - on a timeout during send or no address response was received

KNXInvalidResponseException - on invalid response message

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read domain address errors

readMemory

byte[] readMemory(Destination dst,
                  int startAddr,
                  int bytes)
                  throws KNXException

Reads memory data from the address space of a communication partner its controller.

This service uses point-to-point connection-oriented communication mode.
Note that a remote application layer shall ignore a memory read if the amount of read memory does not fit into an APDU of maximum length.

Parameters:

dst - destination to read from

startAddr - 16 bit start address to read in memory

bytes - number of data bytes to read (with increasing addresses)

Returns:

byte array containing the data read from the memory

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - on problems of the partner reading (part of) the memory (e.g. access to illegal or protected address space, invalid number of bytes)

KNXDisconnectException - on disconnect during read

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read memory error

readProperty

byte[] readProperty(Destination dst,
                    int objIndex,
                    int propID,
                    int start,
                    int elements)
                    throws KNXException

Reads the value of a property of an interface object of a communication partner.

This service uses point-to-point connectionless or connection-oriented communication mode.
One value element in the returned data byte array consumes
(data.length / elements) bytes.
The byte offset into the returned data to access a property value element with index i (zero based) is calculated the following way:
offset = (data.length / elements) * i.
Note that interface objects with active access protection are only accessible over connection oriented communication.

Parameters:

dst - destination to read from

objIndex - interface object index

propID - property identifier

start - start index in the property value to start reading from

elements - number of elements to read

Returns:

byte array containing the property value data

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - if tried to access a non existing property or forbidden property access (not sufficient access rights)

KNXInvalidResponseException - if received number of elements differ

KNXDisconnectException - on disconnect in connection oriented mode

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read property error

readPropertyDesc

byte[] readPropertyDesc(Destination dst,
                        int objIndex,
                        int propID,
                        int propIndex)
                        throws KNXException

Reads the description of a property of an interface object of a communication partner.

This service uses point-to-point connectionless or connection-oriented communication mode.
The property of the object is addressed either with a the propID or with the propIndex. The property index is only used if the property identifier is 0, otherwise the index is ignored.
When using the property ID for access, the property index in the returned description is either the correct property index of the addressed property or 0.

Parameters:

dst - destination to read from

objIndex - interface object index

propID - property identifier, specify 0 to use the property index

propIndex - property index, starts with index 0 for the first property

Returns:

byte array containing the property description, starting with the property object index

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - if the response contains no description (e.g. if tried to access a non existing property)

KNXDisconnectException - on disconnect in connection oriented mode

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read property description error

restart

void restart(Destination dst)
             throws KNXTimeoutException,
                    KNXLinkClosedException

Initiates a reset of the controller of a communication partner.

This service uses point-to-point connectionless or connection-oriented communication mode.
Invoking this method may result in a termination of the transport layer connection (i.e. state transition into disconnected for the supplied destination).

Parameters:

dst - destination to reset

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if network link to KNX network is closed

setPriority

void setPriority(Priority p)

Sets the KNX message priority for KNX messages to send.

Parameters:

p - new priority to use

setResponseTimeout

void setResponseTimeout(int timeout)

Sets the response timeout to wait for a KNX response message to arrive to complete a message exchange.

Parameters:

timeout - time in seconds

writeAddress

void writeAddress(byte[] serialNo,
                  IndividualAddress newAddress)
                  throws KNXTimeoutException,
                         KNXLinkClosedException

Modifies the individual address of a communication partner identified using an unique serial number in the KNX network.

This service uses broadcast communication mode.

Parameters:

serialNo - byte array with serial number, serialNo.length = 6

newAddress - new address

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if network link to KNX network is closed

writeAddress

void writeAddress(IndividualAddress newAddress)
                  throws KNXTimeoutException,
                         KNXLinkClosedException

Modifies the individual address of a communication partner in the KNX network.

This service uses broadcast communication mode.
The communication partner is a device in programming mode.

Parameters:

newAddress - new address

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if network link to KNX network is closed

writeDomainAddress

void writeDomainAddress(byte[] domain)
                        throws KNXTimeoutException,
                               KNXLinkClosedException

Modifies the domain address of a communication partner in the KNX network.

This service uses system broadcast communication mode.
The communication partner is a device in programming mode.

Parameters:

domain - byte array with domain address, domain.length = 2 (on powerline medium) or domain.length = 6 (on RF medium)

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if network link to KNX network is closed

writeKey

void writeKey(Destination dst,
              int level,
              byte[] key)
              throws KNXException

Modifies or deletes an authorization key associated to an access level of a communication partner.

This service uses point-to-point connection-oriented communication mode.
If the supplied key is 0xFFFFFFFF, the key for the given access level is removed. The write request has to be done using equal or higher access rights than the access rights of the level which is to be modified (i.e. current level <= level to change).

Parameters:

dst - destination to write to

level - access level to modify

key - new key for the access level or 0xFFFFFFFF to remove key

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - if the current access level > necessary access level for writing a key

KNXDisconnectException - on disconnect during write

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other write key error

writeMemory

void writeMemory(Destination dst,
                 int startAddr,
                 byte[] data)
                 throws KNXException

Writes memory data in the address space of a communication partner its controller.

This service uses point-to-point connection-oriented communication mode.
If verify mode is enabled for the destination, this method will wait for a memory write response and do an explicit read back of the written memory.
Note that a remote application layer shall ignore a memory write if the amount of memory does not fit into an APDU of maximum length the remote layer can handle.

Parameters:

dst - destination to write to

startAddr - 16 bit start address to write in memory

data - byte array containing the memory data to write

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - in verify mode on problems of the partner writing the memory data (e.g. access to illegal or protected address space, invalid number of bytes) or erroneous memory data was written

KNXInvalidResponseException - in verify mode if the size of memory read back differs from the written size of memory

KNXDisconnectException - on disconnect during read

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read memory error

writeProperty

void writeProperty(Destination dst,
                   int objIndex,
                   int propID,
                   int start,
                   int elements,
                   byte[] data)
                   throws KNXException

Modifies the value of a property of an interface object of a communication partner.

This service uses point-to-point connectionless or connection-oriented communication mode.
The value of the written property is explicitly read back after writing.
Note that interface objects with active access protection are only accessible over connection oriented communication.

Parameters:

dst - destination to write to

objIndex - interface object index

propID - property identifier

start - start index in the property value to start writing to

elements - number of elements to write

data - byte array containing property value data to write

Throws:

KNXTimeoutException - on a timeout during send

KNXRemoteException - if tried to access a non existing property or forbidden property access (not sufficient access rights) or erroneous property data was written

KNXInvalidResponseException - if received number of elements differ or the data length read back differs from the written data length

KNXDisconnectException - on disconnect in connection oriented mode

KNXLinkClosedException - if network link to KNX network is closed

KNXException - on other read property error