Promotic
WikipediaLinkedInYoutubeTwitterFacebook

PmMBus - Driver for communication with 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 read the chapter: Communicaton using the PROMOTIC drivers.
 

Basic properties of the driver

- Using this driver is bound to purchase the license: PmMBus. With the freeware version PmFree, or when developing the application (with development environment for tersting purposes), this component is always functional.
- The communication is done via Ethernet or via standard serial link (COM1, COM2 ...).
- When communicating via Ethernet the form of the transfered 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 (i.e. it initiates the data transfer) from this communication point of view.
- The driver is incorporated into the PROMOTIC system by means of the PmComm object.

Driver supports the usage of both PmCommMsg and PmCommData objects. For common data transfers, it is easier to use the PmCommData object.

For easy integration of this driver into the application it is handy to use: Preconfigurations in group "M-BUS protocol"

- This is a network communication, i.e. one PmComm 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 PmCommData object, the meter address can be defined for each variable, in the PmCommMsg object, the address is defined on the Data-sent page 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 reply. Relevant only if a single meter is connected.
- 255 = universal address. The requests are received by all meters, but no meter replies. Relevant only 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 normally send these values as integer value with set 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 the binary date formats (TimePoint) are converted into the Date data 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 preconfiguratons prepared. Reading such data is based on the fact that the M-BUS data message contains not only the values, but also the additional info about the meaning of the specific value. The driver knows what the value means and therefore is able to process it. Reading such data can be used in both PmCommData and PmCommMsg objects:

In the PmCommData 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) and saves it into the data item.

The "Common meter/Reading of generally configurated data" message in the PmCommMsg object is used for common reading of the data. The designer can setup the data of the PmCommMsg 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.

- Preset messages: For some often used types of meters (see the list below) the driver has already preset messages. So the designer doesn't need to find out which data are sent by the meter. Some data cannot even be find out without the documentation to the meter. Thanks to preset messages the designer doesn't need to care aboout anything.
 
It is easier to use the PmCommData objects for receiving the values from the meters. The PmCommMsg 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 page:
 
- Address: The address of the meter that send the data (according to the M-BUS protocol it is the A-Field item). If the variable Address is set to 254 (universal address) on the Data-sent page, 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 producer to 0.
- IdentNr: (Indentification Number) Customer number, which runs from 00000000 to 99999999. It can be preset at fabrication time with a unique number, but could be changeable afterwards.
- Manufac: (Manufacturer) 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=HotWater, 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 meter.
- Status: It is used to indicate 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 page. 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 parameters values:

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 when they were set to another rate. Caution: convertes often support only the rate of 9600 Bd.
Number of 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 (or greater).

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 Number of repeats after unsuccessful transmission configurator to the value 1 (or more, probably the best value is 2) and Response receipt timeout 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 chars100 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 parameters:
TCP/UDP port numberby converter M-BUS/Ethernet settings
Ethernet transfer typeby converter M-BUS/Ethernet settings
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, the transfer of the message is terminated (event onEndOfTransfer fires with error 24 or 66).
Note:

To read the data from meters more often than 1 minute isn't worth. 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 the PmCommData objects

The PmCommData objects can be used for this driver. For usual data transmissions it is more favourable than using the PmCommMsg object.

The variables in the PmCommData object (or even better the variables in the PmData 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 enabled). Writing variables into the device is not enabled for this driver.

In one PmCommData object, the data items can be defined (variables on the Data page or ExtComm data extensions) for multiple meters simultaneously.

Sometimes it may be more advantageous to let one PmCommData 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 itema (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 value 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 while the application is launching).

Examples of identifier syntax:

sa1.Ia2.Index3
sa3.Ia2.Index3.c0
sa44.M1.TemperFor
sa254.M1.TemperFor.max.S3.T2.c0
saD.M1.MeterManufac

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 defines the area of desired data (defines the type of M-BUS message, 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 are is sent.
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 defined 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 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 for SCYLAR meters. The special message syntax is different but the principle is similar. See: Communication with meters SCYLAR calorimetric meter

The identifier following the comma defines the desired value in selected area. The meter sends all the data from selected area simultaneously. The desired value can be identified by 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 basic 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 flags
ErrorMask - Error mask
CumulCount - Cumulation counter
MeterAddr - The address of the meter that send the data (according to the M-BUS protocol it is the A-Field item).
MeterIdent - Customer number, which runs from 00000000 to 99999999. It can be preset at fabrication time with a unique number, but could be changeable afterwards.
MeterManufac - 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=HotWater, 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 defined then the received message will be serched for the first appearance of the corresponding item regardless on the Subunit.
S = 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 S character is not defined, then the system will search the the received message for the first occurrence of the desired item regardless on the memory location.
T = Item with specified Tariff number. "T0" means current tariff (or "no tariff"), "T1" means the value according to the first tariff, etc. If the T character is not defined, then the system will search the the received message for the first occurrence of the desired item regardless on the memory tariff.
c0 = Do not convert to standard physical units (see Physical units conversion).
 
Description of the PmCommData > Parameters > Special Parameters configurator:
Default meter addressThe address defined here can be used for definitions in the ItemID configurator for the variables in this object (i.e. the variables on the Data page or in the ExtComm data extensions). The address can be defined 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, and the address is taken from this configurator.

This parameter can be modified and read in runtime by the methods: SetSpecParam("SlaveAddr") and GetSpecParam("SlaveAddr").

The communication description by the PmCommMsg objects

The PmCommMsg obejcts can be used for special communications, that cannot be executed by the PmCommData object.
Description of the PmCommMsg > Parameters > Message parameters configurator:
Meter typeMeter type delection. It is recommended to select only "Common meter" here. Other options are considered obsolete and it is recommended to replace these by the PmCommData 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 for Meter type = Common meter.
A list of message types for Meter type = Common meter:
- Initialisation of Slave (of the meter):

Initialization of the meter (message type SND_NKE). It serves 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 when the application starts and also when an communication error appears (see the pEvent.Error parameter in the PmCommMsg.onEndOfTransfer event).

The address of the meter can be set exactly (value from 0 to 250) - then each meter confirms (responds) whether it took due note of the command. It is suitable also to use the universal address 255. Then all connected meters are initialized at once without any confirmations (see Address).

There are following variables on the Data-sent page:
Address (Byte) = Meter address
There is no varible on the Data-received page.
- Reset of the application layer in the Slave (in the meter):

Sending of this message to the meter causes reset of application variables in the meter. 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 page:
Address (Byte) = Meter address
There is no varible on the Data-received page.
- 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 page and can be received from the meters, 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 page:
IdentNr (Long)
Manufac (Integer)
Version (Byte)
Medium (Byte)
There is no varible on the Data-received page.
- Change Baud rate:

Using this message won't be probably needed in most cases 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 page:
Address (Byte) = Meter address
BaudRate (Byte) = (B8h=184=300Bd, BBh=187=2400Bd ..)
There is no varible on the Data-received page.
- Reading of generally configurated data:

Message designed for reading data from meters. It is used only in special cases - for standard data reading it is better to use the object PmCommData - see The communication description by the PmCommData objects.

There are following variables on the Data-sent page:
Address = (Byte) Meter address
FcbAttr = (Byte) Value of FCB flag. See FCB flag handling.
DataAttr = (Long) Attribute indicating how the "specific data" is stored in 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 page:
In the beginning the variables are obtained from message header - see Header of M-BUS message.
Data1 = (Single) First data value in the message. You can change this variable and create variables that follow.
- Single - then 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).

When reading standard data from a meter, the response does not contain only values, but also flags of the value type (flow, energy, power, etc.), flafs 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 the 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 page 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 the message. It is sufficient to define next variables of corresponding types (Byte, Integer, Long) after already created variables on the Data-received page and then the value from 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, and 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 PmCommMsg objects to individual messages, fill it the data respectively and then send the messages one after the other (by the PmCommMsg.Run method). For these types of transfers the meter uses FCB flags (see FCB flag handling) and that's why 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, you would have read only the 1st message (where there are current values only) 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 select the message type "Pure Bytes", which allows to send/receive the data withou any transformation of the protocol.

This type of the message 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 read by the corresponding data message type (from message FCB with flag 0 or 1).

There are following variables on the Data-sent page:
Address = (Byte) Meter address
FcbAttr = (Byte) Value of FCB flag. See FCB flag handling.
There are following variables on the Data-received page:
Info = (String) A list of measured values of the meter in corresponding message.
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice