Overview

The purpose of the EEBUS SPINE Exporter is to:

• provide an API for exporting EEBus SPINE devices which are implemented as OSGi services;
• allow to implement a bridge between any other home protocol and EEBus SPINE, e.g. ZigBee-to-EEBus SPINE;
• be independent of the EEBus SPINE transport.

API Details

The API allows to fully customize the device and its structure. This can be done in a very flexible way. There are four general levels of customization:

1. On the base level are the virtual SPINE devices.
   • A device can be added by registering a OSGI service of type com.prosyst.mbs.services.spine.export.SPINEDeviceDescriptor. The service can provide the full device structure upon registration but this is not required. If the application needs it the structure of the device can be extended and refined after the initial registration.
   • The device can be updated in two ways. The first option is to completely remove it and add it as a new device. The other option is to fine tune it by using some of the higher level of customizations described below.
   • A device can be removed by unregistering the corresponding OSGI service.
   • If the registered device is missing primary entity and/or feature default implementations are provided. The primary feature comes with bindings, subscriptions and detailed discovery support included.
2. The next level is the level of the virtual SPINE entities
   • An entity can be added to an existing device by registering a OSGI service of type com.prosyst.mbs.services.spine.export.SPINEEntityDescriptor.
   • The entity can be extended and refined later by adding removing or updating features and functions.
   • The entity can be removed by unregistering the corresponding OSGI service or by removing some of its ancestors including the device itself.
3. The next level is the level of the virtual SPINE features.
   • A virtual SPINE feature can be added to an existing device by registering a OSGI service of type com.prosyst.mbs.services.spine.export.SPINEFeatureDescriptor.
   • A feature can be extended and refined later, too. This can be done by adding or removing additional functions as explained below.

A feature can be removed by unregistering the corresponding OSGI service or any of its ancestors.

1. The highest level is the level of SPINE functions.
   • A Spine function implementation can be added by registering a OSGI service of type com.prosyst.mbs.services.spine.export.SPINEFunctionHandler. These are the actual implementations that are supposed to handle any SPINE request sent to this device.
   • A function can be removed by unregistering the corresponding OSGI service.
   • A function handler can gain access to all of the devices in the system by implementing the com.prosyst.mbs.services.spine.export.SPINEDeviceAccessHandler interface. It provides single method that allows a SpineDeviceAccess implementation to be attached to the SpineDeviceAccessHandler. This is intended to be used to allow the function to send notifications without the need to handle specific request but allows executing any valid SPINE request.

The four levels above are following the SPINE specification. Only the "SPINEDeviceAccessHandler" requires some explanation and showcasing. Here is an excerpt from the com.prosyst.mbs.spine.virtual-device-demo which implements the SPINEDeviceAccessHandler to get an instance of SpineDeviceAccess which is called deviceAccess. In the sample below the handler uses the deviceAccess to get all of the devices subscribed for changes in the Operation State and notifies them for any change:

void notifyOperationStateUpdated() {

    List<FeatureAddressType> subscribers = deviceAccess.getSubscriptions(featureAddress);

    CmdType cmdState = new CmdType();

    cmdState.setDeviceDiagnosisStateData(getDeviceDiagnosisState());

    PayloadType payload = new PayloadType();

    payload.getCmd().add(cmdState);

    for (FeatureAddressType addressDestination : subscribers) {

      DatagramType stateDatagram = new DatagramType();

      HeaderType header = new HeaderType();

      header.setAddressSource(featureAddress);

      header.setAddressDestination(addressDestination);

      header.setAckRequest(null);

      header.setCmdClassifier(CmdClassifierType.NOTIFY);

      header.setSpecificationVersion(SPINEConstants.CURRENT_VERSION);

      stateDatagram.setHeader(header);

      stateDatagram.setPayload(payload);

      SPINEDevice targetDevice = deviceAccess.getDevice(addressDestination.getDevice());

      targetDevice.send(stateDatagram);

    }

}

Request handling

When an incoming request comes the following verifications are performed:

1. The target device is determined using the address destination from the header. If this is missing the local device is chosen.
2. The target feature within the specified device is found, using the provided feature address.
3. Each of the function handlers is "asked" if the request can be handled by it, using the "isRequestSupported" method.
4. If some of the function handler declares that the specified request is supported it is "asked" to provide the response for this request.

For the cases when some of the components is missing the appropriate set of exceptions is prepared. Here is an example of a well defined function handler. It handles reading of DeviceClassificationManufacturerData and is part of the com.prosyst.mbs.spine.virtual-device-demo:

boolean isRequestSupported(FeatureAddressType sourceAddress, CmdClassifierType cmdClassifier, CmdType cmdRequest) {

    return cmdClassifier == CmdClassifierType.READ && cmdRequest.getDeviceClassificationManufacturerData() != null;

}

CmdType handleReadRequest(FeatureAddressType sourceAddress, CmdType cmdRequest) {

    CmdType cmdResponse = new CmdType();

    cmdResponse.setDeviceClassificationManufacturerData(getManufacturerData());

    return cmdResponse;

}

DeviceClassificationManufacturerDataType getManufacturerData() {

    DeviceClassificationManufacturerDataType result = new DeviceClassificationManufacturerDataType();

    result.setDeviceName("My Virtual Device");

    result.setDeviceCode("My Virtual Device Code");

    result.setSerialNumber("1234567890");

    result.setSoftwareRevision("1.1.0");

    result.setVendorName("Bosch.IO GmbH");

    result.setBrandName("Bosch.IO");

    return result;

}

As the isRequestSupported method shows this handler declares that it can handle only READ requests containing a DeviceClassificationManufacturerData element. After the verifications are performed and this handler is requested to process the request it provides the actual response through the handleReadRequest method. As it shows it just populates the DeviceClassificationManufacturerData with some hardcoded values because it has a demo purpose.

Virtual Devices and Destination List

The Exported devices are "visible" through the "DestinationList" function of the primary feature of the primary entity of the local device i.e. using the address of the machine where the SPINE module is running. For more information you can see "Chapter 7.2 Destination list" from the "EEBus SPINE Technical Specification - Protocol Specification".