Subscribing to DECT Events

You can develop applications which track the events related to DECT networks. To do so you need to subscribe to the events that are published by the DECT Module, i.e. register an event handler.

The event topics and related properties, along with predefined values are available in the com.prosyst.mbs.services.dect.DectConstants interface.

Subscribing to Events Related to Adding/Removing HAN Devices

1. Register an Event Handler service for the following topics depending on your needs:
   • DectConstants.EVENT_DEVICE_ADDED - to receive events when new HAN devices are added
   • DectConstants.DECT_DEVICE_REMOVED - to receive events when HAN devices are removed  
2. In the handleEvent method of your Event Handler implementation, process the properties of the passed Event as follows:
   • DectConstants.KEY_PID:String - to retrieve the DECT Base Connection ID within the network
   • DectConstants.KEY_DEVICE_ID:String - to retrieve the DECT Device ID within the network
   • DectConstants.KEY_UNITS:String - to retrieve units belonging to the device
   • DectConstants.KEY_HANDSET_TYPE:String - to retrieve the type of the DECT Device; for a HAN device is "HAN" (optional)
   • DectConstants.KEY_IPUI:String - to retrieve the unique ID of the device, International Portable User Identifier
   • DectConstants.KEY_DEVICE_EMC:String - to retrieve the device Equipment Manufacturer Code

Subscribing to Events Related to Commands Sent by HAN Devices

1. Register an Event Handler service for the following topics depending on your needs:
   • DectConstants.EVENT_DEVICE_COMMAND - to receive events when new HAN devices sends a command
2. In the handleEvent method of your Event Handler implementation, process the properties of the passed Event as follows:
   • DectConstants.KEY_PID:String - to retrieve the DECT Base Connection ID within the network
   • DectConstants.KEY_DEVICE_ID:String - to retrieve the DECT Device ID within the network
   • DectConstants.KEY_UNIT_ID:String - to retrieve an HanDeviceUnit object representing the DECT Device unit that sent the command
   • DectConstants.KEY_INTERFACE_ID:String - to retrieve the ID of the interface sending the command
   • DectConstants.KEY_COMMAND_ID:String - to retrieve the ID of the command
   • DectConstants.KEY_PAYLOAD:String - to retrieve data payload belonging to the command, presents if exists data payload belonging to the command, presents if exists

Subscribing to Events Related to Changes in the Mode of the Base Station

1. Register an Event Handler service for the following topics depending on your needs:
   • DectConstants.EVENT_REGISTRATION_OPENED - to receive events on transition of the Base Station from normal mode to registration mode
   • DectConstants.EVENT_REGISTRATION_CLOSED - to receive events on transition of the Base Station from registration mode to normal mode  
2. In the handleEvent method of your Event Handler implementation, process the properties of the passed Event as follows:
   • DectConstants.KEY_PID:String - to retrieve the Dect Base Connection ID
   • DectConstants.KEY_DURATION:String - to retrieve the duration in seconds of the registration mode (optional, only in DectConstants.EVENT_REGISTRATION_OPENED events)
   • DectConstants.KEY_REG_CLOSE_REASON:String - to retrieve the reason for the transition to normal mode (only in DectConstants.EVENT_REGISTRATION_CLOSED events); possible values are
     • DectConstants.REG_CLOSE_REASON_HS_REGISTERED
     • DectConstants.REG_CLOSE_REASON_TIMEOUT
     • DectConstants.REG_CLOSE_REASON_UNKNOWN

The DECT Driver API

Upon connecting to a Base Station, the DECT Driver bundle registers a DECTBaseConnection service for managing a DECT network. From that service you can retrieve services for the following functionality areas, as defined in the model of the Base Station API functions:

• CordlessService - for enabling the Base Station to discover devices
• ParamService - for configuring the Base Station
• HanService - for retrieving devices and for sending messages to them
• HandsetService - for disconnecting devices from the network
• SystemService - for resetting the Base Station and for retrieving its module versions

To use this API, retrieve the DECTBaseConnection service and from it retrieve the DECT service you are interested in.

The following code snippet demonstrates getting the Handset Service from the Base Station:

   ServiceReference reference = context.getServiceReference(DectBaseConnection.class.getName());

    DectBaseConnection baseConnection = (DectBaseConnection) context.getService(reference);

     HanService hanService = (HanService) baseConnection.getService(HanService.NAME_SERVICE);  

The OSGi Runtime allows you to manage multiple DECT networks at same time, i.e. it supports parallel connections to more than one Base Stations. In this case, the DECT Module registers a separate OSGi service for each network it is managing.

Managing a DECT Base Station

In this topic we describe how to configure a DECT Base Station (network controller) and how to enable it to discover further DECT HAN devices.

Configuring a DECT Base Station

You configure a Base Station by setting values to its parameters.

To set a new value to a parameter:

1. From the DECTBaseConnection service, retrieve the ParamService.
2. Construct a new Parameter object by passing:
   • The ID of the parameter you want to change.
   • One of the constants defined in ParamService (which include the string TYPE), indicating where the parameter is stored - in RAM or EEPROM.
   • The new value of the parameter.
3. Call the writeParameter method of the ParamService and pass the object containing the data about the parameter that you want to change.

Enabling a DECT Base Station to Discover DECT HAN Devices

To enable a Base Station to discover DECT HAN devices:

1. From the DECTBaseConnection service, retrieve the CordlessService service.
2. Call the openRegistration method of the CordlessService service.

The Base Station is now enabled to discover DECT HAN devices.

The following code snippet demonstrates enabling the Base Station to discover DECT HAN devices.

     CordlessService cordlessService = (CordlessService) baseConnection.getService(CordlessService.NAME_SERVICE);

    try {

      cordlessService.openRegistration(90); // parameter time in seconds

    } catch (DectException e) {

      // handle exception

    }

