2.2Modbus devices and datapoints

This is the installer reference for Modbus in Veltnova. It explains how Modbus RTU works, how to set up the serial port, devices and datapoints in the Configurator, how to use the values, and how to commission and troubleshoot a bus.

#1. Fundamentals

#Master and slaves

Modbus RTU is a serial protocol with one master and up to 247 slaves on the same bus. The master starts every exchange: it sends a request to one slave, and only that slave answers. Slaves never speak on their own, and a second master on the same bus causes collisions.

The Veltnova gateway is always the master. For each datapoint it sends one request, waits for the reply, checks the CRC (the error check at the end of every frame) and decodes the answer. Each slave is identified by its Slave ID (1 to 247), set on the device itself. Every device on one bus needs a different Slave ID. The gateway has two independent serial buses, RS485 and RS232, each with its own master and device list, so an ID only has to be unique within one bus.

#Data areas and function codes

A device exposes its data in four areas. The same address number can exist in more than one area, so you always have to say which area you mean. In the Configurator you choose it with the Read function.

#Registers and multi-register values

A register holds 16 bits, sent high byte first. A 16-bit value fits in one register. A 32-bit integer or float needs two consecutive registers, and text uses two characters per register. Some devices pack several flags into one status register; you read one flag with Bit number, where bit 0 is the least significant bit.

#Byte and word order

Modbus does not say which register of a 32-bit value comes first, so manufacturers differ. The four options are named after the four bytes of the number, A (most significant) to D (least significant). The table shows how the number 100000 (0x000186A0) arrives in the two registers for each setting.

If a 32-bit or float value reads as nonsense, change the word order first. It affects 32-bit integers and floats only.

#Addressing: protocol address, 1-based numbers and hex

On the wire a register has a protocol address from 0 to 65535, counted from zero. Manuals often print something else: zero-based addresses (often in hex), Modicon numbers (4xxxx holding registers, 3xxxx input registers, 1xxxx discrete inputs, 0xxxx coils, with six-digit variants such as 400001), or plain 1-based register numbers.

What this Configurator expects. The Data address field takes the zero-based protocol address. The gateway sends exactly the number you type, with no offset. Hexadecimal needs a 0x prefix (0x2000); decimal needs none (8192). Spaces are ignored and the value is limited to 0 to 65535. Hex digits without the prefix are read as decimal when they are all digits (0100 is 100) and otherwise, like 2000h or 1A, silently become address 0, so read the address back after typing it.

The area comes from the Read function, so never type the area prefix. Convert like this:

Some device families, SunSpec inverters for example, number registers 1-based but with real addresses in the 40000 range. The register documented as 40005 is then at protocol address 40004 (0x9C44): subtract one, not 40001. The built-in Fronius profile is converted this way. When in doubt, test with the Modbus Register Test (section 10) against a value you can see on the device. An off-by-one error usually returns the neighbouring register, not an error.

#2. What you need before you start

• The register map from the device manual: address, area (holding or input), data type, scaling and unit for each value.
• Whether the manual's addresses are zero-based, 1-based or Modicon.
• The device's Slave ID and serial settings (baud rate, data bits, parity, stop bits), and for 32-bit values its word order, if the manual gives it.
• RS485 wiring: a two-wire bus, A to A and B to B on all devices, run as a daisy chain and not a star. Vendors label A and B differently, so a silent device is often swapped. Connect the ground reference where the manual asks for it.
• Termination: a terminating resistor, normally 120 ohm, at each of the two physical ends of the bus. A short bench setup often works without; a long run needs it.
• RS232 is point-to-point, so one device per port. Use RS485 for several devices.
• A deployed gateway with its address and deploy token set in the Configurator, for the Diagnostics tests. See Deploying to a gateway.

#3. Serial port settings

Each bus has its own system object page: RS485 Interface and RS232 Interface. In the right-hand panel open the Server tab, then Interfaces, then the interface.

The gateway applies these settings to the port, with no flow control, when you deploy. They must match every device on the bus. Many devices use 9600 baud, 8 data bits, no parity and 1 stop bit, but check the manual: a mismatch is the most common reason for a silent device.

#4. Devices

Click Configure RTU Devices (N) to open the Modbus RTU Devices dialog. With no device yet it offers Add first RTU device.

The list on the left shows number, name and Slave ID, with the driver below. Under the list:

• Add creates a device from the Generic Modbus RTU profile, with the next free number as Slave ID (device count plus one), one starter datapoint and one starter command.
• Clone copies the selected device with its datapoints and commands, adds "Copy" to the name ("Copy 2" and so on if that name is taken) and keeps the Slave ID. The copy gets its own Reusable value ID and Reusable command ID from its new name, so it never writes to the original's values.
• Remove deletes the selected device with everything in it.

Edits are written into the project as you make them, so Save Changes and Cancel both just close the dialog. Save the project and deploy as usual.

#Device

Replacing datapoints. Choosing a profile in the Protocol driver list on a device that holds more than the starter datapoint and command asks Replace existing datapoints? Replace datapoints swaps in the profile defaults; Keep existing only changes the profile label. The Load button replaces straight away without asking. Either way the profile also sets the timeout and retries. Replacing deletes datapoints you added by hand, with their KNX settings.

#5. Datapoints

A datapoint is one value the gateway reads from a device. The Datapoints section of the device editor has a + button to add a datapoint and a trash icon on each one. Each datapoint is a card with its own fields.

The gateway sends one request per datapoint, so two datapoints on the same register (two bits of one status word) cause two requests.

#Identity

#Addressing and type

Registers beyond those used are read but ignored, so keep Register count at the minimum for the numeric types.

#Value processing

#Polling and live value

The gateway reads all polled datapoints one after another in device-list order, one request each, and starts the next round two seconds after finishing the previous one. It adds a 50 ms pause when the next datapoint belongs to another slave. There is no per-datapoint or per-device interval. A failed read does not stop the round: the datapoint is flagged stale, keeps its last value, and the gateway moves on.

#Publishing to KNX

How publishing behaves:

• The first successful reading after the Modbus engine starts is always published, and so is the first reading after a failed one. With Only on change off, every reading is published.
• For numbers the test is "difference at least Min change". With Min change 0 any difference counts, and an identical reading is not sent again. Set a small Min change (0.1 for a temperature, 1 for a 0 or 1 status bit) to also ignore tiny movements.
• The same test decides whether connected apps get a live update. The stored latest value is refreshed on every successful read regardless.
• Each KNX write happens inside the poll round and can take up to 3 seconds when KNX is slow, so many published datapoints lengthen the round.
• DPT 1.001 sends 0 as off and anything else as on. DPT 5.001 expects 0 to 100 percent and is clamped. DPT 7.001 and 8.001 are rounded to whole numbers.

The gateway's KNX engine must be running. See KNX basics for installers.

#6. Commands

A command is a named write that sends one or more values to the device in one frame.

Use function 10 (16 decimal) with several comma-separated values when a device needs two or more registers written together, for example a key register plus a command register. They travel in one frame, so nothing else on the bus can fall between them. The device answers with a short frame repeating the start address and register count.

#Sending a command or a value

Commands and write functions run when something asks the gateway to:

• Action Button, Run Modbus Command. Choose Run Modbus Command in the button's command list (category Modbus) and pick the command from the list of every command on every Modbus device. Pressing the button sends it.
• Action Button, Write Modbus Value. Choose Write Modbus Value, pick a datapoint that has a Write function, and enter the value. The value is turned back into register data through the datapoint's own scale, offset, data type and word order: with scale 0.1 and a 16-bit datapoint, 21.5 is sent as 215. A 32-bit or float datapoint needs write function 10 (two registers at once). A bit datapoint needs a coil function (05 or 0F), where any value other than 0 means on.
• Sun and prayer events can run the same two commands at a fixed time.
• Logic Studio. The Run Modbus Command block sends a chosen command when its input turns on (pick the command in the block's settings). The Command block can also run Run Modbus Command or Write Modbus Value from its command list; put the id or the value in its parameters.
• A KNX group address. Give a datapoint a Write function and fill in Write from KNX group address: every KNX write to that address is sent to the register. If the same group address also carries the datapoint's status (Send value to KNX), the gateway ignores the echo of its own status telegram, so a value is never written back to the device it came from.

The button's own Require PIN and User access rules apply. A failed write shows the reason on the button's screen (the device refused it, did not answer, or is switched off in the project), after the Retries you set. Commands are sent over the device's own bus: a serial bus that is not polling is opened just for the write.

#7. Built-in device profiles

A profile fills in datapoints and commands for a known device. Check it against your device's manual and firmware; its addresses are sent exactly as stored.

• Daikin. The datapoints carry the numbers printed in the adapter documentation (30001, 32001 and so on) literally. Check each one with the Modbus Register Test before relying on it. For air conditioning use the AC Manager, which has its own register handling for the adapter.
• Fronius. Pair it with the Solar Manager. The addresses are hex, already converted from the 1-based document numbers.
• MEBAY. The Genset Manager supplies the status and sends the start and stop block itself.
• Socomec. Select the device in the UPS Manager.
• Comwintop. Set the sensor's own unit register to metres of water once, with the vendor's tool, so the value reads directly as height in metres. Water Tank Pump Control can use this datapoint as its level source.
• Transmitter. The two relays switch on the device itself, from thresholds stored in the device.

#8. Using the values

Every polled datapoint becomes a reusable value that other parts of the project can pick.

• Analog Value: set Protocol to System Object, then pick the datapoint under System Value > Modbus RTU. The value is already scaled by the datapoint, so do not scale it again with the object's Factor. See Analog Value. The same picker exists on State Action, Generator Panel, UPS Panel (generic) and Solar Panel (generic).
• KNX: turn on Send value to KNX (section 5).
• Managers: the AC Manager, Genset Manager, UPS Manager and Solar Manager each have a Modbus RTU Device dropdown listing the devices you set up here. The AC and Genset managers list RS485 devices; the UPS and Solar managers list RS485 and RS232 devices. Configure the device first, then pick it. The manager reads and controls it with its own register map, in addition to your datapoints.
• History and graphs: the History Recorder can record a datapoint (source Modbus), and a Graph plots the history.
• Logic: Logic Studio has a System Value input and a System Value Changed trigger. The MQTT Client can publish system values.

A value that has not been read successfully for 15 seconds is flagged stale.

#9. Worked examples

These use generic devices on an RS485 bus, each at Slave ID 1. Use the addresses from your own manual.

#a) A temperature in a holding register, scale 0.1

A room sensor documents its temperature as holding register 40001, signed, in tenths of a degree.

First test it with the Modbus Register Test (RS485, Slave ID 1, FC3, Address 0, Count 1). At 25.3 degrees it returns Registers: 253 and the raw frame 01030200fd79c5, and the gateway shows 253 x 0.1 = 25.3. A raw 65526 is negative in two's complement: as signed it is -10, shown as -1.0, but as unsigned it would wrongly show 6552.6. On an Analog Value use Decimal Digits 1 and turn Sign on so a negative temperature keeps its minus.

#b) A 32-bit energy counter and its word order

An energy meter documents total energy as two holding registers from 40257, unsigned 32-bit, in units of 0.01 kWh.

The Register Test (Address 256, Count 2) returns Registers: 34464, 1 with raw frame 01030486a000011299. The first register is 0x86A0 and the second 0x0001. With the default ABCD the gateway joins them as 0x86A00001, which is 2258632705 and clearly wrong. With CDAB (low word first) the number is 0x000186A0 = 100000, and x 0.01 gives 1000 kWh. If the meter display also shows 1000 kWh, CDAB is right. If neither ABCD nor CDAB matches, try BADC and DCBA.

#c) Single bits from a status register

A pump controller documents a status word at holding register 40017: bit 0 Running, bit 1 Fault, bit 3 Remote mode.

Create three datapoints that share Data address 0x0010 (40017 minus 40001 is 16), Read function 03, Data type Bit / coil, Register count 1 and Scale / offset 1 / 0. Only the name and Bit number differ.

If the register reads 9 (binary 1001; the Register Test at address 16 shows Registers: 9, raw frame 01030200097842), the datapoints show Running 1, Fault 0 and Remote mode 1. To send a flag to KNX, turn on Send value to KNX, enter the group address, choose DPT 1.001 and set Min change to 1 so that only a real change between 0 and 1 is sent. If the manual counts bits from 1, or from the most significant end, convert first: this field counts from 0 at the least significant bit.

#d) A setpoint register with function 06, and its status on KNX

A boiler controller documents its temperature setpoint as holding register 40513, signed, in tenths of a degree, writable with function 06.

A raw 215 is shown as 21.5 and sent to 5/1/10; thanks to Min change nothing more is sent until the setpoint moves by at least 0.1. The Write function entry records that the register accepts function 06. Writing 21.5 degrees would be the frame 0106020000d7c82c (slave 1, function 06, address 0x0200, value 215). As the warning in section 6 says, the current gateway does not send writes for generic datapoints, so this example reads the setpoint and publishes it; change the setpoint on the controller itself.

#e) A two-register command with function 16

A drive documents a command block at 0x0300: the first register must hold the key 0x00A5 and the second the command, 0x0001 for start. Both must arrive in one frame.

The request is 0110030000020400a5000136bc (slave 1, function 16, start 0x0300, two registers, four data bytes, CRC) and the device replies 011003000002418c, repeating the start address and register count. The five bytes 0190030c01 would be an exception reply (function 16 plus 0x80, then code 03, illegal data value): the drive rejected the key or the command. The warning in section 6 applies here too: the definition is stored, but the gateway does not send generic commands yet. The Genset Manager sends a block of exactly this shape to a MEBAY controller by itself.

#10. Commissioning and verification

Work in this order: wiring, serial settings, a test read, one datapoint, then the rest.

#Modbus Register Test

Deploy first, with the serial interface enabled and its settings entered. Then click Diagnostics in the toolbar, open the Other Engines tab and use the Modbus Register Test card. The Configurator needs the gateway address in Settings and a paired deploy token (Deploying to a gateway).

Click Read. On success the card shows Registers: with the values in decimal, and the Raw frame, the whole reply in hex: slave ID, function, byte count, data and two CRC bytes. On failure it shows Read failed with the reason, such as timeout reading slave 1 function 3 (no reply) or slave 1 returned Modbus exception 2 (the device refused the address). The test waits up to 1.5 seconds. It needs no datapoint and shares the bus with normal polling; with no polled device the gateway opens the port just for the test. Use it first on every new device.

#Bus table

The same tab lists RS485 and RS232:

On a healthy bus OK grows and Errors stays near zero. Refresh updates the table.

#The gateway console log

Open the gateway console in a browser (see Gateway console and logs), go to the Monitor tab and set Log source to Modbus. Server Logs then shows the latest 80 lines mentioning Modbus. The lines to know:

A reply with a bad CRC is ignored and so appears as a timeout. The built-in managers log under their own tags, for example [genset] or [ac].

#11. Troubleshooting

#Device does not respond

#Wrong register or wrong value

#Writes are ignored

#Unstable or slow readings

#Value not on KNX

#Modbus exception codes

The log prints the code in decimal.

#Quick diagnostic procedure

1. Check power, then wiring: A to A, B to B, ground reference, termination at both ends.
2. Compare the device's baud rate, data bits, parity, stop bits and Slave ID with the interface page. Deploy.
3. In Diagnostics > Other Engines, check the bus is READY and shows the right device path.
4. Run the Modbus Register Test on a register the manual documents: the right bus, Slave ID, FC3, address 0, count 1.
5. On a timeout, repeat steps 1 and 2, then try FC4 and another Slave ID. On an exception, fix the address or function using the table above.
6. Once a register reads, compare it with the device display and adjust type, scale and word order until they agree.
7. Create the datapoint and compare Latest value with the device.
8. Open the gateway console, Monitor, Log source Modbus, and watch for timeout or exception lines while it polls.
9. Add KNX publishing and test the group address with the console's Send Telegram form or the Bus Messages list of the console's Monitor tab.
10. Add the remaining datapoints and watch OK / Errors for a few minutes.

#12. Limits and what is not supported

• Master only. The gateway reads serial devices (RTU) and network devices (Modbus TCP). There is no Modbus slave (server) mode: it cannot act as a Modbus device for another system. Modbus ASCII and Modbus RTU over TCP are not supported.
• Two buses, RS485 and RS232, each an independent master.
• Slave IDs 1 to 247 on a serial bus (broadcast, ID 0, is not available). A Modbus TCP device uses a Unit ID from 0 to 255.
• Reads use functions 01 to 04, one request per datapoint of up to 64 registers. Neighbouring datapoints are not merged into one request.
• Writes use functions 05, 06, 0F and 10, started by an Action Button, a sun/prayer event, a Logic Studio block, a KNX group address (datapoint setting Write from KNX group address) or one of the built-in managers (section 6).
• Polling is one sequential round over all datapoints with a two-second pause between rounds. There is no per-datapoint interval. A serial device that times out is tried again up to Retries times in the same round.
• Register Test reads function 3 or 4 only and takes a decimal address.
• Decoding: 16-bit types use the first register only, 32-bit types the first two.