tuwien.auto.calimero.link
Class KNXNetworkLinkIP

java.lang.Object
  tuwien.auto.calimero.link.KNXNetworkLinkIP

All Implemented Interfaces:

KNXNetworkLink

public class KNXNetworkLinkIP
extends java.lang.Object
implements KNXNetworkLink

Implementation of the KNX network link based on the KNXnet/IP protocol, using a KNXnetIPConnection.

Once a link has been closed, it is not available for further link communication, i.e. it can't be reopened.

If KNXnet/IP routing is used as base protocol, the send methods with wait for confirmation behave equally like without wait specified, since routing is an unconfirmed protocol. This implies that no confirmation frames are generated, thus NetworkLinkListener.confirmation(FrameEvent) is not used.

IP address considerations:
On more IP addresses assigned to the local host (on possibly several local network interfaces), the default chosen local host address can differ from the expected. In this situation, the local endpoint has to be specified manually during instantiation.
Network Address Translation (NAT) aware communication can only be used, if the KNXnet/IP server of the remote endpoint supports it. Otherwise, connection timeouts will occur. With NAT enabled, KNXnet/IP accepts IPv6 addresses. By default, the KNXnet/IP protocol only works with IPv4 addresses.

Field Summary

static int	ROUTER Service mode for routing.
static int	TUNNEL Service mode for link layer tunneling.

Constructor Summary

KNXNetworkLinkIP(int serviceMode, java.net.InetSocketAddress localEP, java.net.InetSocketAddress remoteEP, boolean useNAT, KNXMediumSettings settings)
Creates a new network link based on the KNXnet/IP protocol, using a KNXnetIPConnection.

KNXNetworkLinkIP(java.net.NetworkInterface netIf, java.net.InetAddress mcGroup, KNXMediumSettings settings)
Creates a new network link based on the KNXnet/IP routing protocol, using a KNXnetIPRouter.

KNXNetworkLinkIP(java.lang.String remoteHost, KNXMediumSettings settings)
Creates a new network link based on the KNXnet/IP tunneling protocol, using a KNXnetIPTunnel with default communication settings.

Method Summary

void	addLinkListener(NetworkLinkListener l) Adds the specified event listener l to receive events from this link.
void	close() Ends communication with the KNX network and closes the network link.
byte	getHopCount() Returns the hop count used as default for KNX messages.
KNXMediumSettings	getKNXMedium() Returns the KNX medium settings used by this network link.
java.lang.String	getName() Returns the name of the link, a short textual representation to identify a link.
boolean	isOpen() Checks for open network link.
void	removeLinkListener(NetworkLinkListener l) Removes the specified event listener l, so it does no longer receive events from this link.
void	send(CEMILData msg, boolean waitForCon) Sends a KNX link layer message supplied as type cEMI L-data.
void	sendRequest(KNXAddress dst, Priority p, byte[] nsdu) Sends a link layer request message to the given destination.
void	sendRequestWait(KNXAddress dst, Priority p, byte[] nsdu) Sends a link layer request message to the given destination, and waits for the corresponding link layer confirmation.
void	setHopCount(int count) Sets the hop count used as default in KNX messages.
void	setKNXMedium(KNXMediumSettings settings) Supplies medium information necessary for KNX communication.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ROUTER

public static final int ROUTER

Service mode for routing.

See Also:

Constant Field Values

TUNNEL

public static final int TUNNEL

Service mode for link layer tunneling.

See Also:

Constant Field Values

Constructor Detail

KNXNetworkLinkIP

public KNXNetworkLinkIP(int serviceMode,
                        java.net.InetSocketAddress localEP,
                        java.net.InetSocketAddress remoteEP,
                        boolean useNAT,
                        KNXMediumSettings settings)
                 throws KNXException

Creates a new network link based on the KNXnet/IP protocol, using a KNXnetIPConnection.

For more details on KNXnet/IP connections, refer to the various KNXnet/IP implementations.

Parameters:

serviceMode - mode of communication to open, serviceMode is one of the service mode constants (e.g. TUNNEL); depending on the mode set, the expected local / remote endpoints might differ