Managing DECT Devices

Managing Devices using the DECT Java API.

Retrieving DECT Devices and Device Units

Each physical device in a DECT network is represented by one HanDevice object which consist of one or several HanUnit objects. Sometimes one physical device can be represented by several units - one for each of its functionalities.

The DECT Module allows you to retrieve devices and device units. You can retrieve a device either from the list of all registered devices, or from the events for its registration/removal.

Getting a Device from the List of Connected Devices

To retrieve a device from the list of all registered devices:

1. From the DECTBaseConnection service, retrieve the HanService service.
2. Call the readDeviceTable method of the HanService service. The method returns an array of HanDevice objects representing all connected devices.

Getting the ID of a Device and/or its Device Units from Events

Using the OSGi Event Admin Service, you can receive events about added and removed devices. From these events you can get the device being added/removed.

1. Implement an org.osgi.service.event.EventHandler service which listens for events with the following topics.
   • DectConstants.EVENT_DEVICE_ADDED - to receive events each time a device connects to a DECT network.
   • DectConstants.DECT_DEVICE_REMOVED - to receive events each time a device is disconnected from a DECT network.
2. Get the value of the property DectConstants.KEY_DEVICE_ID It is the ID of the device being added/removed.
3. Get the value of the DectConstants.KEY_UNITS property It is an array of HanUnit objects representing the units that belong to the device being added/removed.

Communicating with DECT Devices

You communicate with DECT devices by sending and receiving messages:

Sending a Message to a Device

There are three types of messages, which can be sent to a DECT Device:

•     command messages (for executing a command on the device)
•     messages for getting device attributes
•     messages for setting device attributes

To send a message to a DECT device:

1. From the DECTBaseConnection service, retrieve the HanService service.
2. Create a HanMessage. There are three constructors available for creating HanMessage objects.
   • HanMessage(short srcDeviceId, byte srcUnitId, short dstDeviceId, byte dstUnitId, byte dstAddressType, byte msgSequence, int msgType, byte interfaceType, short interfaceId, byte interfaceMember, byte data[])
   • HanMessage(short dstDeviceId, byte dstUnitId, byte dstAddressType, byte msgSequence, int msgType, byte interfaceType, short interfaceId, byte interfaceMember, byte data[])
   • HanMessage(short dstDeviceId, byte dstUnitId, int msgType, short interfaceId, byte interfaceMember, byte data[]) where
     • srcDeviceId is the ID of the source device
     • srcUnitId is the ID of the source unit
     • dstDeviceId is the ID of the destination device
     • dstUnitId is the ID of the destination unit
     • dstAddressType is the destination address type
     • msgSequence is the message itself
     • msgType is the type of the message (defined above); one of the constants, defined in HanMessage, which represent message type: CMBS_HAN_MSG_TYPE_CMD (for command), CMBS_HAN_MSG_TYPE_ATTR_GET (for getting the value of an attribute) CMBS_HAN_MSG_TYPE_ATTR_SET (for setting a new value for an attribute)
     • interfaceType is the type of the interface
     • interfaceId is the interface ID of the device. Refer to the documentation that comes with the device for a list of its supported interface(s)
     • interfaceMember is the interface member
     • data is the new value of the attribute, if message is for setting attribute; the command arguments - for command messages; null if not applicable
3. Call one of the two send methods of the HanService, and pass the message as an argument.
   • Call the send(HanMessage, boolean) method to send a message and wait for a response from the device.
   • Call the send(HanMessage, boolean, HanResponseListener) method to send a message without waiting for the response from the device. In this case, you have to attach a message listener (implementation of the HanResponseListener interface) in order to get the response.

The following code snippet demonstrates getting all HAN devices and HAN device units from the network and sending a "turn on" command message with interface id "0x0200" and interface member "0x01" to all HAN device units of type simple outlet.

   HanDevice[] devices = hanService.readDeviceTable();

   for (int i = 0; i < devices.length; i++) {

    // get the han device units of the current device

    HanDeviceUnit[] devUnits = (HanDeviceUnit[]) devices[i].getHanUnits();

    for (int j = 0; j < devUnits.length; j++) {

     // if device unit is of type simple outlet send a turn on command

     if (devUnits[j].getType() == 0x0106 /* DectAdapterUtil.UNIT_TYPE_SIMPLE_OUTLET*/) {

    HanMessage hanMessage = new HanMessage(devices[i].getId(), devUnits[j].getId(),

    (short) HanMessage.MSG_TYPE_CMD, 0x0200, (byte) 0x01, null);

    try {

        hanService.send(hanMessage, false);

     } catch (DectException e) {

      // handle exception

        }

       }

     }

   }    

Receiving a Message (Event) from a Device

When sending messages that are not as a response to a message from the Base Station, devices do not use HanMessage objects. Instead they send events (similar to the device registration events) using the OSGi EventAdmin service. Each message event contains the parameters of the message (interface ID and command ID) as properties.

To receive messages from device units, subscribe to the DectConstants.EVENT_DEVICE_COMMAND event topic.

Response messages are always of type Command.

Removing DECT Devices

Depending on the type of the device (HAN or non-HAN DECT device) the procedures for removing it from a DECT network are different.

To remove a non-HAN (e.g. voice) DECT device from a DECT network:

1. From the DECTBaseConnection service, retrieve the HandsetService.
2. Call the removeDevice method of the HandsetService and pass the ID of the device you want to remove.

To remove a HAN DECT device from a DECT network:

1. From the DECTBaseConnection service, retrieve the HanService service.
2. Call the removeDevice method of the HanService and pass the ID of the device you want to remove.