Model of the control object

Model of the control object is a formalized representation of devices logic and hardware functions managing the object of control. The model has a tree-like structure containing subsystems, arguments, events, and actions.

A primary assignment of the model consists in increasing of an abstraction level from protocols and hardware realization to legible, human-transparent object function names. It makes the work of a programmer easier relieving from the necessity to explore the protocol. The data processed in this way take the shape of the RESTful API request in JSON format, which is handy for mobile application developers.

The device model figures in processes of data serialization and deserialization, data normalization, interface rendering, also in automation scripts and data processing chains.

There is no need to create the model for each of the same object type. The once created model may be used for both one and several objects if they keep a similar set of identified parameters and executed functions.

Device Model Parameters

The process of describing the model of the object of control consists in determining the parameters of the model in the form of the following nodes of the tree structure:

• arguments are the parameters which values are transferred by the object of control in the system from sensors. The arguments may have number, string, boolean data type, represent an object or an array. What is more, it is able to point an unit of measure for the number arguments;
• events are committed actions that either was independently recorded by the object of control itself and, in accordance with established behavior logic, were sent in the system, or occurred in external applications also participating in a business process;
• actions are operations that the device performs. They divide into several types:
  • command to the device is a command on which it is able to react and which is performed by the device;
  • automaton is a scenario of automation which allows building the device behavior logic;
  • custom action (serverless) is an action which is not included in the command set of external software modules and which user can create in the purpose of the custom action applying in his own final state machine in preparing the business logic;
• subsystem is not a configurable type of node which serves for the model structure organization allowing to unite parameters in groups.

In establishing new commands, parameters, and events in the model, “inheritance” is always performed from the basic protocol. To create a new command, it is necessary to “inherit” from the basic command of the protocol on which the device operates, and enter the arguments with which the one or several commands will execute. In a similar way, it works for the events and the parameters. For example, if data is transmitted from the device to the platform and back via the MQTT protocol, it is necessary to specify the data source for the arguments. In the case of MQTT, this source is called a topic by which the data is transmitted.

For the convenience of subsequent use of the model parameters newly created, it is better to give them associative names. The identifier of the parameter is applied for normalization in JSON as an argument key. Eventually, the structure of data acquired as a result of the normalization will correspond with the model structure.

Due to the models, the hardware operating according to different protocols, but installed in the similar objects of control, may be used in one scenario of automation. By comparing the identifiers of nodes with the model structures, the platform will normalize data in equivalent JSON objects.

Model configuring

The process of model configuring represents the creation of a tree-like structure consisting of parameters. At the same time, the parameters are set from the basic functions of the protocol by which the device works.

Configuring of the model for specified protocols is considered in the section of examples.

ATTENTION! If a user does not have appropriate access rights to the device model, which is assigned to the control object, the rendering of interfaces associated with the data viewing will not be performed.

The virtual model creation of a physical device includes such steps:

1. To enter the “Models” menu.
2. To invoke the dialogue box of the control objects model creation.

Following that, it is necessary to fill the next fields:

• Name is the model name;
• Description is a detailed presentation of the model which can be added if desired;
• Template is a prepared structure of the model. Several ready templates created on the base of protocols realized in the platform were added to the platform. Such templates allow making the process of configuration more handy and quick because all necessary parameters are prepared in them in advance. In dependence on which protocol will be used for data transmission, the appropriate template is chosen. It can be MQTT, Wialon IPS, or RIC HTTP which is applied for sending of HTTP requests and data transmission by internal HTTP API.

The model of widely spread protocols, such as MQTT, offers an example structure only, in any case, the user will have to modify it for yourself. In the event of a proprietary protocol, for example, Wialon IPS, the model already represents the structure ready for use.

In the case of a proprietary protocol, for example, Wialon IPS, the model is already a ready-to-use structure that includes a complete list of necessary arguments and actions.

After clicking the “Create” button, a new model will be created. Now the user can start to configure it.

By default, the created model will look like this:

MQTT

RIC HTTP

Wialon IPS

The external software modules are added to the model by default. They represent the list of pre-established functions that describe a business process in a logic template. The external software modules include:

• base commands (ric-gate), the possibility to recognize them and respond to them;
• registration or fixation of steps of automation scenarios execution (committing of transitions, registration of the current object state, etc.);
• timers and schedulers that offer the possibility to set time stamps and other time-related conditions when describing the logic template;
• geo zones that intended for the control object realization, registration of its entering, or leaving some geographical area defining the object location.

Any the model node may be deactivated by deselecting the checkbox. After that, the system will stop to process the node.

It is possible to add new parameters by clicking on + icon. Notably, the new parameter will be a branch from the node from which the building of this parameter occurred (i. e. the new node will be lower on one level then initial). Besides that, the parameter can be deleted, or the analogous one can be created by copying. All nodes of the structure are free to rename.

Common parameters

• type: the node can be configured as the subsystem, the argument, the event or the action. Depending on the chosen type, there will be offered corresponding separate fields to fill in (see below);
• identifier: it is generated automatically by the system itself. The identifier is used for indicating the node in the system. It may be changed by the user. The identifier is the name of the field for an internal device state accessed through API.
• name: it is used for displaying of the device name in all the platform sections;
• description: it provides a brief representation of the parameter. It is convenient to use the description in preparing the final state machine where it will display as a tooltip on mouseover.

Argument

• write to: this is the writing of current values in the state or configuration of the object;
• data type: one of the possible variants is chosen. It can be the number, the string, the boolean type, the object or the array;
• source: the searching of the value in the initial structure of the protocol realizes by the source. For instance, in the case of data transmission by MQTT, a topic should be entered in this field;
• linear: by selecting this checkbox, the adding of the current parameter icon and pointing of the parameter current value indication levels become available.

The tabs “On parse” and “Display” open the additional fields.

• factor: if the number data type was chosen, the argument value would be multiplied by the factor;
• unit of measure: it is used only for displaying in all the platform section;
• icon: it is set in the SVG format that will represent the current parameter in the side menu of the objects graphically;
• levels: to indicate the current value of the parameter, it is able to set several colors in the form of numerical thresholds every of which will be compared to its own value range.

Action

• execute: here the type of action is chosen that is necessary to be executed;
• in the case of choice of an automaton or a custom action (serverless), in the last field should be pointed such automaton or action that are necessary to be executed;
• in the event of a command of device selection, the message publication is specified in the Send field, after that, the corresponding parameters are pointed:
  • topic by that the command must be transferred to the device in the message shape;
  • payload that contains the transmitted message text (for example, in case of the message transmission in the JSON format, a key and a value are specified for each parameter the values of that should be transferred to the platform and displayed in its graphical interface);
  • reply to: the answer to the delivered message may be sent on the topic pointed in the last field.