tuwien.auto.calimero.mgmt
Class ManagementClientImpl

java.lang.Object
  extended by tuwien.auto.calimero.mgmt.ManagementClientImpl
All Implemented Interfaces:
ManagementClient

public class ManagementClientImpl
extends java.lang.Object
implements ManagementClient

Implementation of management client.

Uses TransportLayer internally for communication.
All management service methods invoked after a detach of the network link are allowed to throw KNXIllegalStateException.


Constructor Summary
ManagementClientImpl(KNXNetworkLink link)
          Creates a new management client attached to the supplied KNX network link.
 
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 oneDomainOnly)
          Reads the domain address of a communication partner in the KNX network.
 java.util.List readDomainAddress(byte[] domain, IndividualAddress start, 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ManagementClientImpl

public ManagementClientImpl(KNXNetworkLink link)
                     throws KNXLinkClosedException
Creates a new management client attached to the supplied KNX network link.

The log service used by this management client is named "MC " + link.getName().

Parameters:
link - network link used for communication with a KNX network
Throws:
KNXLinkClosedException - if the network link is closed
Method Detail

authorize

public byte authorize(Destination dst,
                      byte[] key)
               throws KNXDisconnectException,
                      KNXTimeoutException,
                      KNXRemoteException,
                      KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
authorize in interface ManagementClient
Parameters:
dst - destination at which to authorize
key - byte array containing authorization key
Returns:
the granted access level
Throws:
KNXDisconnectException - on disconnect during authorize
KNXTimeoutException - on a timeout during send
KNXInvalidResponseException - if the received access level is out of the allowed value range
KNXLinkClosedException - if network link to KNX network is closed
KNXRemoteException

createDestination

public Destination createDestination(IndividualAddress remote,
                                     boolean connectionOriented)
Description copied from interface: ManagementClient
Creates a new destination using the remote KNX address for management communication.

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

Specified by:
createDestination in interface ManagementClient
Parameters:
remote - destination KNX individual address
connectionOriented - true for connection oriented mode, false for connectionless mode
Returns:
destination representing the logical connection

createDestination

public Destination createDestination(IndividualAddress remote,
                                     boolean connectionOriented,
                                     boolean keepAlive,
                                     boolean verifyMode)
Description copied from interface: ManagementClient
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.

Specified by:
createDestination in interface ManagementClient
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

public KNXNetworkLink detach()
Description copied from interface: ManagementClient
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.

Specified by:
detach in interface ManagementClient
Returns:
the formerly attached KNX network link, or null if already detached
See Also:
TransportLayer.detach()

getPriority

public Priority getPriority()
Description copied from interface: ManagementClient
Returns the current used KNX message priority for KNX messages.

Specified by:
getPriority in interface ManagementClient
Returns:
message Priority

getResponseTimeout

public int getResponseTimeout()
Description copied from interface: ManagementClient
Returns the response timeout used when waiting for a KNX response message to arrive.

Specified by:
getResponseTimeout in interface ManagementClient
Returns:
timeout in seconds

isOpen

public boolean isOpen()
Description copied from interface: ManagementClient
Returns whether a network link is attached to this management client.

Specified by:
isOpen in interface ManagementClient
Returns:
true if link attached, false if detached

readADC

public int readADC(Destination dst,
                   int channelNr,
                   int repeat)
            throws KNXTimeoutException,
                   KNXDisconnectException,
                   KNXRemoteException,
                   KNXLinkClosedException
Description copied from interface: ManagementClient
Reads the value of the A/D converter of a communication partner.

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

Specified by:
readADC in interface ManagementClient
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
KNXDisconnectException - on disconnect during read
KNXRemoteException - on remote converter read problem (e.g. overflow or wrong channel)
KNXLinkClosedException - if network link to KNX network is closed

readAddress

public IndividualAddress[] readAddress(boolean oneAddressOnly)
                                throws KNXTimeoutException,
                                       KNXRemoteException,
                                       KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
readAddress in interface ManagementClient
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
KNXRemoteException

readAddress

public IndividualAddress readAddress(byte[] serialNo)
                              throws KNXTimeoutException,
                                     KNXRemoteException,
                                     KNXLinkClosedException
Description copied from interface: ManagementClient
Reads the individual address of a communication partner identified using an unique serial number in the KNX network.

This service uses broadcast communication mode.

Specified by:
readAddress in interface ManagementClient
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
KNXRemoteException

readDeviceDesc

public byte[] readDeviceDesc(Destination dst,
                             int descType)
                      throws KNXInvalidResponseException,
                             KNXDisconnectException,
                             KNXTimeoutException,
                             KNXLinkClosedException
Description copied from interface: ManagementClient
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

Specified by:
readDeviceDesc in interface ManagementClient
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:
KNXInvalidResponseException - on invalid read response message
KNXDisconnectException - on disconnect in connection oriented mode
KNXTimeoutException - on a timeout during send
KNXLinkClosedException - if network link to KNX network is closed

readDomainAddress

public java.util.List readDomainAddress(boolean oneDomainOnly)
                                 throws KNXLinkClosedException,
                                        KNXInvalidResponseException,
                                        KNXTimeoutException
Description copied from interface: ManagementClient
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.

Specified by:
readDomainAddress in interface ManagementClient
Parameters:
oneDomainOnly - 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:
KNXLinkClosedException - if network link to KNX network is closed
KNXInvalidResponseException - on invalid read response message
KNXTimeoutException - on a timeout during send or no address response was received

readDomainAddress

public java.util.List readDomainAddress(byte[] domain,
                                        IndividualAddress start,
                                        int range)
                                 throws KNXInvalidResponseException,
                                        KNXLinkClosedException,
                                        KNXTimeoutException
Description copied from interface: ManagementClient
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.

Specified by:
readDomainAddress in interface ManagementClient
Parameters:
domain - byte array with domain address to check for, domain.length = 2 (powerline medium only)
start - 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:
KNXInvalidResponseException - on invalid response message
KNXLinkClosedException - if network link to KNX network is closed
KNXTimeoutException - on a timeout during send or no address response was received

readMemory

public byte[] readMemory(Destination dst,
                         int startAddr,
                         int bytes)
                  throws KNXTimeoutException,
                         KNXDisconnectException,
                         KNXRemoteException,
                         KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
readMemory in interface ManagementClient
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
KNXDisconnectException - on disconnect during read
KNXRemoteException - on problems of the partner reading (part of) the memory (e.g. access to illegal or protected address space, invalid number of bytes)
KNXLinkClosedException - if network link to KNX network is closed

readProperty

public byte[] readProperty(Destination dst,
                           int objIndex,
                           int propID,
                           int start,
                           int elements)
                    throws KNXTimeoutException,
                           KNXRemoteException,
                           KNXDisconnectException,
                           KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
readProperty in interface ManagementClient
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

readPropertyDesc

public byte[] readPropertyDesc(Destination dst,
                               int objIndex,
                               int propID,
                               int propIndex)
                        throws KNXTimeoutException,
                               KNXRemoteException,
                               KNXDisconnectException,
                               KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
readPropertyDesc in interface ManagementClient
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

restart

public void restart(Destination dst)
             throws KNXTimeoutException,
                    KNXLinkClosedException
Description copied from interface: ManagementClient
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).

