This document describes the main principles in providing new device types or types of device components to the RM device management tree.

Overview

The device management model of RM is based on controlling devices and their manageable components by using their representation as control units. This allows unified view of all device types in the system.

Devices are generally under the control of the Generic Device Manager, which on its behalf allows remote applications to issue commands to devices, such as registering new devices, synchronizing their state, etc. Besides the very devices, remote applications can manage specific components of specific devices.

Device Control Unit Providers and Component Control Unit Providers are responsible for mapping, respectively, devices and device components to control units of specific types. All providers are registered as OSGi services on backend hosts with the "management server" role, and are automatically detected by the Generic Device Manager at the moment of registration.

The goal of Control Unit Providers is to transform the device-specific information into control unit instances (collections of state variables and actions), and vice-versa. The interface of a specific control unit type is described by metadata in compliance with the OSGi Metatype Specification and the Metatype API.

Each control unit managed in this way communicates with exactly one CU Provider. The provider for each device type or component type should be able to handle the device protocols, connections, etc., and should know how to manage the control unit information for this device or component on the basis of the reported device information.

More information about the role of control units in RM is available in Conceptual Guide.

Control Unit Provider SPI

RM defines two SPIs (service provider interfaces) for implementing a Control Unit Provider depending on if the provider is for a device root type or for a device component type:

  • Device Root Control Unit SPI – its components are in the com.prosyst.mprm.backend.ms.cu.spi.root package.

  • Component Control Unit SPI - its components are in the com.prosyst.mprm.backend.ms.cu.spi.component package.


Both SPIs derive from the components of the com.prosyst.mprm.backend.ms.cu.spi package.

The Control Unit Provider SPIs are available on a backend framework having the management server role. They are exported by the RM Control Unit Lib bundle (packages/gdm/gdmlib.jar) and are handled mainly by the Control Unit Manager bundle (packages/gdm/cu.jar).

During development, you can also use the lib/api/gdm-api.jar JAR file for compilation and for code complete in a Java editor.

Summary of Development Tasks

Basically, you need to provide the following aspects in your CU Provider implementation:

  • Communication with the backend device management subsystem

  • Assigning unique control unit IDs in the scope of the control unit type

  • Device characteristics-to-control unit metadata transformation

  • Creation and destruction of control units if user-initiated registration will be supported

  • Up-to-date information about the control unit state

  • Association of control unit actions with the actual underlying device- or component-specific functions

  • Synchronization of a control unit state with the underlying device or component

  • Registration of the CU Provider implementation as an OSGi-compliant service.

Common Guidelines for Implementing a CU Provider

Providing the Control Unit State

You create the control unit representation of a device root or a device component at a particular moment of time in a com.prosyst.mprm.backend.ms.cu.spi.ControlUnitState object. The CU Provider should return a ControlUnitState object in the following cases:

  • When creating a control unit instance

  • When the system calls the CU Provider to get the state of a control unit on request from the user

  • When the system asks the provider to synchronize a control unit's state.


The ControlUnitState object contains the information about:

  • The ID of the control unit, represented as a com.prosyst.mprm.admin.devices.ControlUnitID object.

  • The list of the unit's state variables, which form the control unit state interface. It can be retrieved from the metatype of the control unit type.

  • The current values of state variables.

Callback to the Device Management System

RM provides a callback interface to Control Unit Providers, providing several types of functionality:

  • Can be used it to store persistently tree and control unit information in the Device Tree Database and the Control Unit Database, as well as in the Component Tracker.

  • Carries the result from executing control unit actions including predefined actions (create, destroy, find) and custom type-specific actions.

  • Enables Control Unit Providers to notify RM of newly created control units, of destroyed control units and of changes in a control unit's state. Next, the system forwards the events to listeners registered by RM administration applications through the Generic Device Manager API (see the Common Management Principles guide).


The callback interface is generally represented by the com.prosyst.mprm.backend.ms.cu.spi.ControlUnitSystemContext interface. Each Control Unit Provider receives an instance of the interface with extended features depending on the provider's type (device root or component).

The system context is supplied by the system once the provider is registered in the OSGi framework by calling its init method with the system context as argument.

To indicate to the provider that it should terminate its work and release all occupied resources for maintaining its control units, the system calls the init method with null argument. Such a situation will emerge when stopping the system (including restarts of system bundles) as well as when the system ignores specific control unit types due to external configuration.

With regard to action execution, the interface of the device management system to Control Unit Providers is asynchronous to meet the case when it is expected the execution on the underlying resources to be time-consuming, especially in cases of remote calls to a physical device. Asynchronous action invocation allows increasing system's efficiency by implementing providers in such a way that there are no blocking long time device calls. Of course, providers can respond to system calls in a synchronous way by applying the result before the corresponding caller method returns. The results from action execution should be delivered in a com.prosyst.mprm.backend.ms.cu.spi.ProviderResult or a com.prosyst.mprm.backend.ms.commands.spi.InterpretationResult object, available as an argument to the provider's methods.

Control Unit Providers as Command Interpreters

RM supports definition and execution of tasks over specific devices (see Scripting and Rule-Based Management conceptual guide).

Generally, commands can be separated in control unit commands and custom commands. control unit commands define the generic control unit management actions – action invocation, creation, destruction and synchronization. The Operation Manager redirects the interpretation of custom commands to custom command interpreters, and considers Control Unit Providers as command interpreters for the control unit commands. There is a difference between interpreting usual (instant) control unit action invocation and interpreting action invocation in operation. Operation executions are persistently pended, and if the device is not available to execute it, the invocation should not finish with error, but should stay pending and executed when it becomes possible.

For more information about supporting action invocation operations, refer to the "Support Action Invocation" sections of the Extending RM with a New Device Type and Extending RM with a New Component Type guides.

References