The RM Control Unit APIs allow developers to access and manage devices and their components from applications remote to the RM backend or from custom backend bundles.

The common principles and concepts of RM device management are described in Conceptual Guide and in the Device Management Overview document from Programmer's Guide.

Overview

The device-scoped management model, introduced in the Common Management Principles document, defines that applications built on top of it are operating with device's components represented as component control units only in the scope of a particular device root - there these components are presumed to be unique.

The device-scoped model includes two entities for component management:

  • Remote CU Admin (org.mbs.services.cup.radmin.RemoteCUAdmin) – Adapts the generic model for control unit administration defined for device OSGi frameworks to the model used in RM's Generic Device Management Framework. Remote CU Admin extends the simple functionality of the generic Control Unit Admin ( org.mbs.services.cu.ControlUnitAdmin). Regarding communication resources, the use of Remote CU Admin will result in synchronous requests and greater amount of transmissions.

  • Control Unit Proxy (org.mbs.services.cup.ControlUnitProxy) – Offers an alternative to Remote CU Admin having the same functionality but this time based on asynchronous calls to consuming applications - requests are accumulated until explicitly executed and the result is delivered back to the requesting application by calling certain application's methods. Control Unit Proxy provides more efficient opportunities for remote management of control units.


Both Remote CU Admin and Control Unit Proxy can be obtained from the Device Manager (com.prosyst.mprm.admin.devices.DeviceManager), which is the main point for access to the control unit management capabilities of RM.

Getting the Device Manager

To be able to get and use Remote CU Admin or Control Unit Proxy, first you need the Device Manager (com.prosyst.mprm.admin.devices.DeviceManager). A reference to DeviceManager can be requested by a backend bundle residing in a RAS OSGi framework or in the CC OSGi framework or by an application running a RAC as described in "Getting the Device Manager" section from Common Management Principles guide.

Using Remote CU Admin

An org.mbs.services.cup.radmin.RemoteCUAdmin instance for a specific device root allows management of component control units as if using the generic Control Unit Admin (see the API documentation). The RemoteCUAdmin extends org.mbs.services.cu.ControlUnitAdmin with methods for getting control unit metadata and registration/unregistration of event listeners.

Getting Remote CU Admin

To get a device-specific RemoteCUAdmin, call the getCUAdminToComponentsOf(String deviceType, String deviceId) method of the Device Manager providing appropriate device type and device ID.

Getting Control Units and Their Metadata

Getting Control Units

Getting component control unit types and particular control units can be done by using RemoteCUAdmin's methods inherited from org.mbs.services.cu.ControlUnitAdmin:

  • To get available control units types, use the getControlUnitTypes(). To trace a hierarchy of control units, use the getParentControlUnitTypes and getSubControlUnitTypes methods.

  • To get control units of a particular type, use the getControlUnits or the findControlUnits method. For parent or child control units, use respectively getParentContrlUnits or getSubControlUnits.

Getting Control Unit Metadata

You can get the metadata related to a control unit interface by calling the getMetadata method of the Remote CU Admin. This method returns an org.osgi.service.metatype.MetaTypeProvider instance representing the metatype of the control unit interface. Further details on the structure of such a MetaTypeProvider are discussed in Control Unit Metatyping.

Invoking Actions and Querying State Variables

The mechanism that the Remote CU Admin offers for invoking actions of the component control unit and for querying it for the current values of its state variables. It relies respectively on the invokeAction method and on the queryStateVariable method of org.mbs.services.cu.ControlUnitAdmin.

Listening for Control Unit Events

The Remote CU Admin provides separate methods for listener registration and unregistration in order to receive events for control units handled by the relevant device.

Subscribing for Control Unit Events

Control unit listeners listen for newly-registered or destroyed control unit types and instances within the scope of the associated device. Type events in regard to the Remote CU Admin are equivalent to the system-wide type events arriving for the components in the scope of the target device (refer to the "Control Unit Listeners" section from System-Wide Device Management).

A control unit listener is registered using the registerControlUnitListener(org.mbs.services.cu.ControlUnitListener cuListener, Dictionary cuListenerProps) method of RemoteCUAdmin. The method takes the following arguments:

  • cuListener – The instance of your ControlUnitListener implementation that will receive control unit events

  • cuListenerProps – Properties for filtering the control units to receive events about. The cuListenerProps can have the following keys:

    • org.mbs.services.cup.radmin.RemoteControlConstants.EVENT_FILTER – A String representation of an LDAP filter for specifying component control unit types and IDs to receive events from. Filtering is done on the basis of the RemoteControlConstants.TYPE, RemoteControlConstants.ID , RemoteControlConstants.VERSION and RemoteControlConstants.EVENT_TYPE  search attributes.

      A control unit listener with no filter specified receives all types of events for all control units.


