Object Models
The following object models are supported in Modbus.
There are two distinct situations where you would want to create DPIs based on a custom defined Object Model:
- Where you can model the entire Modbus device as data point with properties representing registers.
- Where you can model a register as a data point with properties representing parts of the register's bytes (see Choice of Custom Object Models over the Standard Object Models that describes a use case).
In both the cases you must define the object model, however you need to handle the Import Rules with a difference.
Design of Custom Object Model
Before you begin with creating your custom object model, you need to identify the properties and their data types. Usually, this is done after determining the application characteristics. For example, an electrical meter may offer measurement and configuration parameters. Using the datasheet or engineering manual of the product, you can determine the register address, data type, engineering units, range, and so on. The object model is initially formulated in a CSV file based on which parameters of the device you want to integrate and its data type. The formulation can then be imported into the management station and extended with information like engineering units and range.
Structure of the Custom Object Model Template
The structure of the device can be defined in terms of the object model. Consider the following hypothetical datasheet for a Meter Type XY.
Property Name | Registry Address | Data Type | Direction |
Voltage Phase 1 | 40001 | Float | Output |
Voltage Phase 2 | 40003 | Float | Output |
Voltage Phase 3 | 40005 | Float | Output |
Current Phase 1 | 40007 | Float | Output |
Current Phase 2 | 40009 | Float | Output |
Current Phase 3 | 40011 | Float | Output |
Total Power | 40013 | Float | Output |
Total Power Apparent | 40015 | Float | Output |
Total Power Reactive | 40017 | Float | Output |
Power Factor | 40019 | Float | Output |
Energy | 40021 | Uint | Output |
Correction Factor | 40023 | Float | Input |
A CSV file for the object model according to the above data sheet looks as shown in the following image.
While defining the CSV file , you must specify the data points, data type element and data type for each object model you want to create in the following format:
# DPT Name;DPE Name;Type;(Reference);[DPE Name Type (Reference) .... ]
Example
Modbus_MeterTypeXY,Voltage_Phase1,Float
Data Point Type, Data Point Element, and Data Type | |
Data | Description |
DPT Name | Name of the data point of the object model. |
DPE Name | Name of the DPE (property) associated to the object model. |
Type;(Reference) | String identifying the property (element).
For details about the acceptable values, see the Table Element Types that follows. |
[DPE Name Type (Reference)] | Definition of the property (element) by name and type. |
Element Types | |
Type String | Description |
Char | Character |
Uint | Unsigned Integer |
Int | Integer |
Float | Double |
Bool | Boolean |
A CSV file template example named Modbus_template_4.0_CustomObjectModel_1.csv is provided under the following folder GmsMainProject\profiles\ModbusDataTemplate. This CSV file can be used to start creating the custom object model.
While specifying the definition for your custom object models, we recommend you to consider the following situations. In each of the situations, you can also define the InOut properties.
Situation 1
If you want to create 20 instances of MeterXY, each integrated through its own gateway interface, then you must define the CSV file as follows. Note that the Object Model name must be specified under the ObjectModel column in the Device entry.
When you open the CSV file, you must enter the following elements:
- Modbus Interface
- Modbus Custom Devices
The data from the CSV file is reordered to represent the hierarchy of the data points of an Object Model to create in the Management View of System Browser.
Situation 2 for Modbus
If you want to create 20 instances of Point ABC under Meter_ABC (integrated through a single gateway interface 192.168.0.1), then you must define the CSV file as follows.
Note that the Object Model name must be specified under the ObjectModel column in the Point entry.
When you open the CSV file, you must enter the following elements:
- Modbus Interface
- Modbus Device
- Modbus Custom Points
Situation 3 for Modbus Fire Panel
This scenario is an extension of situation 2.
There are several Modbus devices, especially fire detectors, that have limited memory. These devices may include points addressed as a single bit because of memory restrictions; they cannot be assigned a full byte or register (two bytes). Addressing such points is accomplished through a combination of Offset and bit-level SubIndexing.
In such scenarios, Offset and SubIndex are separately defined in the Import Rules, as well as in the CSV. The cumulative values of Offset and SubIndex are calculated using the following formulas:
- Final Offset = Offset from Import Rules + Offset from CSV
- Final SubIndex = SubIndex from Import Rules + SubIndex from CSV
A register is made up of 2 bytes (or 16 bits).
For example, a fire detector device has four Boolean Input properties. Therefore, the total memory requirement for each detector is four bits. If you have four instances of the same detector, the total memory requirement is sixteen bits, which is equal to one register. So, instead of assigning a separate register to each detector (which will occupy a total of four registers), they can all share a single register to save memory. The following sections explain two different ways of achieving this.
Situation 3 Case A
This situation applies when multiple properties occupy consecutive bits in a single register.
For example, there is a Data Model FD01 in the Import Rules so that all the properties occupy the consecutive bits in a single register, as shown as follows:
NOTE:
The data type of the properties can also be changed to GmsBool from the Object Configurator of the data model. Both mean the same. However, when the data type is GmsBool, you can associate the text groups; you cannot associate the text groups for PvssBool.
If you want to create four instances of this fire detector so that they all fit in a single register, and their properties occupy the bits in the register in the following manner:
Fire Detector Instance | Property | Bit Number in the Register |
FD01_inst01 | AlarmStatus | 0 |
FaultStatus | 1 | |
TamperStatus | 2 | |
MaintenanceStatus | 3 | |
FD01_inst02 | AlarmStatus | 4 |
FaultStatus | 5 | |
TamperStatus | 6 | |
MaintenanceStatus | 7 | |
FD01_inst03 | AlarmStatus | 8 |
FaultStatus | 9 | |
TamperStatus | 10 | |
MaintenanceStatus | 11 | |
FD01_inst04 | AlarmStatus | 12 |
FaultStatus | 13 | |
TamperStatus | 14 | |
MaintenanceStatus | 15 |
You must define the fire detector instances in the CSV file as follows.
During the import, the Importer adds the Offset and SubIndex values of the object model mentioned in the Import Rules to the Offset and SubIndex of the instances mentioned in the CSV file. The formula for calculating the final address of each property is as follows:
- Final Offset = Offset mentioned in Import Rules + Offset mentioned for instance in CSV
- Final SubIndex = SubIndex mentioned in Import Rules + SubIndex mentioned for instance in CSV
- Final address = (Final Offset) + (Final SubIndex)
Fire Detector instance | Property | Offset in Object Model | SubIndex in Object Model | Offset in CSV | SubIndex in CSV | Bit number in the register |
FD01_inst01 | AlarmStatus | 0 | 0 | 0 | 0 | 0 |
FaultStatus | 0 | 1 | 0 | 0 | 1 | |
TamperStatus | 0 | 2 | 0 | 0 | 2 | |
MaintenanceStatus | 0 | 3 | 0 | 0 | 3 | |
FD01_inst02 | AlarmStatus | 0 | 0 | 0 | 4 | 4 |
FaultStatus | 0 | 1 | 0 | 4 | 5 | |
TamperStatus | 0 | 2 | 0 | 4 | 6 | |
MaintenanceStatus | 0 | 3 | 0 | 4 | 7 | |
FD01_inst03 | AlarmStatus | 0 | 0 | 0 | 8 | 8 |
FaultStatus | 0 | 1 | 0 | 8 | 9 | |
TamperStatus | 0 | 2 | 0 | 8 | 10 | |
MaintenanceStatus | 0 | 3 | 0 | 8 | 11 | |
FD01_inst04 | AlarmStatus | 0 | 0 | 0 | 12 | 12 |
FaultStatus | 0 | 1 | 0 | 12 | 13 | |
TamperStatus | 0 | 2 | 0 | 12 | 14 | |
MaintenanceStatus | 0 | 3 | 0 | 12 | 15 |
The following example of FD01_inst04.AlarmStatus may help you better understand the address calculation better.
- Final Offset = Offset mentioned in Import Rules (0) + Offset mentioned for instance in CSV (0) = 0
- Final SubIndex (or Bit Number for Offset 0) = SubIndex mentioned in Import Rules (0) + SubIndex mentioned for instance in CSV (12) = 12
- Final address = (0) + (12) = 12
Situation 3 Case B
This is a derivative of Case A of Situation 3.
In Case A, all the properties were placed consecutively. In Case B, some of these consecutive properties are placed in the lower byte, while the others in the higher byte.
You can change the entries in the CSV file as shown below:
Using the same formulas for calculating the address, the final address will look as follows:
Fire Detector instance | Property | Offset in Object Model | SubIndex in Object Model | Offset in CSV | SubIndex in CSV | Bit Number in the Register |
FD01_inst01 | AlarmStatus | 0 | 0 | 0 | 0 | 0 |
FaultStatus | 0 | 1 | 0 | 0 | 1 | |
TamperStatus | 0 | 8 | 0 | 0 | 8 | |
MaintenanceStatus | 0 | 9 | 0 | 0 | 9 | |
FD01_inst02 | AlarmStatus | 0 | 0 | 0 | 2 | 2 |
FaultStatus | 0 | 1 | 0 | 2 | 3 | |
TamperStatus | 0 | 8 | 0 | 2 | 10 | |
MaintenanceStatus | 0 | 9 | 0 | 2 | 11 | |
FD01_inst03 | AlarmStatus | 0 | 0 | 0 | 4 | 4 |
FaultStatus | 0 | 1 | 0 | 4 | 5 | |
TamperStatus | 0 | 8 | 0 | 4 | 12 | |
MaintenanceStatus | 0 | 9 | 0 | 4 | 13 | |
FD01_inst04 | AlarmStatus | 0 | 0 | 0 | 6 | 6 |
FaultStatus | 0 | 1 | 0 | 6 | 7 | |
TamperStatus | 0 | 8 | 0 | 6 | 14 | |
MaintenanceStatus | 0 | 9 | 0 | 6 | 15 |
Similar to case A, the entire register is used for storing the complete Object Model instead of four different registers. However, the addressing pattern is different.
Situation 3 Case C
The data model requires two byte properties in a single register. The first property is placed in the lower byte and the second property in the higher byte.
NOTE:
PvssChar is used to represent a byte.
Two instances of this are created in the CSV.
Fire Detector instance | Property | Offset in Object Model | Offset in CSV | Final Offset | SubIndex in Object Model | SubIndex in CSV | Final SubIndex |
FD03_inst01 | CommandStatus | 0 | 0 | 0 | 0 | 0 | 0 |
ExtendedStatus | 0 | 0 | 0 | 1 | 0 | 1 | |
FD03_inst02 | CommandStatus | 0 | 1 | 1 | 0 | 0 | 0 |
ExtendedStatus | 0 | 1 | 1 | 1 | 0 | 1 |
FD03_inst01 and FD03_inst02 instances each occupy a separate single register. Offset 0 indicates the first byte of the register from the base address, while Offset 1 indicates the second byte of the register from the base.
When re-importing the Object Model via a CSV file, the existing Object Models are updated.
By using re-import, you can perform the following:
- Add new Object Models.
- Add or remove properties in existing Object Models.
- Update the type of an existing property of an Object Model.
- Add or update multiple Object Models using a single CSV file.
NOTE:
Re-import cannot delete any existing Object Models from the system. If you want to delete any existing Object Model, you must select the Object Model from System Browser and click Delete.
The key Modbus data point types map to analog or digital property types, which are either read-only or read-write. The following table shows this simplified classification.
Function Code | Address Range |
Coil (Discrete Output) | 00001 - 09999 |
Discrete Input | 10001 - 19999 |
Input Register | 30001 - 39999 |
Holding Register | 40001 - 49999 |
The Holding register (function type 3) and Input register (function type 4) can contain data, which is an integer/long, unsigned integer/long, or int/double. Therefore, the mapping of these registers and data point types to an equivalent management station object model needs information input from the user. This information is contained in the engineering data. This information is combined (by the Importer) with information contained in the Import Rules to decide which object model must be used to create the representation of a register.
Standard Modbus object models are located at the following location Management View > System Settings > Libraries > L1-Headquarter > Global > Modbus.
In addition to the standard Modbus object models, a set of custom object models termed as Modbus InOut object models is also present in the standard Modbus library. To illustrate using InOut object models, a CSV file containing the instances of the InOut Object models is present at the following location, GmsMainProject\profiles\ModbusDataTemplate.
The current Modbus driver supports either the IN or Out direction for a point; however, it does not support both the In and Out directions for a single point. This means that if you manually change the value of a point in the field whose direction is Out, the new value will fail to reflect this.
For example, you have an AnalogOutputpoint whose direction is Out. The initial value of this point is 4 and you want to update this value to 5. To do this, in the Operation tab, you would enter 5 into the AnalogOutput field. The Modbus driver physically writes this value to the point.
Next, you want to update the value of this Out point to 10. The new value will not be updated.
To overcome this limitation, there are two properties in the same point. In this way, both the In and the Out point will refer to the same point in the field. The result is that you will see the same value for both the In and the Out point. Only the Value changed from field is updated in the InOut point.
Therefore, the most recent field value of the point (in this case, 10) will be updated to the In point, whereas the Out point will still retain the old value (in this case 4).
The workaround for this situation has been provided in the library for System-defined points in the form of InOut object models. For custom devices and points, a step-by-step approach to create object models with InOut properties has been provided.
System Defined Points
The workaround for system defined points is the form of InOut Object models, which are a part of Modbus Standard Library. There are the following types of object models:
- GMS_MODBUS_AnalogInOut_Float
- GMS_MODBUS_AnalogInOut_Int
- GMS_MODBUS_AnalogInOut_Int64
- GMS_MODBUS_AnalogInOut_Uint
- GMS_MODBUS_AnalogInOut_Uint64
- GMS_MODBUS_BinaryInOut
- GMS_MODBUS_MultiStateInOut
Each of these object models has two properties
- Value - Represents the current value of the point. This functions in the input direction.
- ValueOut - Represents the value that has been sent from the management station to the point. This functions in the output direction.
A separate set of custom Import Rules labeled as Import Rules InOut Points has been included to define the two above mentioned properties for each of the five object models.
The following three object models, support both 32Bit as well as 16Bit transformation types
- GMS_MODBUS_AnalogInOut_Int
- GMS_MODBUS_AnalogInOut_Uint
- GMS_MODBUS_MultiStateInOut
For 16-bit transformation type, you must select the 16Bit address profile and for 32Bit you must select the default profile in the Address Profiles section.
These object models and their Import Rules have been pre-configured so that they can be used directly without requiring any re-configuration. For example, the function codes of the Value and ValueOut properties have been set to support reading from and writing to that particular point. However, you can change the attributes (Function Code, Offset, Subindex and so on) of the properties in the custom Import Rules as per your requirements. For more information, see Objects and Properties Expander in Custom Import Rules.
Object Models, Address Profiles, and Preconfigured Function Codes of their properties | |||
Type | Function Code for “ValueOut” | Function Code for “Value” | Address Profiles |
GMS_MODBUS_AnalogInOut_Float | 16 | 03 |
|
GMS_MODBUS_AnalogInOut_Int | 16 | 03 |
|
GMS_MODBUS_AnalogInOut_Int64 | 16 | 03 |
|
GMS_MODBUS_AnalogInOut_Uint | 16 | 03 |
|
GMS_MODBUS_AnalogInOut_Uint64 | 16 | 03 |
|
GMS_MODBUS_BinaryInOut | 05 | 01 |
|
GMS_MODBUS_MultiStateInOut | 16 | 03 |
|
CSV Configuration
While configuring the CSV for points of the InOut Object Models, you must mention the object model name or its alias in the ObjectModel column of the point entry. You do not need to specify Function Code, Direction and Data type, since these are directly taken from the Import Rules. The configuration for the remaining CSV fields is similar to that of standard Modbus points.
After the import, the points in the management station display as follows:
Support for Custom Object Models with InOut Properties
To support the functionality of an InOut point for custom object models, you must define a corresponding Output property for an Input property. Therefore, you must modify the object model importer CSV file and mention the Output property as follows.
Example
The object model ‘MyDevice’ is modified to have an additional two Output properties for the corresponding two Input properties.
NOTE:
The first part of the Output property name must be the same as the Input property name. Otherwise, the Importer will fail to set the Text Group on the Output property.
As you can see, ‘Speed_Output’ is an Output property that points to ‘Speed’. ‘Speed’ actually handles the reading of the property from the point, whereas ‘Speed_Output’ internally handles writing values to the property of the point from the management platform.
After importing the Object Model, set the values in the Properties expander in the Models & Functions tab of the ‘MyDevice’ as follows. Note that the DL2 and DL3 of ‘Speed’ and ‘Temperature’, that is the Primary properties, are checked. Set the Managed type. You can also configure other attributes of the property.
If you are configuring an Output property for a GmsEnum or GmsBool type property, you must enable the Valid flag available under the Value Attributes frame in the Details expander for that Output property.
Proceed to the Import Rules to configure the object properties (Function Code & Direction) of MyDevice. You must perform the following steps for Speed:
- Configure the Input property.
- Set the direction of Speed property as Input.
- Select the appropriate Function Code for read operation.
- Enter an Offset and SubIndex. Carefully select these values as these values are replicated in the Output property.
- Configure the Output property.
- Set the direction of Speed_Output as Output.
- Select the appropriate Function Code for write operation.
- Enter the same Offset and SubIndex that you mentioned in the corresponding Input property.
Repeat this procedure for the Temperature property also.
Additionally, you must add the commands configuration for the object model properties. Go to the object model MyDevice. Perform the following steps to add commands for Speed:
- In the Properties expander, under the Models & Functions tab, select Speed.
- In the Command Configuration expander, click New to create a new command.
- In the Command column, from the drop-down, select GenericWriteInt, if Speed is a PvssInt type.
For other data types, select the appropriate command. Example, GenericWriteFloat for PvssFloat/GmsFloat and so on.
- In the Targeted Property column, select the name of corresponding Out point (in this case Speed_Output).
- Click +/- to open or close the sublines (parameters) belonging to a command type.
- Select the Value parameter.
- Set the Default Value to ReferCmdDef and set the Affected Property to the name of the affected input property, that is, Speed_Output.
- Repeat Steps 4 through 7 for the remaining properties.
- Save the changes.
Role of Default Property
Among the set of properties of the object model, there is a default property that can be viewed and changed from the object Model and Functions tab.
Since the importer updates the default property of the custom point with attribute values mentioned in the CSV file, the default property must be carefully chosen and its gms data type must be set to GMS*** to allow the importer to update the details from the CSV.
The GMS data type of the output property that corresponds to the default property must be the same. For example, if your default property is 'Speed' and its Data Type is GmsEnum, then the data type of the Output property of 'Speed' must be GmsEnum.
Please note that the custom object models which will be used to represent devices instead of points do not support configuration of default Property using the CSV.
Configuring Statetext through CSV
If the default property of your object model is a GmsEnum or GmsBool type, then you can configure Statetexts for the property using your CSV. The rules for configuring Statetext are the same as they are for Standard Modbus Points.
You have configured the Modbus custom device data model with Out points. You can now create a CSV file for this type of Object Model to import points.
NOTE:
For InOut Object Models, if ValueConversion configuration is being assigned to a Value property, either from the MessageConversion section in the Objects and Properties expander in Custom ImportRules or from N-1 mapping in the CSV file, then the same ValueConversion configuration must be assigned to the corresponding ValueOut property also.
