Distrix Model: Organizing Object Instances

A model is an organizational structure for object instances, in which nested subdirectories provide you with a familiar structure in which to work, similar to a normal file system's directory structure. As you build your Distrix system, each time you have an agent publish an object, you also specify the location in the model where the object instance will be published.

The purpose of utilizing a hierarchical model for object publication is twofold:

First, rather than storing a flat structure of objects, model nodes encourage a logical organization of data.
Second, and more importantly, subscribing agents have the option to subscribe by model path, rather than specific object name. This type of subscription allows for non-named or "anonymous" publication-subscription relationships that are not necessarily one-to-one.

Distrix Model as Object-oriented Overlay

The Distrix model provides an object-oriented overlay that abstracts the underlying communication protocols and channels in the distribution of data among application components. From a designer's point of view, Distrix presents one or more physical networks as a single, logical network, which allows the designer to focus on the production and consumption of data rather than deal with the complex task of transporting data. Although a Distrix network is still subject to the properties of the underlying communications channels, including bandwidth and latency limitations, Distrix provides static and run-time interfaces to configure how these underlying channels are connected and used.

Implementing the object-oriented overlay is the Distrix Objects Service, which provides interfaces for object definition (such as its member variables and functions), publication of object instances, and subscription to object instances. To determine the relationships between publications and subscriptions, the Objects Service uses the structure of the Distrix model, which can be visualized much like a folder tree structure, although it is not literally composed of files and folders. This folder-like model structure can be pre-configured at design time or, for dynamic systems, configured at run time; the structure of the information model is completely up to the system designer.

The information model is composed of paths indicating where certain objects are published within the model, so one can think of the paths as analogous to uniform resource identifiers — they identify the location to which information is published and from where information is subscribed. All manner of logical groupings can be achieved by publishing and subscribing to the appropriate model paths.

When designing a Distrix system the primary tool is Distrix System Builder. This tool enables the designer to define:

The model structure
The object types that will be used within the model
The agents that publish and subscribe to the objects
The publications and subscriptions made by each agent

There are three levels of increasing design flexibility that can be employed by the designer.

Static model
In a static model approach, Distrix System Builder is used to define all publications and subscriptions using paths fixed at design time. This minimizes coding effort but does not permit any run-time alterations to the model. This approach is for systems with well-defined, fixed-point-to-fixed-point information flows and can be verified with static analysis tools in Distrix System Builder.
Configurable model
In a configurable model the designer defines the publications and subscriptions using Distrix System Builder and may also specify dynamic path nodes, the names of which can be set by calling the appropriate functions when the agent is starting up. The designer may also use wildcard characters in model paths to provide more general subscription. Agents subscribing to wildcard paths receive all objects of the specified type whose paths match the pattern.
Dynamic model
In dynamic models there are no predefined model paths. Distrix System Builder is used to create objects and agents and the developer directly calls the appropriate Distrix Client API functions at run time to dynamically create publications and subscriptions in the model.

All three of these approaches can be mixed and matched within a single Distrix system depending upon requirements.

Named and Anonymous Objects

Model nodes not only lend structure to your project, but also allow for subscription to objects within a model node. The model allows for two types of object instance: named and anonymous.

Named objects. By specifying an instance name, agents can subscribe to that specific named instance.
Anonymous objects. By not specifying an instance name, agents can subscribe via "wildcard" subscriptions. All anonymous objects of a given type in a node — and optionally sub-nodes — can be acquired by a subscription.

Limitations and Best Practices

While designing your model structure, keep these limitations in mind:

A model node can't contain two named objects of the same name, even if the objects are of different types.
A model node can contain many anonymous objects, even if they are of the same type.
A node's name can be no longer than 255 bytes. As well, System Builder restricts the length of some names to fewer characters due to filename length restrictions.
Model paths starting with /Distrix/ and object names starting with DX_ are reserved for internal Distrix use. Although you can subscribe to these paths and objects, the server will return an error if you attempt to create such a path or object.

Suggestions for best practices:

Functionally speaking, it's best to make proper use of a hierarchical structure rather than build on a single node in a flat structure. In particular, if you maintain only one node, you will likely run into difficulties regarding the duplication of object names.
Model nodes can allow for multiple instances of the same hardware configurations, in which each has its own identical node sub-tree.
As a rule of thumb, when naming model nodes, choose names that suggest the purpose of the path to which they are attached. Example: a node named aq3 does not provide a developer with any meaningful information about the node's purpose, while the name WaterTemperatureSensors does.

Example 1: Temperature Regulation System

The Temperature Regulation System Tutorial provides a simple example of how you can utilize the model structure for a small project. In the tutorial, agents publish three objects:

TemperatureValue: The value reported by a temperature sensor.
Thresholds: The temperature thresholds at which an air conditioning unit turns on and off.
AirConditionerControl: The required on/off state of the air conditioning unit.

These three objects can be sorted into two model nodes:

/Controllers/ contains AirConditionerControl and Thresholds.
/Sensors/ contains TemperatureValue.

This example taken from the temperature control tutorial shows object locations in the model structure.

A subscription to the object type TemperatureValue in /Sensors/ without specifying a specific instance allows an agent to read any TemperatureValue object in that location.

Example 2: Driving Robots

If you had a set of robots that have similar driving characteristics, each robot could have a copy of a driving agent. To control that agent you would publish new speed and turn rate data for that robot.

Where there are two robots, RobotA and RobotB, each node contains the objects Speed and TurnRate:

/Controllers/RobotA/
/Controllers/RobotB/

Agents can subscribe to objects that correspond to the appropriate robot

In this way, each driving agent can subscribe to the speed and turn rate objects in the model node that is specific to that robot.