localEP - the local endpoint of the link to use;
- in tunneling mode (point-to-point), this is the client control endpoint, use null for the default local host and an ephemeral port number
- in ROUTER mode, specifies the multicast interface, i.e. the local network interface is taken that has the IP address bound to it (if IP address is bound more than once, it's undefined which interface is returned), the port is not used; use null for localEP or an unresolved IP address to take the host's default multicast interface

remoteEP - the remote endpoint of the link to communicate with;
- in tunneling mode (point-to-point), this is the server control endpoint
- in ROUTER mode, the IP address specifies the multicast group to join, the port is not used; use null for remoteEP or an unresolved IP address to take the default multicast group

useNAT - true to use network address translation in tunneling service mode, false to use the default (non aware) mode; parameter is ignored for routing

settings - medium settings defining device and medium specifics needed for communication

Throws:

KNXException - on failure establishing link using the KNXnet/IP connection

KNXNetworkLinkIP

public KNXNetworkLinkIP(java.net.NetworkInterface netIf,
                        java.net.InetAddress mcGroup,
                        KNXMediumSettings settings)
                 throws KNXException

Creates a new network link based on the KNXnet/IP routing protocol, using a KNXnetIPRouter.

Parameters:

netIf - local network interface used to join the multicast group and for sending, use null for the host's default multicast interface

mcGroup - address of the multicast group to join, use null for the default KNXnet/IP multicast address

settings - medium settings defining device and medium specifics needed for communication

Throws:

KNXException - on failure establishing link using the KNXnet/IP connection

KNXNetworkLinkIP

public KNXNetworkLinkIP(java.lang.String remoteHost,
                        KNXMediumSettings settings)
                 throws KNXException

Creates a new network link based on the KNXnet/IP tunneling protocol, using a KNXnetIPTunnel with default communication settings.

The link is established using a KNXnet/IP tunnel, the local endpoint is the default local host, the remote endpoint uses the default KNXnet/IP port number, network address translation (NAT) is disabled.

Parameters:

remoteHost - remote host name

settings - medium settings defining device and medium specifics needed for communication

Throws:

KNXException - on failure establishing link using the KNXnet/IP connection

Method Detail

addLinkListener

public void addLinkListener(NetworkLinkListener l)

Description copied from interface: KNXNetworkLink

Adds the specified event listener l to receive events from this link.

If l was already added as listener, no action is performed.

Specified by:

addLinkListener in interface KNXNetworkLink

Parameters:

l - the listener to add

close

public void close()

Description copied from interface: KNXNetworkLink

Ends communication with the KNX network and closes the network link.

All registered link listeners get notified.
If no communication access was established in the first place, no action is performed.

Specified by:

close in interface KNXNetworkLink

getHopCount

public final byte getHopCount()

Description copied from interface: KNXNetworkLink

Returns the hop count used as default for KNX messages.

Specified by:

getHopCount in interface KNXNetworkLink

Returns:

hop count as 3 Bit unsigned value with the range 0 to 7

See Also:

KNXNetworkLink.setHopCount(int)

getKNXMedium

public KNXMediumSettings getKNXMedium()

Description copied from interface: KNXNetworkLink

Returns the KNX medium settings used by this network link.

The returned object is a reference to the one used by this link (not a copy).

Specified by:

getKNXMedium in interface KNXNetworkLink

Returns:

medium settings for KNX network

getName

public java.lang.String getName()

Description copied from interface: KNXNetworkLink

Returns the name of the link, a short textual representation to identify a link.

The name is unique for links with different remote endpoints.
The returned name is used by this link for the name of its log service. Supply KNXNetworkLink.getName() for LogManager.getLogService(String) for example to get the log service of this link.

By default, "link " + address/ID of the remote endpoint is returned (e.g. "Link 192.168.0.10:3671" for an IP link).
After closing the link, the returned name might differ, e.g. get reset to some arbitrary default name.

Specified by:

getName in interface KNXNetworkLink

Returns:

link name as string

isOpen

public boolean isOpen()

Description copied from interface: KNXNetworkLink

Checks for open network link.

After a call to KNXNetworkLink.close() or after the underlying protocol initiated the end of the communication, this method always returns false.

Specified by:

isOpen in interface KNXNetworkLink

Returns:

true if this network link is open, false on closed

removeLinkListener

public void removeLinkListener(NetworkLinkListener l)

Description copied from interface: KNXNetworkLink

Removes the specified event listener l, so it does no longer receive events from this link.

If l was not added in the first place, no action is performed.

Specified by:

removeLinkListener in interface KNXNetworkLink

Parameters:

l - the listener to remove

send

public void send(CEMILData msg,
                 boolean waitForCon)
          throws KNXTimeoutException,
                 KNXLinkClosedException

Description copied from interface: KNXNetworkLink

Sends a KNX link layer message supplied as type cEMI L-data.

If the source address of msg is 0.0.0, the device address supplied in the medium settings is used as message source address.

Specified by:

send in interface KNXNetworkLink

Parameters:

msg - cEMI L-data message to send

waitForCon - true to wait for link layer confirmation response, false to not wait for the confirmation

Throws:

KNXTimeoutException - on a timeout during send (for example when waiting on acknowledge using a reliable sending protocol)

KNXLinkClosedException - if the link is closed

sendRequest

public void sendRequest(KNXAddress dst,
                        Priority p,
                        byte[] nsdu)
                 throws KNXLinkClosedException,
                        KNXTimeoutException

Sends a link layer request message to the given destination.

Depending on the address, the request is either point-to-point, multicast or broadcast. A network link implementation is allowed to interpret a dst parameter of null as system broadcast, or otherwise uses its default broadcast behavior. When communicating with a KNX network which uses open medium, messages are broadcasted within domain (as opposite to system broadcast) by default. Specify dst null for system broadcast.

Specified by:

sendRequest in interface KNXNetworkLink

Parameters:

dst - KNX destination address, or null

p - priority this KNX message is assigned to

nsdu - network layer service data unit

Throws:

KNXLinkClosedException - if the link is closed

KNXTimeoutException - on a timeout during send (for example when waiting on acknowledge using a reliable sending protocol)

sendRequestWait

public void sendRequestWait(KNXAddress dst,
                            Priority p,
                            byte[] nsdu)
                     throws KNXTimeoutException,
                            KNXLinkClosedException

Sends a link layer request message to the given destination, and waits for the corresponding link layer confirmation.

Depending on the address, the request is either point-to-point, multicast or broadcast. A network link implementation is allowed to interpret a dst parameter of null as system broadcast, or otherwise uses its default broadcast behavior. When communicating with a KNX network which uses open medium, messages are broadcasted within domain (as opposite to system broadcast) by default. Specify dst null for system broadcast.

Specified by:

sendRequestWait in interface KNXNetworkLink

Parameters:

dst - KNX destination address, or null

p - priority this message is assigned to

nsdu - network layer service data unit

Throws:

KNXTimeoutException - on a timeout during send or while waiting for the confirmation

KNXLinkClosedException - if the link is closed

setHopCount

public final void setHopCount(int count)

Description copied from interface: KNXNetworkLink

Sets the hop count used as default in KNX messages.

It denotes how many sub networks a message is allowed to travel.
A message its hop count is decremented by KNX routers to limit distance and avoid looping. On hop count value 0, the message is discarded from the network. A hop count of 7 never gets decremented.
By default, a hop count of 6 is specified.

Specified by:

setHopCount in interface KNXNetworkLink

Parameters:

count - hop count value, 0 <= value <= 7

setKNXMedium

public void setKNXMedium(KNXMediumSettings settings)

Description copied from interface: KNXNetworkLink

Supplies medium information necessary for KNX communication.

These informations are differing between KNX media and depend on the KNX network this link is communicating with.
The settings medium type has to match the medium type supplied to the link in the first place.
The settings object is not copied internally to allow subsequent changes to medium settings by the user which should take effect immediately.

Specified by:

setKNXMedium in interface KNXNetworkLink

Parameters:

settings - medium settings to use, the expected subtype is according to the KNX network medium

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object