The org.mbs.services.cu.ControlUnitListener has a single method, controlUnitEvent(ControlUnitEvent cuEvent), called by the Control Unit Manager when a new event is available.

Subscribing for State Variable Events

State variable listeners listen for changes in the values of the state variables of control units. Such a listener is registered using the registerStateVariableListener(org.mbs.servics.cu.StateVariableListener l, Dictionary svListenerProps) method of RemoteCUAdmin.

  • The svListener parameter represents the instance of the your StateVariableListener implementation that will process received state variable events.

  • The svListenerProps parameter contains the listener's properties for filtering, which are similar to the ones of the control unit listener discussed above. In addition to these common filter attributes, a state variable listener can also specify the IDs of state variables of interest by including the org.mbs.services.cup.radmin.RemoteControlConstants.STATE_VARIABLE_ID search attribute in the RemoteControlConstants.EVENT_FILTER filter property.


The org.mbs.services.cu.StateVariableListener has a single method: stateVariableChanged(StateVariableEvent svEvent), called by the Remote CU Admin when a new event suitable for this listener comes.

Subscribing for Hierarchy Events

Hierarchy listeners receive events for changes in the hierarchy of specific control units. You can register a hierarchy listener by calling the registerHierarchyListener method of the RemoteCUAdmin. Similarly to the methods for registration of control unit listeners and state variable listeners you should provide as arguments the org.mbs.services.cu.HierarchyListener instance that will receive the events and the listener registration properties. Besides the control unit type, ID and version, the LDAP filter of the org.mbs.servics.cup.radmin.RemoteControlConstants.EVENT_FILTER registration property can contain the following search attributes:

  1. org.mbs.servics.cup.radmin.RemoteControlConstants.EVENT_TYPE – Specifies whether to receive events for attached or detached parents of a control unit, or for both. This attribute can be related to

  2. org.mbs.services.cu.HierarchyListener.ATTACHED or

  3. org.mbs.services.cu.HierarchyListener.DETACHED

  4. org.mbs.servics.cup.radmin.RemoteControlConstants.PARENT_TYPE and org.mbs.servics.cup.radmin.RemoteControlConstants.PARENT_ID – Specify the type and ID of parent control units for whose subcomponent to receive events.


The org.mbs.services.cu.HierarchyListener owns a single method, hierarchyChanged, which the Remote CU Admin calls when there are changes in the hierarchy of the watched control units.

Creating, Destroying and Searching for Control Units

If defined by the respective Control Unit Provider, you can create, destroy or search for a component control unit by using the provider's constructor(s), destructor and finder(s) actions. Use the following methods of the Remote CU Admin:

  • createControlUnit for calling a specific constructor

  • destroyControlUnit for calling the provider's destructor

  • findControlUnits for calling a provider's finder

Using Control Unit Proxy

As previously discussed, the Control Unit Proxy (org.mbs.services.cup.ControlUnitProxy) provides the data resulting from the communication with the Control Unit Providers to its caller applications via asynchronous calls to the applications.

The methods of ControlUnitProxy simply prepare data for the requests and responses. Requests are sent only after the send or sendSync method of ControlUnitProxy is called.

The usage of the Control Unit Proxy implies that your application provides a org.mbs.services.cup.RemoteControlUnitAdminApplication which will receive callbacks from the proxy in order to process received results in an asynchronous way. The RemoteControlUnitAdminApplication interface contains methods for the main functionality aspects in component control unit management.

Each request to the Control Unit Proxy is identified with a request ID. The same request ID is then passed to the corresponding callback method of the RemoteControlUnitAdminApplication.

Getting Control Unit Proxy

To get the ControlUnitProxy for a device, call the getCUProxyToComponentsOf(String deviceType, String deviceId, RemoteControlUnitAdminApplication remoteApplication) method of the Device Manager. The getCUProxyToComponentsOf has the following arguments:

  • deviceType – The device type of the target device within RM.

  • deviceId – The device ID of the device root in the RM system.

  • remoteApplication – The instance of your RemoteControlUnitAdminApplication implementation which will receive and process results of control unit management requests.

Getting Control Units and Their Metadata

Getting Control Units

To get the types of component control units registered for the device, use the getControlUnitTypes method.