Specified by:
restart in interface ManagementClient
Parameters:
dst - destination to reset
Throws:
KNXTimeoutException - on a timeout during send
KNXLinkClosedException - if network link to KNX network is closed

setPriority

public void setPriority(Priority p)
Description copied from interface: ManagementClient
Sets the KNX message priority for KNX messages to send.

Specified by:
setPriority in interface ManagementClient
Parameters:
p - new priority to use

setResponseTimeout

public void setResponseTimeout(int timeout)
Description copied from interface: ManagementClient
Sets the response timeout to wait for a KNX response message to arrive to complete a message exchange.

Specified by:
setResponseTimeout in interface ManagementClient
Parameters:
timeout - time in seconds

writeAddress

public void writeAddress(byte[] serialNo,
                         IndividualAddress newAddress)
                  throws KNXTimeoutException,
                         KNXLinkClosedException
Description copied from interface: ManagementClient
Modifies the individual address of a communication partner identified using an unique serial number in the KNX network.

This service uses broadcast communication mode.

Specified by:
writeAddress in interface ManagementClient
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

public void writeAddress(IndividualAddress newAddress)
                  throws KNXTimeoutException,
                         KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
writeAddress in interface ManagementClient
Parameters:
newAddress - new address
Throws:
KNXTimeoutException - on a timeout during send
KNXLinkClosedException - if network link to KNX network is closed

writeDomainAddress

public void writeDomainAddress(byte[] domain)
                        throws KNXTimeoutException,
                               KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
writeDomainAddress in interface ManagementClient
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

public void writeKey(Destination dst,
                     int level,
                     byte[] key)
              throws KNXTimeoutException,
                     KNXDisconnectException,
                     KNXRemoteException,
                     KNXLinkClosedException
Description copied from interface: ManagementClient
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).

Specified by:
writeKey in interface ManagementClient
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
KNXDisconnectException - on disconnect during write
KNXRemoteException - if the current access level > necessary access level for writing a key
KNXLinkClosedException - if network link to KNX network is closed

writeMemory

public void writeMemory(Destination dst,
                        int startAddr,
                        byte[] data)
                 throws KNXDisconnectException,
                        KNXTimeoutException,
                        KNXRemoteException,
                        KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
writeMemory in interface ManagementClient
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:
KNXDisconnectException - on disconnect during read
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
KNXLinkClosedException - if network link to KNX network is closed

writeProperty

public void writeProperty(Destination dst,
                          int objIndex,
                          int propID,
                          int start,
                          int elements,
                          byte[] data)
                   throws KNXTimeoutException,
                          KNXRemoteException,
                          KNXDisconnectException,
                          KNXLinkClosedException
Description copied from interface: ManagementClient
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.

Specified by:
writeProperty in interface ManagementClient
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