) protocol. This protocol is designed primarily for applications that collect data from consumption meters of various types (heating, electricity...).
Before using this driver in the PROMOTIC application it is highly recommended to watch "
Basic properties of the driver
- Usage of this driver requires purchase of the
PmMBus licence. When developing the application in the freeware mode
PmFree, or with
development environment and while testing it in runtime, this component is always functional.
- The communication is done for Ethernet (PROMOTIC application is client) or for serial link (COM1, COM2 ...).
When communicating via Ethernet the form of the transferred data is the same as for M-BUS for serial link. The essential condition is that the M-BUS/Ethernet converter does no modifications to the transferred data.
- The PROMOTIC application is the Master (it means that it initiates the data transfer) from this communication point of view.
- This is a network communication, it means that one
PmaComm object can communicate with multiple devices (the protocol supports multiple device addressing).
The driver can be configured on very general level in the PROMOTIC application:
-
Address:
Each meter can be addressed. In the
PmaCommGroup object, the meter address can be defined for each variable, in the
PmaCommMsg object, the address is defined on the "
Data-sent" tab in the
Address variable. The addresses values are:
- 0 to 250 = standard address of specific meter.
- 254 = universal address. All meters receive the requests and all meters also response. It has sense only if a single meter is connected.
-
More meter types on 1 line:
On one serial line there can be connected more meter types, for example, meters
Kamstrup,
Landis,
Danfoss, etc. can be "mixed".
-
Different data formats:
Values from the meters are sent in different formats (
BCD or binary encoding, stored on 2/4/6/8 bytes, ...). The driver
automatically decodes these values.
-
Physical units conversion:
The driver can
automatically convert the values of received data into standard physical units. The meters usually send these values as integer value with flag that it is, for example, 0.01C, 0.1kW, etc. The driver converts the values into the following units:
| Unit: |
Physical quantity: |
| GJ |
Energy |
| W |
Power |
| m3 |
Volume |
| kg |
Mass |
| m3/h |
Volume Flow |
| kg/h |
Mass Flow |
| C |
Temperature (Forward, Return, Difference, External) |
| mbar |
Pressure |
| V |
Electric Voltage |
| A |
Electric Current |
| second count |
Averaging Duration, Actuality Duration .. |
| day count |
On time, Operation time |
The binary date formats (
TimePoint) are converted to the value of the
Date type. Other values (counter, serial number ..) are not being converted.
-
Common read:
The driver can read also from unknown M-BUS meters, that have no preconfigurations prepared. Reading such data is based on the fact that the M-BUS data message contains not only the values, but also the additional flags about the meaning of the specific value. The driver knows what the value in the message means and therefore is able to process it. Reading such data can be used in both
PmaCommGroup and
PmaCommMsg objects:
In the
PmaCommGroup object, the data items are configured by specifying the item type (Temperature, Volume ...). The driver then finds the desired data in the received message (if present in the message) and saves it into the data item.
The "
Common meter/Reading of generally configurated data" message in the
PmaCommMsg object is used for common reading of the data. The designer can setup the data of the
PmaCommMsg object exactly according to the meter type. If the designer does not know what the meter provides, then it is possible to set in this message to write received data into the
INFO system. According to this listing, the designer can then set the data of the object.
It is easier to use the
PmaCommGroup objects to receive the values from the meters. The
PmaCommMsg objects can be used for special, less standard, communications fith following properties:
-
Header of M-BUS message:
When receiving the standard data, the meter sends a header before the data. The information from the header is available because the driver generates for each such message the following variables on the "
Data-received" tab:
-
Address: The address of the meter that send the data (for the
M-BUS protocol it is the
A-Field item). If the
Address variable is set to
254 (universal address) on the "
Data-sent" tab, then the meter responds by its real address and so it is possible to
find out this address by the meter with unknown address. The meter itself has the address preset by the manufacturer to
0.
- IdentNr: (Indentification Number) Customer number in the range from 00000000 to 99999999. It can be preset at fabrication time with a unique number, but could be changeable afterwards.
- Manufac: (Manufacturer) The manufacturer identifier.
- Version: Generation or version of meter and depends on the manufacturer.
- Medium: Measured medium: 0=other, 1=oil, 2=electricity, 3=gas, 4=heat (measured at return temperature: outlet), 5=steam, 6=hot water, 7=water, 8=Heat Cost Allocator, 9=compressed air, 10=Cooling load meter (measured at return temperature: outlet), 11=Cooling load meter (measured at flow temperature: inlet), 12=heat (measured at flow temperature: inlet), 13=Heat/Cooling load meter, 14=Bus/System, 15=Unknown Medium, 22=Cold water, 23=Dual water, 24=Pressure, 25=A/D converter.
- AccessNr: (Access Number) It is increased by one after each send data from the meter.
- Status: Indicates application errors. Status bit1.bit0: 0.0=No Error, 0.1=Application Busy, 1.0=Any Application Error, 1.1=Reserved.
-
FCB flag handling:
Optionally the driver can automatically change the counter of sending to individual meters (it can automatically change so-called
FCB flag). According to this flag the meter knows if the request is new or old (repeating). Some meters don't use this flag but some of them wouldn't sent correct data without setting the flag right. For meters and messages, where this has to be specified by the designer, there is the
FcbAttr variable on the "
Data-sent" tab. It can be set to the following values:
0 = don't change the counter (i.e. FCB flag is not used)
1 = the flag is changed automatically. The designer needn't care about changing the flag, the driver itself changes it.
4 = (only for special purposes) FCB=FCV=0
5 = (only for special purposes) FCB=0 and FCV=1
6 = (only for special purposes) FCB=1 and FCV=0
7 = (only for special purposes) FCB=FCV=1
The communication description by means of the PmaCommGroup object
The
PmaCommGroup objects can be used for this driver. For usual data transmissions it is more favourable than using the
PmaCommMsg object.
The variables in the
PmaCommGroup object (or even better the variables in the
PmaData object with
ExtComm data extension) can be of arbitrary number, type and order. The driver uses optimized internal communication messages for reading the data from the device.
All variables are read (if the "
Data refresh enabled" configurator is checked). Writing variables into the device is not enabled for this driver.
In one
PmaCommGroup object, the data items can be defined (variables on the "
Data" tab or
ExtComm data extensions) for multiple meters simultaneously.
Sometimes it may be more advantageous to let one
PmaCommGroup object represent a single meter - in such case the meter address can be defined in the "
Default meter address" configurator and then the address needs not to be defined for each data item (only the text
"saD.." is defined - see further). This way it is easier to change the meter address just on one place.
Description of the "ItemId" configurator:
ItemId is the text identifier of the item that is used for addressing the item in the device. The "
ItemId" configurator tells the driver how to receive or send the item value.
The text can be either written manually, or it can be assembled in the window opened by the button to the right of the configurator.
Macro expression can be used for input (it is evaluated after the application is launched).
Examples of the identifier syntax:
sa44.M1.TemperFor
sa254.M1.TemperFor.max.S3.T2.c0
saD.M1.MeterManufac
saD.B1.Index20
saD.B4.Index30
sa1.Ia2.Index3
sa3.Ia2.Index3.c0
The text always begin with
"sa" (=
Slave/Station Address) followed by a decimal address of the meter. The
"D" (
=default) character can be used instead of specific address, which means that the meter address is taken from the "
Default meter address" configurator.
The identifier following after the comma specifies the area of desired data (specifies the M-BUS message type, causing the meter to send the data from desired area). The possible values are as follows:
M1 = (
Request UD2, FCB=0, FCV=1) The first standard area of the meter.
Supported by majority of meters.
The main actual values of the meter are usually present here.
M2 = (
Request UD2, FCB=1, FCV=1) The second standard area of the meter.
Usually either not supported by the meters, or the same data as for the first area are is sent.
B1 = (
Send UD, CIField=B1) Request readout of complete RAM content.
B4 = (
Send UD, CIField=B4) EEPROM read.
Ia = (
Danfoss-INFOCAL type) This type is used for
Danfoss meters (
Ia=
a type indexing).
There is too much data to fit into the standard area.
For obtaining the additional data a special message must be sent with the area index (the index is entered after the
"Ia" text) and the meter sends the data from the selcted area. See:
Communication with meters Danfoss INFOCAL-5
Ib = (
Sontex-SUPERCAL type) The same situation as for
"Ia", but used only for
Sontex meters.
The special message syntax is different but the principle is similar. See:
Communication with meters Sontex SUPERCAL
The identifier following the comma specifies the desired value in selected area. The meter sends all the data from selected area simultaneously. The desired value can be identified either by index (
Index) or by value specification (additional options):
Index -
Behind the identifier the value index is defined (zero-based index) in the area. This way each standard value in the area can me identified. Suitable for entering values that cannot be defined by following meaning specification. The following specifications do not cover all the possibilities of M-BUS communication (the
MICROSYS, spol. s r.o. company can add additional specifications into the driver).
Pressure -
Pressure [mbar]
FlowVolume -
Volume Flow [m3/h]
FlowMass -
Mass Flow [kg/h]
TemperFor -
Forward temperature [°C]
TemperRet -
Return temperature [°C]
TemperDif -
Temperature difference [°C]
TemperExt -
External temperature [°C]
Voltage -
Electric Voltage [V]
Current -
Electric Current [A]
TimeOper -
Operation time [day]
FabricNum -
Meter fabric number
CumulCount -
Cumulation counter
MeterAddr -
The address of the meter that send the data (for the
M-BUS protocol it is the
A-Field item).
MeterIdent -
Customer number in the range from 00000000 to 99999999. It can be preset at fabrication time with a unique number, but could be changeable afterwards.
MeterManufac -
The manufacturer identifier.
MeterVersion -
Generation or version of meter and depends on the manufacturer.
MeterMedium -
Measured medium:
0=other,
1=oil,
2=electricity,
3=gas,
4=heat (measured at return temperature: outlet),
5=steam,
6=hot water,
7=water,
8=Heat Cost Allocator,
9=compressed air,
10=Cooling load meter (measured at return temperature: outlet),
11=Cooling load meter (measured at flow temperature: inlet),
12=heat (measured at flow temperature: inlet),
13=Heat/Cooling load meter,
14=Bus/System,
15=Unknown Medium,
22=Cold water,
23=Dual water,
24=Pressure,
25=A/D converter.
The identifiers following the comma define more specific values and are optional.
max = Maximum value
min = Minimum value
err = Value during error state
U = The item with defined number Subunit (used for distinction of two similar items).
If not set, then the first appearance of the corresponding item will be serched in the received message regardless on the Subunit.
S = The item with specified Storage number. "S0" means the curent value, "S1" is a value in storage1, possibly could be, for example, the value from previous month, etc.
If the memory (S character) is not defined, then the first occurrence of the desired item will be searched in the received message regardless on the memory location.
T = The item with specified Tariff number. "T0" means current tariff (or "no tariff"), "T1" means the value according to the first tariff, etc.
If the tariff (T character) is not defined, then the first occurrence of the desired item will be searched in the received message regardless on the memory tariff.
| Default meter address | The address defined here can be used for definitions in the "ItemId" configurator in variables in this object (i.e. in variables on the "Data" tab or in data extension ExtComm). The address can be entered in ItemId:
- either for example sa1... - then the value of the variable will be read from the meter with address 1.
- or saD... - the "D" character means default ((it means that the address is taken from this configurator).
This parameter can be changed in runtime and read in the script by methods: SetSpecParam("SlaveAddr") and GetSpecParam("SlaveAddr"). |
|---|
The communication description by means of the PmaCommMsg object
The
PmaCommMsg object can be used for special communications, that cannot be executed by the
PmaCommGroup object.
| Meter type | Meter type selection. It is recommended to select only "Common meter" here. Other options are considered obsolete and it is recommended to replace these by the PmaCommGroup object.
Common meter - Common messages suitable for all types of M-BUS meters.
Kamstrup MULTICAL - obsolete
ABB SVM - obsolete
Danfoss INFOCAL 5 - obsolete
Landis ULTRAHEAT - obsolete
Supercal SONTEX - obsolete
CALMEX VKP - obsolete |
|---|
| Message type | Required message type for the corresponding meter. The following list contains messages only for Meter type = Common meter. |
|---|
List of message types for Meter type = Common meter:
-
Initialization of Slave (of the meter):
Initialization of the meter (message of the
SND_NKE type). It is used first of all for the initialization of controlling so-called
FCB flag (see
FCB flag handling) that serves to the meter as the information about the right sequence of the sent messages. It is recommended to call this message at application launch and also when an communication error appears (see the
pEvent.Error parameter in the
PmaCommMsg.onEndOfTransfer event).
The address of the meter can be set exactly (value from 0 to 250) - in this case each meter confirms (responds) whether it took due note of the command.
It is suitable also to use the universal address 255 - in this case all connected meters are initialized at once without any confirmation (see
Address).
There are following variables on the "
Data-sent" tab:
Address (Byte) = Meter address
-
Reset of the application layer in the Slave (of the meter):
Sending of this message to the meter causes reset of application variables in the meter (message of the
SND_UD type). What actually happens in the meter depends only on the meter. Majority of the following meters doesn't need this message. This message is used by:
Communication with meters Sontex SUPERCAL.
There are following variables on the "
Data-sent" tab:
Address (Byte) = Meter address
-
Selection of a Slave station by identification number:
This message will turn the
Slave station into so-called
selected) state. After the station is turned into the selected state, then it communicates as if its address was
253 (see
Address), until any other station is turned into the selected state. The station is selected by so-called secondary address, which is defined by following:
IdentNr = identification number of the meter,
Manufac = identification number of the manufacturer,
Version = meter version,
Medium = measured medium. These items are defined on the "
Data-sent" tab and can be received from the meter, for example, by the "
Common meter/Reading of generally configurated data" message when starting up the meter.
Addressing stations by the secondary address is handy for for example:
- complex systems where 250 addresses are insufficient or
- for stations that are replaced very often and therefore the primary addresses may not be unique.
There are following variables on the "
Data-sent" tab:
IdentNr (Long)
Manufac (Integer)
Version (Byte)
Medium (Byte)
-
Change Baud rate:
(message of the
SND_UD type). Using this message will not be probably needed usually because the rate can be set directly in the meter and it is not advisable to change it during run of the application. Many meters can also adjust themselves to more baude rates, even if they were set to another rate.
There are following variables on the "
Data-sent" tab:
Address (Byte) = Meter address
BaudRate (Byte) = (B8h=184=300Bd, BBh=187=2400Bd ..)
-
Reading of generally configurated data:
The message designed
for reading data from meters (message of the
REQ_UD2 type). It is used only in special cases - for standard data reading it is better to use the
PmaCommGroup object - see
The communication description by means of the PmaCommGroup object.
There are following variables on the "
Data-sent" tab:
Address = (Byte) Meter address
DataAttr = (Long) Flag indicating how the "specific data" is stored in the received message (i.e. data v poslední části
DIF=0f):
0 = are stored as binary - i.e. no recounting is needed
1 = are stored in BCD code - the driver recalculates the value to binary form.
There are following variables on the "
Data-received" tab:
Data1 = (Single) First data value in the message. This variable can be changed and create variables that follow. Variables can be of following data types:
-
Single - in this case the stored value is converted into the appropriate technological unit. The conversion is made according to the table - see
Physical units conversion.
- Date - the value is converted into the calendar date.
- Long - the value is not converted (for variables that have no unit or if conversion is not needed).
On reading
standard data from the meter, the response does not contain only values, but also flags of the value type (flow, energy, power, etc.), flags of the unit type (e.g.
kWh,
J,
0.001kWh ...), flags about the tarif type or memory number, etc. If you know the meaning of values in the response from the meter, then you can configure and name items, into which the received values are stored, on the "
Data-received" tab by yourself. If you do not know what the meter sends, then you can use the "
Common meter/Getting a complete list of gauges measured quantities" message type.
Except the standard data the meter can send the
specific data that don't have the flag about the meaning and the unit any more. These data are always located after the standard data. If you know the meaning of these data (e.g. from the meter documentation), then even these data can be received in this message. It is sufficient to define next variables of corresponding types (
Byte,
Integer,
Long) after already created variables on the "
Data-received" tab and then the value in the received message is stored in the corresponding variable without any conversion. To be more specific, it is possible to define if the specific data are stored in the message in binary form (i.e. no conversion is needed) or in
BCD code. If the specific data are in
BCD code, then you can already mentioned variable
"DataAttr" set to 1 - in this case the driver converts the value into the binary form (it would be also possible not to convert it and to use the
Pm.TransformValue method but it would be much more complicated).
Some meters send
data in more messages in the exact sequence. Even receiving the data can be done by this type of the message. You must configure more
PmaCommMsg objects to individual messages, fill it the data respectively and then send the messages one after the other (by the
PmaCommMsg.Run method). For these types of transfers the meter uses
FCB flags (see
FCB flag handling) and therefore the
"FcbAttr" variable has to be set to 1. By this way some meters solve first of all reading the history. If you didn't set
"FcbAttr" to 1, then you would have read only the 1st message (where there are current values usually) all the time. If
"FcbAttr" is set to 1, then the meter sends all messages it has - and sometimes it has really lots of them. For example the
ABB SVM meter has stored historical data in 128 messages (fortunately of the same type, so that it is possible to read them by one object).
-
Byte configurated message of the send/receive type:
This message is meant for designers who know the
M-BUS protocol. It is possible to configure the message (separatelly to receive and separatelly for sending) from the
"SingleCharacter",
"ShortFrame",
"ControlFrame" and
"LongFrame" types, which are 4 possible message types of the protocol on the lowest level with setting the
CField,
AField and
CIField values by the designer and with setting the user data. It is also possible to choose the message of the
Pure Bytes type, which allows to send/receive the data without any transformation by the protocol.
This message type will be used very rarely for special and test purposes.
-
Getting a complete list of gauges measured quantities:
This message creates a list of all items that can be obtained by the corresponding data message type (from message with
FCB flag 0 or 1).
There are following variables on the "
Data-sent" tab:
Address = (Byte) Meter address
There are following variables on the "
Data-received" tab:
Info = (String) Text list of measured values of the meter in corresponding message.
This list is used mainly as information for the designer for the correct entry of the in the "
ItemId" configurator value. - see
Description of the "ItemId" configurator.
The list can look like this:
Meter: Address=6, Ident=2015597318, Manufac=11309, Version=15, Medium=4
Index:0; Name:FabricationNumber; Value:6932378; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:1; Name:Energy; Value:311230720; Unit:10 MJ; RecalcValue:3112307.250000 GJ; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:2; Name:Volume; Value:1369178624; Unit:0.1 m3; RecalcValue:136917856.000000 m3; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:3; Name:TimeOn; Value:-1236336640; Unit:1 hour; RecalcValue:-51514028.000000 day; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:4; Name:ForwardTemperature; Value:-484573184; Unit:0.01 °C; RecalcValue:-4845732.000000 °C; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:5; Name:Power; Value:1241513984; Unit:100 W; RecalcValue:124151400.000000 kW; Type:InstantenousValue; SubUnit:0; Storage:0; Tariff:0
Index:6; Name:Volume; Value:0; Unit:0.01 m3; RecalcValue:0.000000 m3; Type:InstantenousValue; SubUnit:1; Storage:0; Tariff:0
Index:7; SpecData (DIF=Fh)