To get control units of a particular type, use the getControlUnits or the findControlUnits method. After the "get" request is launched for processing with the proxy's send method, the proxy will provide the result to the RemoteControlUnitAdminApplication by calling the application's processReceiveControlUnits. The Control Unit Proxy will pass an array of org.mbs.services.cup.data.ControlUnitInfo objects, each of them allocated for a specific control unit. For the associated control unit instance a ControlUnitInfo object can contain the type, ID, interface (the set of state variables), checksum and ControlUnitInfos of its parents.

You can use the state variable information in a ControlUnitInfo to avoid parsing the metadata for the corresponding control unit interface.

The arguments of the getControlUnits and findControlUnits methods can be combined to have different data provided in the ControlUnitInfo[] cunits parameter of the application's processReceiveControlUnits method:


Method Argument

Result Description

String[] cuIds

You can receive information in the form of ControlUnitInfo objects only for control units with specific IDs.

int cuMode

According to the specified cuMode, you can get three kinds of control unit information:

  • ControlUnitInfo.ID – The Control Unit Proxy fills passed ControlUnitInfo objects only with the IDs of the control units.

  • ControlUnitInfo.STATE – The Control Unit Proxy returns a unit-specific ControlUnitInfo object holding its state variables, which form the unit's interface and whose values indicate the unit's state.

  • ControlUnitInfo.CHECKSUM – The Control Unit Proxy returns a unit-specific ControlUnitInfo object, which also includes a checksum calculated on the basis of the unit's state variables and their values.

String[] svNamesList

You can get ControlUnitInfo objects having information only for specific state variables.

boolean parentInfo

If set to true, the ControlUnitInfo for a control unit will also include information about its parents.


You can retrieve parent or child (sub) control units by using respectively the getParentControlUnits or getSubControlUnits method of the Control Unit Proxy.

Getting Control Unit Metadata

To receive the metadata of the interface of a control unit type, call the getMtaType method of ControlUnitProxy. When the system returns requested data, the proxy will invoke the processControlUnitMetaType of your RemoteControlUnietAdminApplication. As the metaTypeProvider argument value, the proxy will provide the Metatype Provider for the control unit interface. See Control Unit Metatyping for more details on the structure of a control unit metatype.

Querying State Variables

You can query the state variables of a control unit for their values by using the corresponding ControlUnitInfo, previously retrieved with mode ControlUnitInfo.STATE.

To get the state variable IDs of the control unit, call the getInterface method of the ControlUnitInfo. Then, to get the values of a certain state variable, use the getValue method of ControlUnitInfo.

Using State Checksums

The Control Unit Proxy allows to identify a specific state of a control unit by using checksums. For instance, you can store checksums for predefined states of a control unit. When the control unit changes its state, you can compare the checksum for the control unit with the stored ones and quickly distinguish its new state.

To get the current checksum of a control unit:

  1. Make request to get the control unit information in mode ControlUnitInfo.CHECKSUM (see "Using Control Unit Proxy: Getting Control Units" subsections above)

  2. Call the getCheckSum method of the provided ControlUnitInfo object.


You can also calculate the checksum for a control unit state from a ControlUnitInfo object in STATE mode by calling the calcCheckSum static method of ControlUnitInfo.

Invoking Actions

With the help of the Control Unit Proxy, you can invoke actions on a control unit instance by using the proxy's invokeAction method. The proxy will return the invocation result back by calling the processInvokeActionResult method of your RemoteControlUnitAdminApplication. The action result is represented by the Object invocationResult method argument.

Listening for Control Unit Events

The Control Unit Proxy provides a general mechanism for event subscription based on ready-to-use event subscription entries, each identified by a subscription ID.

To subscribe for specific events, call the subscribe method of the Control Unit Proxy providing instances of org.mbs.services.cup.data.CUEventSubscription, org.mbs.services.cup.data.SVEventSubscription and/or org.mbs.services.cup.data.HEventSubscription for receiving respectively control unit events, state variable events and/or hierarchy events.

Subscribing for Control Unit Events

As previously discussed, to receive control unit event, you should subscribe a CUEventSubscription instance in the Control Unit Proxy by calling the proxy's subscribe method.

To instantiate CUEventSubscription, you need to pass the following parameters to the constructor, related to the general listener registration and notification mechanism for control units:

  • listenerRegProps – A Dictionary containing the following keys:

    • org.mbs.services.cu.ControlConstants.EVENT_FILTER - A String representation of an LDAP filter for specifying control unit types and IDs to receive events from. Filtering is done on the basis of the org.mbs.services.cu.ControlConstants.TYPE, org.mbs.services.cu.ControlConstants.IDorg.mbs.services.cu.ControlConstants.VERSION , and org.mbs.services.cu.ControlConstants.EVENT_TYPE search attributes.

      A control unit listener with no filter specified receives all types of events for all control unit

  • receiveCUStates – A flag indicating if the events to be delivered should contain information about the state variables of the associated unit in addition to the control unit type and ID.

  • receiveParentsInfo – A flag indicating if the events to be delivered should contain information about the parents of the control unit the event is for.


When a control unit event is called, the Control Unit Proxy will notify subscribed applications by calling the processControlUnitEvent method of their RemoteControlUnitAdminApplication entities. Depending on the EVENT_TYPE filter attribute, the application can receive events of type:

  • org.mbs.services.cu.ControlUnitListener.CONTROL_UNIT_TYPE_APPEARED

  • org.mbs.services.cu.ControlUnitListener.CONTROL_UNIT_TYPE_DISAPPEARED

  • org.mbs.services.cu.ControlUnitListener.CONTROL_UNIT_ADDED

  • org.mbs.services.cu.ControlUnitListener.CONTROL_UNIT_REMOVED


Type events in regard to the Control Unit Proxy are equivalent to the system-wide type events arriving for the components in the scope of the target device (see "Control Unit Listeners" section from System-Wide Device Management guide).

Subscribing for State Variable Events

The RemoteControlUnitAdminApplications can receive events for changes in the values of specific state variables. This kind of subscription can be done by calling the subscribe method of ControlUnitProxy providing a SVEventSubscription instance with proper attributes assigned in its constructor:

  • listenerRegProps – A Dictionary holding properties for event type filtering and synchronous delivery as described for control unit event subscription above. In addition to these common subscription attributes, a state variable subscription can also have the IDs of state variables of interest by including the org.mbs.services.cu.ControlConstants.STATE_VARIABLE_ID search attribute in the ControlConstants.EVENT_FILTER filter property.

  • expiredEventsFilter – Has the same meaning as for control unit event subscription (see "Using Control Unit Proxy: Subscribing for Control Unit Events" subsections above).

  • eventTimeout – Has the same meaning as for control unit event subscription (see "Using Control Unit Proxy: Subscribing for Control Unit Events" subsections above).


When a state variable event comes, the Control Unit Proxy notifies registered RemoteControlUnitAdminApplications by calling their processStateVariableChanged method.

Subscribing for Hierarchy Events

Another type of events that the Control Unit Proxy is capable of delivering to RemoteControlUnitAdminApplications are hierarchy events related to changes in the parent-child relations within a certain control unit hierarchy. Interested applications can subscribe for such events by calling the subscribe method of ControlUnitProxy with an HEventSubscription instance populated with proper attributes:

  • listenerRegProps – A Dictionary holding properties for control unit type and ID filtering and synchronous delivery as described for control unit event subscription above. In addition to these common subscription attributes, a hierarchy subscription can also have the following attribute in its org.mbs.services.cu.ControlConstants.EVENT_FILTER filter property:

    • ControlConstants.EVENT_TYPE – Can be related to org.mbs.services.cu.HierarchyListener.ATTACHED or org.mbs.services.cu.HierarchyListener.DETACHED.

    • ControlConstants.PARENT_TYPE and ControlConstants.PARENT_ID – Specify the type and ID of parent control units to receive events for.

  • expiredEventsFilter – Has the same meaning as for control unit event subscription (see Using Control Unit Proxy: Subscribing for Control Unit Events subsections above).

  • eventTimeout – Has the same meaning as for control unit event subscription (see "Using Control Unit Proxy: Subscribing for Control Unit Events" subsections above).


When a hierarchy event comes, the Control Unit Proxy notifies registered RemoteControlUnitAdminApplications by calling their processHierarchyChanged method.

Creating, Destroying and Searching for Control Units

If the respective Control Unit Provider, associated with a specific control unit type, supports constructors, a destructor or finder actions, you can call them remotely through the Control Unit Proxy and process the result in a RemoteControlUnitAdminApplication.

Call the following ControlUnitProxy methods:

  • createControlUnit for calling a specific constructor

    The Control Unit Proxy will deliver the result to your RemoteControlUnitAdminApplication by calling its processCreateControlUnitReply method.

  • destroyControlUnit for calling the provider's destructor

    The Control Unit Proxy will deliver the result to your RemoteControlUnitAdminApplication by calling its processDestroyControlUnitReply method.

  • findControlUnits for calling a provider's finder

    The Control Unit Proxy will deliver the result to your RemoteControlUnitAdminApplication by calling its processReceiveControlUnits method.