tuwien.auto.calimero.knxnetip
Class KNXnetIPRouter

java.lang.Object
  tuwien.auto.calimero.knxnetip.KNXnetIPRouter

All Implemented Interfaces:

KNXnetIPConnection

public class KNXnetIPRouter
extends java.lang.Object

KNXnet/IP connection for KNX routing protocol.

A KNXnet/IP router is a fast replacement for line/backbone couplers and connected main/backbone lines, using Ethernet cabling for example.
The router use point to multipoint communication (multicast). By default, routers are joined to the DEFAULT_MULTICAST multicast group. On more KNX installations in one IP network, different multicast addresses have to be assigned.
All IP datagrams use port number 3671, i.e only datagrams on this port are observed.
The routing protocol is an unconfirmed service.

Optionally, a listener of type RouterListener can be supplied to addConnectionListener(KNXListener) instead of a default KNXListener, to receive RouterListener.lostMessage(LostMessageEvent) notifications.

Multicast considerations:
By default, the loopback mode of the socket used for sending multicast datagrams is disabled.

A multicast datagram sent with an initial hop count greater 1 may be delivered to the sending host on a different interface (than the sending one), if the host is a member of the multicast group on that interface. The loopback mode setting of the sender's socket has no effect on this behavior.

Nested Class Summary

Nested classes/interfaces inherited from interface tuwien.auto.calimero.knxnetip.KNXnetIPConnection

KNXnetIPConnection.BlockingMode

Field Summary

static int	ACK_ERROR Status code of communication: in idle state, received an acknowledge error in response, ready to send.
static int	ACK_PENDING Status code of communication: waiting for acknowledge after send, no error, not ready to send.
static int	CEMI_CON_PENDING Status code of communication: waiting for confirmation after acknowledge, no error, not ready to send.
static java.lang.String	DEFAULT_MULTICAST Multicast address assigned by default to KNXnet/IP routers, address "224.0.23.12".
static int	UNKNOWN_ERROR Status code of communication: unknown error, no send possible.

Fields inherited from interface tuwien.auto.calimero.knxnetip.KNXnetIPConnection

CLOSED, IP_PORT, KNXNETIP_VERSION_10, NONBLOCKING, OK, WAIT_FOR_ACK, WAIT_FOR_CON

Constructor Summary

KNXnetIPRouter(java.net.NetworkInterface netIf, java.net.InetAddress mcGroup)
Creates a new KNXnet/IP routing service.

Method Summary

void	addConnectionListener(KNXListener l) Adds the specified event listener l to receive events from this connection.
void	close() Ends communication with the remote server/client as specified by the used protocol.
protected void	connect(java.net.InetSocketAddress localEP, java.net.InetSocketAddress serverCtrlEP, CRI cri, boolean useNAT) Opens a new IP communication channel to a remote server.
protected void	fireFrameReceived(CEMI frame) Fires a frame received event (KNXListener.frameReceived(FrameEvent)) for the supplied cEMI frame.
int	getHopCount() Returns the default hop count (TTL) used in the IP header of encapsulated cEMI messages.
java.lang.String	getName() Returns the name of this connection, a brief textual representation to identify a KNXnet/IP connection.
java.net.InetSocketAddress	getRemoteAddress() Returns the address (endpoint) this connection endpoint is communicating to.
protected int	getSeqNoRcv() Returns the protocol's current receive sequence number.
protected int	getSeqNoSend() Returns the protocol's current send sequence number.
int	getState() Returns information about the current KNXnet/IP communication state.
protected void	incSeqNoRcv() Increments the protocol's receive sequence number, with increment on sequence number 255 resulting in 0.
protected void	incSeqNoSend() Increments the protocol's send sequence number, with increment on sequence number 255 resulting in 0.
void	removeConnectionListener(KNXListener l) Removes the specified event listener l, so it does no longer receive events from this connection.
void	send(CEMI frame, KNXnetIPConnection.BlockingMode mode) Sends a cEMI frame to the joined multicast group.
void	setHopCount(int hopCount) Sets the default hop count (TTL) used in the IP header of encapsulated cEMI messages.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MULTICAST

public static final java.lang.String DEFAULT_MULTICAST

Multicast address assigned by default to KNXnet/IP routers, address "224.0.23.12".

This is the standard system setup multicast address used in KNXnet/IP.

See Also:

Constant Field Values

ACK_ERROR

public static final int ACK_ERROR

Status code of communication: in idle state, received an acknowledge error in response, ready to send.

See Also:

Constant Field Values

ACK_PENDING

public static final int ACK_PENDING

Status code of communication: waiting for acknowledge after send, no error, not ready to send.

See Also:

Constant Field Values

CEMI_CON_PENDING

public static final int CEMI_CON_PENDING

Status code of communication: waiting for confirmation after acknowledge, no error, not ready to send.

See Also:

Constant Field Values

UNKNOWN_ERROR

public static final int UNKNOWN_ERROR

Status code of communication: unknown error, no send possible.

See Also:

Constant Field Values

Constructor Detail

KNXnetIPRouter

public KNXnetIPRouter(java.net.NetworkInterface netIf,
                      java.net.InetAddress mcGroup)
               throws KNXException

Creates a new KNXnet/IP routing service.

In general, routers are assigned a multicast address by adding an offset to the system setup multicast address ("224.0.23.12") for each KNX installation, by default this offset is 0 (i.e. only one used installation).

Parameters:

netIf - specifies the local network interface used to join the multicast group and send outgoing multicast data, use null to use the default interface; useful for multihomed hosts

mcGroup - address of the multicast group this router is joined to, or null to use the default multicast ("224.0.23.12"); value of mcAddr >= "224.0.23.12"

Throws:

KNXException - on socket error, or if joining to group failed

Method Detail

getHopCount

public final int getHopCount()

Returns the default hop count (TTL) used in the IP header of encapsulated cEMI messages.

The hop count value is queried from the used multicast socket.

Returns:

hop count in the range 0 to 255

getName

public java.lang.String getName()

Description copied from interface: KNXnetIPConnection

Returns the name of this connection, a brief textual representation to identify a KNXnet/IP connection.

The name has to be unique at least for connections with different IP addresses for the remote control endpoint.
The returned name is used by this connection for the name of its log service.

Returns:

name for this connection as string

send

public void send(CEMI frame,
                 KNXnetIPConnection.BlockingMode mode)
          throws KNXConnectionClosedException

Sends a cEMI frame to the joined multicast group.

Specified by:

send in interface KNXnetIPConnection

Parameters:

frame - cEMI message to send

mode - arbitrary value, does not influence behavior, since routing is always a unconfirmed, nonblocking service

Throws:

KNXConnectionClosedException - if no communication was established in the first place or communication was closed

setHopCount

public final void setHopCount(int hopCount)

Sets the default hop count (TTL) used in the IP header of encapsulated cEMI messages.

This value is used to limit the multicast geographically, although this is just a rough estimation. The hop count value is forwarded to the underlying multicast socket used for communication.

Parameters:

hopCount - hop count value, 0 <= value <= 255

addConnectionListener

public void addConnectionListener(KNXListener l)

Description copied from interface: KNXnetIPConnection

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

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

Note: the method KNXListener.frameReceived(tuwien.auto.calimero.FrameEvent) of an added listener will be invoked by the KNXnet/IP receiver, and not in the context of the calling thread. Lengthy tasks have to be avoided during the notification, and should be relayed into their own worker thread. Otherwise subsequent listener invocations will suffer from time delays since the receiver can not move on.

Specified by:

addConnectionListener in interface KNXnetIPConnection

Parameters:

l - the listener to add

close

public final void close()

Description copied from interface: KNXnetIPConnection

Ends communication with the remote server/client as specified by the used protocol.

All registered event listeners get notified. The close event is the last event the listeners receive.
If this connection endpoint is already closed, no action is performed.

Specified by:

close in interface KNXnetIPConnection

connect

protected void connect(java.net.InetSocketAddress localEP,
                       java.net.InetSocketAddress serverCtrlEP,
                       CRI cri,
                       boolean useNAT)
                throws KNXException

Opens a new IP communication channel to a remote server.

The communication state of this object is assumed to be closed state. This method is designed to be called only once during the objects lifetime!

Parameters:

localEP - the local endpoint to use for communication channel

serverCtrlEP - the remote server control endpoint used for connect request

cri - connect request information used to configure the communication attributes

useNAT - true to use a NAT (network address translation) aware communication mechanism, false to use the default way

Throws:

KNXException - on socket communication error

KNXTimeoutException - on no connect response before connect timeout

KNXRemoteException - if response indicates an error condition at the server concerning the request

KNXInvalidResponseException - if connect response is in wrong format

fireFrameReceived

protected void fireFrameReceived(CEMI frame)

Fires a frame received event (KNXListener.frameReceived(FrameEvent)) for the supplied cEMI frame.

Parameters:

frame - the cEMI to generate the event for

getRemoteAddress

public final java.net.InetSocketAddress getRemoteAddress()

Description copied from interface: KNXnetIPConnection

Returns the address (endpoint) this connection endpoint is communicating to.

The address returned is equal to the one used to establish the communication (e.g. control endpoint), although internal there might be used different addresses.
If no communication is established, the unspecified (wildcard) address with port number 0 is returned.

Specified by:

getRemoteAddress in interface KNXnetIPConnection

Returns:

IP address/host and port as InetSocketAddress

getSeqNoRcv

protected int getSeqNoRcv()

Returns the protocol's current receive sequence number.

Returns:

receive sequence number as int

getSeqNoSend

protected int getSeqNoSend()

Returns the protocol's current send sequence number.

Returns:

send sequence number as int

getState

public final int getState()

Description copied from interface: KNXnetIPConnection

Returns information about the current KNXnet/IP communication state.

Specified by:

getState in interface KNXnetIPConnection

Returns:

state enumeration

incSeqNoRcv

protected void incSeqNoRcv()

Increments the protocol's receive sequence number, with increment on sequence number 255 resulting in 0.

incSeqNoSend

protected void incSeqNoSend()

Increments the protocol's send sequence number, with increment on sequence number 255 resulting in 0.

removeConnectionListener

public void removeConnectionListener(KNXListener l)

Description copied from interface: KNXnetIPConnection

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

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

Specified by:

removeConnectionListener in interface KNXnetIPConnection

Parameters:

l - the listener to remove