How to manage KNX Devices using the KNX Module Java API.

Sending Frames to Devices

To send a frame to a KNX device:

1. Obtain the com.prosyst.mbs.services.knx.layerData.DataLink service.
2. Create a frame by using the utility classes from the com.prosyst.mbs.services.knx.layerApp package.
3. Call the DataLink.dataRequest method to send the frame.

Receiving Frames from Devices

To receive frames from a KNX device:

1. Register an org.osgi.service.event.EventHandler.
2. Make sure that the driver is connected.
3. When the driver receives an event from the KNX bus, it delivers the event asynchronously to the event handlers.
4. Process the frame in the handleEvent method. The KNX Frame event has a topic "com/prosyst/mbs/services/knx/layerData/FrameEvent" (Use DataLink.TOPIC_FRAME constants)
5. Release all references to the event object before exiting the handleEvent method.

The following example demonstrates advanced techniques for receiving notifications for incoming frames from the KNX bus. The event handles is registered with event filter, that instructs the event admin service to deliver only those events, that match the given filter. The event handler itself, processes the group value read requests and generates a response.

package receive.frames.example;

import java.util.Hashtable;

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;

import com.prosyst.mbs.services.knx.KnxUtil;
import com.prosyst.mbs.services.knx.cemi.APCI;
import com.prosyst.mbs.services.knx.cemi.Priority;
import com.prosyst.mbs.services.knx.cemi.frames.L_Data_cEMI;
import com.prosyst.mbs.services.knx.layerApp.MulticastService;
import com.prosyst.mbs.services.knx.layerData.DataLink;

public class ReceiveFramesExample {

BundleContext bc; // Must be initialized
ServiceRegistration eventHandlerReg;
DataLink dataLink;

public void receiveFrames() {

String topics[] = { DataLink.TOPIC_FRAME, /*An incoming frame event*/};
String filter = //
"(&" + //
//Receive frame, with target Group Address 1/0/2
"(" + DataLink.P_TARGET + "=" + KnxUtil.toAddress("1/0/2", '/') + ")" +
//Respond only to GROUP_VALUE_READ requests.
"(" + DataLink.P_APCI + "=" + APCI.GROUPVALUE_READ + ")" + //")";

//Initialize the properties with the correct topics
Hashtable props = new Hashtable(2);
props.put(EventConstants.EVENT_TOPIC, topics);
props.put(EventConstants.EVENT_FILTER, filter);

EventHandler handler = new EventHandler() {

public void handleEvent(Event event) {
//Print the received event
L_Data_cEMI frame = (L_Data_cEMI) event.getProperty(DataLink.P_FRAME);
final int groupAddress = KnxUtil.toAddress("1/0/2", '/');
// process only "group value read" requests, with destination GROUP
// address 1/0/2
if (frame.isDAF() && frame.getDestination() == groupAddress
&& APCI.GROUPVALUE_READ == frame.getAPCI()) {
/**
* generate response frame - notice, the initially we generate
*"group value write" request, but after that we replace the
* APCI with "response" type.
*/
L_Data_cEMI response = MulticastService.A_GroupValue_Write(//
groupAddress, /*Group Address*/
Priority.NORMAL, /*Priority is usually normal*/
1, // group value
false);
response.setAPCI(APCI.GROUPVALUE_RESPONSE);

// send response
try {
dataLink.dataRequest(response);
} catch (Throwable e) {
e.printStackTrace();
}
}
}
};

eventHandlerReg = bc.registerService(EventHandler.class.getName(), handler,
props);
}
}

The following is an example for an event handler which is notified, when the KNX driver is connected or disconnected.

import java.util.Hashtable;

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;

import com.prosyst.mbs.services.knx.layerData.DataLink;

public class ReceiveConnectionStatus {

ServiceRegistration eventHandlerReg;
BundleContext bc; // Must be initialized

public void receiveConnectionStatus() {

String topics[] = { DataLink.TOPIC_CONNECT, // When the data link driver connects
DataLink.TOPIC_DISCONNECT, // Disconnected
};

// Initialize the properties with the correct topics
Hashtable props = new Hashtable(2);
props.put(EventConstants.EVENT_TOPIC, topics);

EventHandler handler = new EventHandler() {

public void handleEvent(Event event) {
// Just print the received event
System.out.println(event);
}
};

eventHandlerReg = bc.registerService(EventHandler.class.getName(), handler, props);

}

}

The following is an example for an event handler which is notified, when the KNX driver is connected or disconnected, or a data frame is received from a KNX device.

import java.util.Hashtable;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;
import com.prosyst.mbs.services.knx.layerData.DataLink;

public class ReceiveAllEvents {

ServiceRegistration eventHandlerReg;
BundleContext bc; // Must be initialized

public void receiveAllEvents() {
String topics[] = { DataLink.TOPIC_CONNECT, // When the data link driver connects
DataLink.TOPIC_DISCONNECT, // Disconnected
DataLink.TOPIC_FRAME, // Incoming frame event
};

// Initialize the properties with the correct topics
Hashtable props = new Hashtable(2);
props.put(EventConstants.EVENT_TOPIC, topics);

EventHandler handler = new EventHandler() {

public void handleEvent(Event event) {
// Just print the received event
System.out.println(event);
}
};

eventHandlerReg = bc.registerService(EventHandler.class.getName(), handler,props);
}
}