This document is a quick startup guide to create a Saia PCD® application with the M-Bus FBox library.
Even if your application is not exactly as assumed here it is stronly recommended going through these steps in order to get a first basic application running. In a second step you can then adapt it to match your requirement.
1. Purchase – Download – Install the M-Bus FBox library
Two versions of the M-Bus library exist.
- The "Saia reduced" library which only supports Saia Burgess Controls M-Bus meters. This version of the library can be obtained free of charge from the Saia Burgess Controls.
- The complete (full) Engiby M-Bus library.
This document was written for the full version but can be also useful for the reduced version.
Once your M-Bus library is correctly installed, you should see it in the PG5 Library manager and in the Fupla FBox selector the FBox familiy "M-Bus" appears.
2. Working principle
The working principle of M-Bus is as following. The Master (a Saia PCD® in our case) sends a general Data Request telegram to an M-Bus address. The corresponding device returns its standard data package. Each value has a unique identification, consisting of Data type (energy, volume, temperature, etc…), a Unit number, a Tariff number, a Storage number and some additional and optional codes. The master driver decodes the response and searches for the required values in this data package. This coding is called DIF and VIF and is normally unique for each value in a device. Based on VIF and DIF, the M-Bus FBoxes are able to find a value even if its place in the telegram is not known. The response returned by the M-Bus device is defined by its configuration. Some devices have a fix configuration, some can be configured with a special tool, and others need a special telegram to be sent to the device in order to select a given configuration. Because of this working principle, it is not possible to ensure that any device can be read with one unique implementation. However, after several years of experience Engiby has developed an M-Bus library that allows you to read a lot of M-Bus devices (probably 90% of all Volume meters, 80% off all Heat Meter devices and 50% of all Electricity meters on the market) without specific development.
3. Hardware installation
If you have an external M-Bus converter, connect the M-Bus meter to the converter on the M-Bus line output. Supply the converter with 24V. Connect the RS232 line to a RS232 port of the PCD (direct connection is usually required).
If you have a Saia M-Bus module PCD2/3.F27x, plug the module into one of the 4 first slots, connect the M-Bus meter to the M-Bus terminals and 24V to the supply terminals.
Note that most heating and water meters are powered by the M-Bus itself and therefore doesn’t need additional power supply. Electricity meters in contrary usually need to be powered to work on the M-Bus.
In case of doubt, consult the manual of the device or contact the provider.
4. Prepare the PG5 project
We assume that you have now correctly installed the M-Bus library with your license key. Prepare a PG5 project; create a new device and a Fupla file.
Alternatively you can also download this project example for a quick start.
Hint: when you start working with a new PCD device, open the Device configurator and upload the configuration from the device. Save the configuration and close the Device configurator. After that, open the "Build Options" and click "Set Default". In this way, you are sure that your PCD device settings match the connected PCD.
5. M-Bus master driver
In your Fupla file first place the M-Bus Driver FBox (called "M-Bus Master" in some versions) which is found in the "M-Bus Drivers" FBox family. In this FBox select the used channel and the "Serial line type".
For working with a Saia M-Bus module (PCD2/3.F27x), select the option ‘M-Bus/F27x’, else select RS232.
For a first test, keep the other parameters as default.
6. M-Bus device FBox
After the Driver FBox, one or several M-Bus device FBoxes can be placed. To find the correct FBox to use, proceed as follow:
- Consult the list of tested devices (List of supported devices). If your device is in the list, use the indicated FBox.
- Else, check the type of your M-Bus device (Heating, Water or Electricity) and use the Generic 01 FBox of the corresponding family (Standard Variant for electricity).
For a first test, connect a "0" at the "Enable" input (En).
In the FBox, set the M-Bus address of the device. Not yet configured devices usually have the address 0 or 1. If you don’t know the device address and only one device is connected to the bus, use the "Test address" 254. Every device always responds to address 254.
Your application is now ready for a first test. Build, download and run the application in the PCD.
7. Runtime test
The M-Bus Driver FBox should be green at startup. Double-click on the device FBox to get the online view of the property window and click the "Read" button. Within 1 to 10 seconds, you should get the device identification (based on serial number of the device) at the FBox outputs.
If this ID is correctly shown, your installation is basically working correctly.
In case of an error, check the help for a description of the error code and consult the description of typical errors below.
If your FBox does not exactly match the connected device, you may have an error "Missing value". Note that for the Energy and Power values, the basic unit (Wh, MWh, J or GJ and W or MW) is also a selective parameter and must match the device configuration.
You can also make a basic communication check with the FBox "Data Request" from the "M-Bus General" family. It will only return the Status bits and the device identification that all devices must provide.
8. Extend your application
Once you get a positive result with the above test, you can extend your application.
Set the read interval in the FBox to a lower value (e.g. 15 min) and put a "1" at the "Enable" input.
Add further device FBoxes and adjust the addresses to read more devices from the bus.
You can setup several busses in parallel by placing further M-Bus Driver FBoxes. In this case, each of them must have a different name. The device FBoxes must also refer to the corresponding Master.
You can use the "M-Bus Additional Values" FBox after any other device FBox to get further data (see point 10 below).
9. FBox variant 01 and 02
Each FBox exists in a variant 01 and 02. The list of the returned values is the same but the difference is in the formatting of the values. At the same time, the variant 01 has FBox output connectors while the variant 02 has a register array defined by its base address.
- FBox variant 01: With the FBox variant 01, the returned values always have the same unit even if the device changes the format of the value in its telegram (what cannot be excluded in operation). Saia PCD registers have a size of 32 bits which allows coding of values with up to 9 digits. In case of overflow of the value, the upper digits are truncated (max value is 999’999’999). This has the consequence that the selection of a too small unit will add zeros as lower digits and may cause the loss of higher digits.
Conclusion: FBox variant 01 have the advantage to return their values with a fix resolution but may lose higher digits of big values.
- FBox variant 02: With the FBox variant 02, the values are returned as received by the counter. The loss of higher digits will only occur for 12 digits and 64 bits values. No format conversion is made and no 0s are added as low digits. This also means that the value unit may change depending on the device configuration and even during operation. For this reason, the FBox returns an exponent (conversion factor in power of then) in a second register. Because a PCD register only has 32 bits, it may be complex to convert the value in the PCD. Using float format is not a good solution for counters because the precision is only 4 to 5 (most significant) digits. But you can read the values with the exponent and convert it on a supervisor that may have 64 bits precision.
Examples: Value 123 with exponent 3 = 123000. Value 4567 with exponent -2 = 45.67.
Conclusion: FBox variant 02 have the advantage that no digits are lost (except for 12 digits and 64 bits values) but the value resolution is not fix and must be taken into account by the exponent register.
10. Additional values
Maybe you can read the device with an existing FBox but you need additional values which are not read by the existing FBox (e.g. a second energy from an additionally configured pulse input). In this case you can read this additional value with the FBox ‘M-Bus Additional Values’. Check first how the additional values are identified (Data type, Unit, Tariff, Storage), e.g. using NG-MScan2 which is a free Engiby tool to scan your M-Bus devices and identify the provided data.
If the desired values can not be read, please ask the provider of the device for an M-Bus specification of the device and send it to Engiby for analysis. If possible send also a scan file made with NG-Mscan2. Special cases that are not covered by this FBox still exist and a specific FBox must be developed by Engiby.
11. In case of problems
Only two typical errors cases are shortly explained here. See the trouble shooting document, referenced below, for more details.
- The most common errors are hardware and addressing errors. Remember that as long as you have errors code in range 1 to 29 (The FBox shows ‘Read fails’) you should check your installation and the device address.
Once you get the device ID, the communication is physically working.
- Error "Missing value". If you get this error, it means that the device can be addressed and is responding on the bus. But, in the response telegram, one or more values required by the FBox are missing.
- First verify the selected unit for the Energy and the Power in the FBox. The FBox selection must match the device configuration.
- Ensure that you have used an FBox made for your device. It might be a new version of the same type or a new type of the same manufacturer.
- If you have used a Generic FBox, check if a specific FBox exists for this device.
- If you don't find the reason, ask for an M-Bus specification of the device and send it to Engiby for analysis.
If you contact Engiby for support, please indicate first wheter you have
- a library installation problem
- a build error (report the error message)
- a runtime error
- a driver error (codes 1 to 29)
- a device FBox error (Id returned but problem with returned values)
Please provide the following data:
- M-Bus device(s) you are using
- Network topology (Saia F27x module or external converter)
- PCD systems with firmware versions (including the FW version of the F27x module if present)
- M-Bus library version in use
- Used communication port
- Used device FBoxes
- Error code of the M-Bus Master FBox
- Error code of the device FBox
- Error occurrences (each reading, every x reading or x times per hour)
- Scan file created with NG-Mscan 2
- Other particular points and relevant information.
12. Further useful links