Promotic

PmMBus - Driver for communication by the M-BUS protocol

This PROMOTIC driver is used for communication with devices that support the M-BUS (Meter-Bus) protocol. This protocol is designed primarily for applications that collect data from consumption meters of various types (heating, electricity...).
- The meters communicate by the M-BUS protocol over the special physical interface (36V) and therefore it is necessary to use the HW converter (see M-BUS HW converter).


Before using this driver in the PROMOTIC application it is highly recommended to watch "PROMOTIC video tutorial 4 - Communication drivers".

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.
- The driver is incorporated into the PROMOTIC system by means of the PmaComm object.
The driver supports the usage of both PmaCommMsg and PmaCommGroup objects. For common case of the data transfer, it is better to use the PmaCommGroup object.
For easy integration of this driver into the application it is handy to use: Preconfigurations in group "M-BUS"
- 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.
- 253 = the address of "selected" meter. The meter can be "selected" by the "Common meter/Selection of a Slave station by identification number" message.
- 254 = universal address. All meters receive the requests and all meters also response. It has sense only if a single meter is connected.
- 255 = universal address. The requests are received by all meters, but no meter replies. It has sense for example for "Common meter/Initialisation of Slave (of the meter)" message.
- 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 coding, 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 up the data of the object.


It is easier to use the PmaCommGroup objects for receiving 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


- Non-standard messages: For special messages that don't serve for standard reading the data, the driver has preset messages ("Common meter/Initialisation of Slave (of the meter)" and "Common meter/Change Baud rate" messages) or the designer can set up the special message on the byte level ("Common meter/Byte configurated message of the send/receive type" message - for experts of the M-BUS protocol).

Recommended values of the PmaComm object parameters:

Recommended values for the Serial link parameters:
Baud rate300 Bd. This rate should be supported by all meters. Then according to used meters the rate can be increased. Next recommended rates are: 2400 Bd, 9600 Bd, 38400 Bd. Many meters can be adjusted to some rates, even if they were set to another rate. Caution: converters often support only the rate of 9600 Bd.
Number data bits8 (it is prescribed by M-BUS standard)
ParityEVEN (it is prescribed by M-BUS standard)
Number of stop bits1
Number of repeats after unsuccessful transmission0.
In order to conserve battery power, these meters go to sleep mode and so it is necessary to wake it up before the communication. The most simple solution is to set the "Number of repeats after unsuccessful transmission" configurator to the value 1 (or more, probably the best value is 2) and the "Response receipt timeout" configurator to the value from 500 to 1000 ms. So the first sent message will wake up the meter and the following messages are then processed correctly.
Timeout between receiving 2 characters100 ms (or greater)
Delay between receive-send0 ms (or greater)
Filter ECHO charsNo. It depends on M-BUS/RS232 converter.
RTS flow controllog.0
DTR flow controllog.0
Recommended values for the Ethernet-client parameters:
TCP/UDP remote port numberaccording to setting of converter M-BUS/Ethernet
Ethernet transfer typeaccording to setting of converter M-BUS/Ethernet
Description and recommended values for the Protocol parameters:
Response receipt timeout1000 ms (or greater). Only for serial link. The time (in milliseconds) the driver is waiting for the response on sending the message.
If no response comes during this time, then the transmission of the message is terminated (the onEndOfTransfer event is triggered with error 24 or 66).
Note:
To read the data from meters more often than 1 minute isn't worth usually. If the data are read more often than 4-30 seconds (it depends on the meter), then the meter doesn't send the data.

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 optimalised 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 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 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
Ic = (Scylar type) The same situation as for "Ia", but used only for Scylar meters.
The special message syntax is different but the principle is similar. See: Communication with calorimetric meters Scylar

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 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).
Energy - Energy [GJ]
Power - Power [kW]
Pressure - Pressure [mbar]
Volume - Volume [m3]
Mass - Mass [kg]
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]
TimeOn - On time [day]
TimeOper - Operation time [day]
TimeDate - Date [date]
FabricNum - Meter fabric number
ErrorFlags - Error flag
ErrorMask - Error mask
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 mont, 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.
c0 = Do not convert to standard physical units (see Physical units conversion).


Description of the "PmaCommGroup > Parameters > Special Parameters" configurator:
Default meter addressThe 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:
- as for example sa1... - then the value 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 modified and read in the script in runtime 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.
Description of the "PmaCommMsg > Parameters > Message parameters" configurator:
Meter typeMeter 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 typeRequired 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:
- Initialisation of Slave (of the meter):
Initialization of the meter (message type SND_NKE). It is used first of all for the initialization of control 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
There is no variable on the "Data-received" tab.
- 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 type SND_UD). 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
There is no variable on the "Data-received" tab.
- 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)
There is no variable on the "Data-received" tab.
- Change Baud rate:
(message type SND_UD). 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 ..)
There is no variable on the "Data-received" tab.
- Reading of generally configurated data:
The message designed for reading data from meters (message type REQ_UD2). 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
FcbAttr = (Byte) Value of FCB flag. See FCB flag handling.
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:
In the beginning the variables are obtained from message header - see Header of M-BUS message.
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 je converted into the calendar date.
- Long - the value is not converted (for variables that have no unit or if conversion is not needed).

When 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 for receiving 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
FcbAttr = (Byte) Value of FCB flag. See FCB flag handling.
There are following variables on the "Data-received" tab:
Info = (String) List of measured values of the meter in corresponding message.

History:
Pm9.00.26: Generalization for data receiving from area B1 (RAM) and B4 (EEPROM).
Pm8.03.19: Generalization for receiving negative values in BCD code.
Pm8.03.17: Fixed bug: Value received in the 12 digit BCD format was processed incoreectly.
Pm8.03.12: Fixed bug:
24bit Integer type values were received incorrectly.
While transferring some messages types memory loss accured (PmSNMP, PmMBus, PmIEC8705, PmElgas2).
Pm8.03.10: Improved receiving of some values (e.g. values with extended VIFE used for detecting variable change time).
Pm8.03.02:
- Generalization in ItemId the desired Subunit now can be defined.
- New message type (in the PmaCommMsg object) has been created for reading information about which values can be obtained from the meter.
- Sometimes the "recount to basic physics units" did not work correctly (for VIFE extended type)
Pm8.02.15: The option to read meter address (MeterAddr) in ItemId.
Pm8.01.08: Fixed bug: When transmitting the message without the acknowledgement some unnecessary timeouts occured
Pm8.00.09: Generalization by the possibility to receive the user values VIF (used by the ACTARIS meter).
Pm8.00.07: Generalization allowing receipt of data with variable length (for meters Actaris and Sensus).
Pm8.00.04: Generalization in order to use the PmaCommGroup object and the ExtComm data extension. This generalization allows to get the basic data from meters regardless on meter type. The driver now searches the desired data in the received message that are defined in the PmaCommGroup object or in data extension ExtComm.
Pm8.00.02: Faster data sending and receiving via Ethernet without the need to wait for timeout.
Pm8.00.00: Generalization for reception of 64-bit float values.
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.