Overview

One additional way to manage an OSGi device (also known as "client") is through Client Control Unit Agent. It allows control units residing on the OSGi device to be synchronized and managed on the RM (see Control Units and Device Representation for more conceptual information). The Client Control Unit Agent communication uses messaging.
The client control unit providers register org.mbs.services.cu.spi.ManagedControlUnit or org.mbs.services.cu.spi.ControlUnitFactory implementations on their devices (refer to Control Unit Doc). The RM provides a bundle named Control Unit Management Agent with content id: mprm.osgidm.control_unit_agent and symbolic name: com.prosyst.mprm.osgidm.clientcu.agent.
Once installed on an OSGi device the Control Unit Management Agent bundle starts providing control units registered on the client to the RM. The information is synchronized with RM only if devices are successfully registered on the RM. When connected:

• the control units (CUs) from the managed types are synchronized;
• the RM receives the events thrown by the CUs according to the default policies, described below.

The auto-synchronization could be divided into two types – structural (synchronizing the control unit id's and hierarchy) and state (synchronizing the state variables).
According to the configuration:

• control units are synchronized with the RM – their information is stored persistently on the RM and that information is synchronized;
• events (for state variable change for instance) – they are dispatched to the RM and made available for dynamic processing;
• history and statistics for the state variable changes – can be recorded in order to track the state variable behavior through time.

Client CU Configuration

Since the synchronization is entirely made in favor of the RM, it is the one that has to do the runtime configuration about which parts of the CU state to synchronize with and which mode.
The RM provides and combines several configurations for Client CUs as the one that comes from the Client CU module itself is called The Client CU Module Configuration.

Configuration Providers

The Client CU Agent is configured through setting the device node properties. There are different configuration providers allowed, which are defined by the mprm.clientcu.configProviders system property – a comma separated list of provider types, set by default to mprm.clientcu.configProviders ="sync,history,stats". In this way there are three configuration providers supported by default:

• sync – the Client CU Module provider,
• history – the CU History provider,
• stats – the CU Statistics provider.

Additional providers can be supported by including them to the list of the provider types, e.g. mprm.clientcu.configProviders ="sync,history,stats,info".
There is a pattern for every configuration property of the Client CU Agent and all the properties that mach a pattern are united to define the value of the configuration, e.g. by default clientcu.events.var.offline Client CU Agent property is combined value from values of the clientcu.events.var.offline.sync, clientcu.events.var.offline.history and clientcu.events.var.offline.stats node properties.
Each default or additional provider supports some or all properties of the following type:

• clientcu.managed.types.<config provider type>
• clientcu.events.cu.offline.<config provider type>
• clientcu.events.cu.skip.<config provider type>
• clientcu.events.var.offline.<config provider type>
• clientcu.events.var.skip.<config provider type>
• clientcu.events.var.skip.frequent.periods.<config provider type>
• clientcu.events.var.poll.periods.<config provider type>.

Configuration Properties and Policies

Managed Types

The main configuration setting is the Managed Types configuration – it uses the clientcu.managed.types.<config provider type> properties to define which control unit types will be managed. This configuration setting is taken into account while determining any status or state event policy. If a type is not a managed one – events for its control units will not be transmitted to the RM.

Structural Synchronization Configurations

The structural synchronization of the control unit supports the following policies:

• sync cu all – all structural events (online and offline) are sent to the RM. This policy is set with LDAP String[] filters got from node settings matching pattern clientcu.events.cu.offline.*.

• sync cu online – the offline structural events are skipped and only the online structural events are delivered to the RM. This policy is applied if an event does not match sync cu all and don't sync cu policies. This is the default policy. The changes will be synchronized with the RM only if the device is connected to the RM.

• don't sync cu – in this case the user/RM does not receive any change events from control units of that type (i.e.. only the state events from the synchronization when connected). Event synchronization is not available on demand. This policy is set with LDAP String[] filters provided by node settings matching pattern clientcu.events.cu.skip.*.

  
  

State Synchronization Configurations

Orthogonally to the above strictural synchronization policies, for the state variables there are:

• sync var all – all state variable events of managed types (online and offline), are sent to the RM (i.e. no events are skipped). This policy is set with LDAP String[] filters node got from settings matching pattern clientcu.events.var.offline.*;

• sync var online – offline variable events are not sent to the RM; events will be sent to the RM only if thrown while the device is online. This policy is applied if a variable event does not match its sync var all or don't sync var policies. This is the default policy;

• don't sync var – no variable events are synchronized with the RM. This policy is set with LDAP String[] filters received from node settings matching pattern clientcu.events.var.skip.*, with which some of the state variable events can be skipped.

  
  

There are also:

• could skip too frequent – if there are too many events into an interval/period, some of them could be skipped to prevent flooding the RM with probably useless events. It is configured with node settings clientcu.events.var.skip.frequent.periods.*. The settings have to be arrays in format <LDAP Filter>: <period in milliseconds>. Such an entry means, that for matching (LDAP Filter) state variables you could send only the last event in the interval of <period> milliseconds.

• don't skip var frequent – all events, including the too frequent ones, are delivered to the RM. Under this (default) policy are those change state variable events that do not match the could skip too frequent policy.

• polling state vars – it is configured via Poll Period property – clientcu.events.var.poll.periods.*. The matching variables are polled at a certain time in order to be forced to generate events. As frequency skipping, their format is: arrays in format <LDAP Filter>: <period in milliseconds>.

  
  

Matching

Depending on the Client CU Agent configuration property dictionaries representing the CU event or CU type are matched against the LDAP filters. These dictionaries (hence the LDAP filters) could contain the following keys:

• type – a key for control unit type;
• id – a key for the control unit id;
• var – a key for variable id or
• stateVar:<var id> – a key for the current value of a control unit's state variable.

The applicable keys for the properties are:

• for the Managed type property:
• clientcu.managed.types.<config provider type> – type;
• for the Structural synchronization properties:
• clientcu.events.cu.offline.<config provider type> – type, id, stateVar:<var id>;
• clientcu.events.cu.skip.<config provider type> – type, id, stateVar:<var id>.
• for the State synchronization properties without pooling:
• clientcu.events.var.offline.<config provider type> – type, id, var , stateVar:<var id>;
• clientcu.events.var.skip.<config provider type> – type, id, var , stateVar:<var id>;
• clientcu.events.var.skip.frequent.periods.<config provider type> – type, id, var , stateVar:<var id>.
• for the State synchronization pooling property:
• clientcu.events.var.poll.periods.<config provider type> – type.

The Client CU Module Configuration

The following configuration comes from the Client CU module itself and provides the properties with suffix "sync" and their corresponding display name:

• clientcu.managed.types.sync -> Managed Types Filter
• clientcu.events.cu.offline.sync -> CU Events Offline Sync Filter
• clientcu.events.cu.skip.sync -> CU Events Skip Filter
• clientcu.events.var.offline.sync -> State Var Events Sync Offline Filter
• clientcu.events.var.skip.sync -> State Var Events Skip Filter
• clientcu.events.var.skip.frequent.periods.sync -> Skip Frequent State Var Events
• clientcu.events.var.poll.periods.sync -> Poll Periods