ModbusBB user manual

1. Introduction

ModbusBB is a Modbus tool for Windows. It has three parts:

• Master (client): reads and writes data in Modbus devices such as energy meters, PLCs, inverters and drives.
• Slave simulator: acts like a Modbus device, so you can test a SCADA system or a PLC program without real hardware.
• Command-line tool (CLI): the same functions in a terminal, for scripts and automatic tests.

ModbusBB supports five ways (transports) to talk to devices: Modbus TCP, Modbus UDP, Modbus RTU (serial), Modbus ASCII (serial) and RTU over TCP (serial frames through an Ethernet gateway).

What you can do with ModbusBB

• Connect to several devices at the same time. Each connection has its own poll tabs.
• Read coils, discrete inputs, holding registers and input registers, once or every few milliseconds.
• Show values as 16, 32 or 64-bit integers, Float32, Float64, strings, hex or binary, in all four byte orders, with scale, offset and unit.
• Write values to coils and holding registers.
• See every byte that goes over the wire in the traffic monitor.
• Run diagnostics: device identification (FC43), Report Slave ID (FC17), Diagnostics (FC08), Mask Write (FC22), Read/Write Multiple (FC23) and raw requests.
• Find devices and registers with scanners, chart values over time, raise alarms, log data to CSV and save your setup as a workspace.

How to use this manual

Chapters 3 to 9 explain the daily work: install, connect, read and write. The later chapters explain the tools one by one. Numbered red marks in the screenshots match the numbered lists under them. Words in bold are names of buttons, menus and fields in the program. Technical words are explained in the glossary.

↑ Back to top

2. Requirements

↑ Back to top

3. Installation

Install with the installer (recommended)

1. Download ModbusBB_Setup_{VER}.exe from the download page.
2. Double-click the file. Windows may ask for administrator rights. Click Yes.
3. Follow the wizard. The program is installed in C:\Program Files\ModbusBB.
4. Optional: tick Add CLI to system PATH. Then you can type ModbusBB.CLI in any terminal window.
5. Optional: tick Create a desktop shortcut.
6. Click Finish. ModbusBB starts.

The installer creates three Start-menu entries: ModbusBB (the program), ModbusBB CLI (opens a command window with the CLI help) and the uninstaller.

Portable version (no installation)

1. Download ModbusBB_Portable_{VER}.zip.
2. Right-click the ZIP file and choose Extract All. Choose any folder, for example a USB stick.
3. Start GUI\ModbusBB.GUI.exe for the program, or use CLI\ModbusBB.CLI.exe in a terminal.

Update to a new version

Run the new installer over the old installation. You do not need to uninstall first. Your license, trial status and settings stay.

Uninstall

Open Windows Settings > Apps, select ModbusBB and click Uninstall. The folder %LOCALAPPDATA%\ModbusBB is kept on purpose. It holds your license activation and the trial record, so a later reinstall keeps working.

↑ Back to top

4. First start and the license window

Every time ModbusBB starts without a license, it shows the license window.

Click to enlarge

1. Trial Version: how many trial days are left. The trial lasts 30 days from the first start.
2. Session Time Remaining: in the trial, each session lasts 15 minutes. Then the program closes. Start it again for a new session.
3. Enter License Key: type your key in the format XXXXX-XXXXX-XXXXX-XXXXX and click Activate License. This needs internet.
4. Continue Trial opens the program in trial mode. Exit closes it.

With a valid license there is no time limit and the license window does not appear. The status bar shows Licensed in the bottom-right corner. More about keys, devices and moving the license: chapter 21.

↑ Back to top

5. The main window

The main window has a fixed layout. The left side is for connections. The right side is for data.

Click to enlarge

1. Menu bar: File, Connection, Tools, View and Help.
2. Connections tree: every connection and its polls. The buttons + Conn, + Poll, Rename and ✕ add, rename or remove items. A green dot means connected.
3. Connection settings of the selected connection: name, type, network or serial settings and timing.
4. Connect / Disconnect button. Below it: Scan Slaves, Scan Regs, Stats and Device Tools.
5. Poll tabs: one tab per poll. The dot shows the state of its connection.
6. Poll settings: name, slave ID, function, address, quantity and interval.
7. Read (read once, F5) and Start / Stop Polling (F6).
8. Format and Byte order for all rows of this tab, and the Cycle button.
9. Register grid: one row per value, with address, alias, format, value, engineering value, hex and binary.
10. Write value box and Write button.
11. Bottom tabs: Communication Log, Traffic (raw frames) and Alerts.
12. Status bar: how many connections are connected, active polls, logging and watchdog state, and the license state.

Below the connection buttons you also find Connect All, Start All Polls and Stop All. They act on all connections at once.

↑ Back to top

6. Connecting to devices

A connection is one link to one device or one network/serial line. You can have many connections at the same time. Each connection has its own settings and its own poll tabs.

Click to enlarge

1. Select the connection in the tree. Use + Conn to add a new one.
2. Name: any name, for example "Meter panel A". It appears in the tree, tabs, log and traffic monitor.
3. Type: the transport (see the table below).
4. Timing: timeout and retries.
5. Auto-reconnect: what happens when the link drops.
6. Connect / Disconnect.

Step by step: connect to a Modbus TCP device

1. Click + Conn (or Connection > Add Connection).
2. Type a Name.
3. Set Type to Modbus TCP.
4. Type the device IP Address and Port (Modbus default: 502).
5. Optional: click Ping to check that the IP address answers.
6. Click Connect. The dot in the tree turns green and the button changes to Disconnect.

Step by step: connect to a serial (RTU) device

1. Connect the RS-485 adapter. Windows gives it a COM port number (see Windows Device Manager).
2. Click + Conn and set Type to Modbus RTU (serial).
3. Choose the COM Port. Click Refresh if the port is not in the list.
4. Set Baud Rate, Data Bits, Parity and Stop Bits exactly as in the device. Common: 9600, 8, None, 1 (often written "9600 8N1") or 19200 8E1.
5. Click Connect.

The five transports

Serial settings

Timing

Auto-reconnect

When Reconnect automatically is on (default), ModbusBB opens a dropped link again and continues polling. The pause between attempts grows step by step:

When Reconnect automatically is off, a dropped link stops the polls of this connection.

Click to enlarge

Several connections at the same time

Add one connection for each device or line. All connections work at the same time. Connection > Connect All and Disconnect All act on every connection. Several devices on one RS-485 line share one connection; use a separate poll tab with its own Slave number for each device.

↑ Back to top

7. Polling and poll tabs

A poll is one read request that ModbusBB can repeat. Each poll has its own tab. A connection can have many polls, for example one for measurements and one for status bits.

Step by step: read data

1. Select the connection in the tree and click + Poll (or press Ctrl+T). A new tab opens.
2. Type a Name for the poll.
3. Slave: the device address (unit ID), 0–255. Most TCP devices use 1. Decimal or hex (0x..).
4. Function: what to read (see the table below).
5. Address: the first address, 0-based (see addresses). Decimal (400) or hex (0x190).
6. Quantity: how many registers (1–125) or bits (1–2000) to read.
7. Interval: time between reads when polling, 100 – 3600000 ms. Default 1000 ms.
8. Click Read (F5) to read once, or Start Polling (F6) to read again and again.

The line next to the Cycle button shows the counters: OK (successful reads), Err (failed reads), the last response time and the time of the last read.

Work with polls

• Rename: Connection > Rename Poll, or right-click the poll in the tree.
• Remove: click ✕ on the tab, or Connection > Remove Poll.
• Start or stop all polls: Start All Polls / Stop All (bottom of the left side).
• All polls of all connections can run at the same time.

↑ Back to top

8. Data types, byte order, scaling and addresses

A Modbus register holds 16 bits. Many values need more space: a Float32 or a 32-bit integer uses 2 registers, a Float64 or a 64-bit integer uses 4 registers. ModbusBB combines the registers for you. You choose the format and the byte order.

Click to enlarge

1. Format and Byte order for all rows of the tab. Cycle tries the next byte order.
2. Format column: change the format of one row.
3. Byte Order column: change the byte order of one row.
4. Regs: how many registers this value uses.
5. Value (raw decoded value) and Eng. Value (after scale and offset, with unit).
6. Scale, Offset and Unit of the row.

Formats

Byte order

Devices store multi-register values in different orders. If a value looks wrong (very large, very small or nonsense), the byte order is probably wrong. Click Cycle until the value looks right.

"A" is the most significant byte. Example: the float 230.5 is 43 66 80 00 in ABCD. In CDAB the device sends 80 00 43 66.

Scaling and units

Many devices send integers that you must scale. Engineering value = raw value × Scale + Offset. Example: register value 2305 with Scale 0.1 and Unit V gives 230.5 V. Type the scale, offset and unit in the row of the grid.

Addresses: 0-based, 1-based and Modicon

The Modbus message always carries a 0-based address (0–65535). This is what you type in the Address field. Device manuals often use other numbers:

View > Address Notation changes only how the grid shows addresses: 0-based (protocol / PDU), 1-based (register number) or Modicon (0xxxx / 1xxxx / 3xxxx / 4xxxx). Requests always use the 0-based address. View > Show Hex Addresses shows addresses in hex.

Click to enlarge

↑ Back to top

9. Writing values

You can write to coils (FC01 tabs) and holding registers (FC03 tabs). Discrete inputs (FC02) and input registers (FC04) are read-only. A read-only tab shows an orange note.

Method 1: Set Value column (fastest)

1. Read the tab once (F5) so the rows exist.
2. Click the Set Value cell of the row.
3. Type the new value in the format of the row (for example 21.5 for Float32, 1 or 0 for a coil).
4. Press Enter. ModbusBB writes the value and reads it back on the next poll.

Method 2: Write value box

1. Select a row in the grid.
2. Type the value in the Write value box under the grid.
3. Click Write.

Comma-separated values (for example 10,20,30) write consecutive rows in one request.

Which function code is used?

• With Use FC05/FC06 for a single value ticked, one coil is written with FC05 and one 16-bit register with FC06.
• Without the tick, and for more than one value, ModbusBB uses FC15 (coils) or FC16 (registers).
• 32-bit, 64-bit and String values always use FC16, because they need more than one register.

To write a bit mask or to write and read in one step, use Device Tools (FC22 and FC23).

↑ Back to top

10. Communication log and traffic monitor

The bottom part of the main window has three tabs.

• Communication Log: one line per request and response in plain words, with time and response time. Clear Log empties it, Export Log saves it to a file.
• Traffic (raw frames): every frame as bytes (hex and ASCII). Use it to see exactly what the device sends.
• Alerts: alarms from the watchdog.

Click to enlarge

1. Filter: show only frames that contain this text in hex, ASCII or connection name (for example 01 03). Next to it: All, TX or RX.
2. Connection: show only frames of connections whose name contains this text.
3. Pause stops capturing. Auto-scroll follows new frames. Clear, Copy (Ctrl+C) and Export... (CSV or TXT).
4. Max rows: 1000, 5000 or 20000 frames are kept.
5. Dir: TX = sent by ModbusBB, RX = received from the device.
6. Hex: the frame bytes. TCP frames start with the MBAP header (transaction ID, protocol ID, length, unit ID).

↑ Back to top

11. Device Tools and diagnostics

Tools > Device Tools (or the Device Tools button) opens a window for special Modbus functions. The top bar applies to all tabs.

Click to enlarge

1. Session (which connection to use), Slave ID, Timeout (empty = connection setting), Retries and Confirm writes (asks before any request that changes data).
2. One tab per function.
3. Category and Start object id.
4. Read identification.
5. The result: object, name, value and raw bytes. Copy and Export… save it.
6. Status line with the result and response time.

The tabs, explained simply

Click to enlarge

Click to enlarge

Click to enlarge

Click to enlarge

↑ Back to top

12. Register maps and the device library

A register map gives each address a name (alias), a format, a byte order, a scale and a unit. With a map you see "L1 Voltage 231.9 V" instead of "0x4367".

Use a built-in map from the device library

1. Create a poll tab for the device (for example FC04, address 0).
2. Open Tools > Device Library.
3. Type in the search box (manufacturer, model or name) and select the device.
4. Check the Default connection settings and the register list on the right.
5. Click Use this map. Names, formats and scaling are applied to the active tab.

Click to enlarge

The library contains maps for: ABB ACS580, Carlo Gavazzi EM24, Eastron SDM120, Eastron SDM630, Growatt inverters, Schneider Altivar, Schneider PM5xxx, SMA inverters and SunSpec common model. Export… saves a map as JSON or CSV.

Your own maps (File menu)

• File > Import Register Map...: applies a CSV or JSON map to the active tab's connection.
• File > Export Register Map...: saves the current names, formats and scaling.
• File > Create Register Map Template...: creates an empty CSV file to fill in Excel.

CSV columns: Address, Name, Description, Format, ByteOrder, Type, RegisterCount, ScaleFactor, Offset, Unit, MinValue, MaxValue, ReadOnly.

Click to enlarge

↑ Back to top

13. Scanners and connection statistics

Scan Slaves: find devices on a line

1. Connect the connection.
2. Click Scan Slaves (or Tools > Scan for Slaves).
3. ModbusBB asks slave IDs 1 to 247. A device that answers, also with an exception, counts as found.
4. At the end ModbusBB lists the IDs and offers to set the found ID in the active tab.

Click Cancel Scan to stop. Tip: a short connection timeout (for example 200 ms) makes the scan much faster.

Scan Regs: find valid registers

Scan Regs checks 1000 addresses from the address of the active tab, with the tab's function and slave. At the end it lists the ranges that answered and offers to jump to the first one.

Click to enlarge

Click to enlarge

Connection statistics

Stats (or Tools > Connection Statistics) shows each connection: protocol, endpoint, state, retries, auto-reconnect and, for each poll, the number of good and failed reads.

Click to enlarge

↑ Back to top

14. Slave simulator

Tools > Modbus Simulator (slave) turns your PC into a Modbus device. Use it to test a SCADA system, a PLC program or ModbusBB itself, without hardware.

Click to enlarge

1. Transport: Mode (TCP, UDP, RTU, ASCII), Port or COM settings, Start/Stop. Response delay + jitter slow down the answers so you can test timeouts.
2. Unit IDs: each unit ID has its own data. Type a number and click Add.
3. Tabs: Data, Generators, Exceptions and Request log.
4. Add, Remove, Add demo set and Clear all.
5. The generators: table, address, kind, minimum, maximum, period, step, format and byte order.

Step by step: start a simulator and read it

1. Open Tools > Modbus Simulator (slave).
2. Set Mode to TCP and Port to 5020 (port 502 may need administrator rights or be in use).
3. Open the Generators tab and click Add demo set.
4. Click Start. The status shows "Running".
5. In the main window, add a connection: Modbus TCP, IP 127.0.0.1, port 5020. Connect and read holding registers from address 0.

Data tab

Choose Unit, Table (holding registers, input registers, coils, discrete inputs), Start, Count (1–250), Format and Order. Edit values in the grid and click Apply edits. Auto-refresh updates the values twice a second.

Generators

Exceptions

On the Exceptions tab, Add rule makes the simulator answer certain requests with a Modbus exception (for example 02 Illegal Data Address). A rule can match a unit, a function code and an address range (empty = any).

Click to enlarge

↑ Back to top

15. Live trends

Tools > Live Trends draws the values of the active poll tab over time.

Click to enlarge

1. Pause, Clear, Follow live, Window (visible time span) and History (points kept per series) with an optional age limit.
2. Auto Y or a manual Min/Max with Set. Reset view returns to live mode.
3. Export CSV... (all samples) and Export PNG... (picture of the chart).
4. Series: tick to show a series. ✕ removes it.
5. The chart. Point at it to see the values at that time.
6. Sample main grid every: how often the values of the main grid are recorded.

Mouse: wheel = zoom time, Ctrl+wheel = zoom Y, drag = move, Shift+drag or right-drag = zoom box, double-click or Home = reset.

↑ Back to top

16. Watchdog alerts

The watchdog checks every value that is read. When a rule is true, it can raise an alert, write a line to a log file, play a sound or write a value to a device.

Click to enlarge

1. The list of rules. Tick a rule to enable it. New (Ctrl+N), Duplicate, Delete, Clear all.
2. Source & filters: address, and optionally tag, session (connection), slave and function. Empty = any.
3. Decoding: how the raw value is turned into an engineering value (format, byte order, scale, offset).
4. Condition, threshold, tolerance, debounce (number of samples the condition must be true), cooldown and Only on transition.
5. Actions: raise alert, log to file, play sound, write value.
6. Save rule (Ctrl+S). Revert discards changes.
7. Alert log file: the CSV file for the "Log to file" action.

Step by step: alarm when a value is too high

1. Open Tools > Watchdog Alerts > Configure Rules....
2. Click New and type a Name.
3. Type the Address of the value. Choose the Format and Byte order as in your poll tab.
4. Set Condition to Greater than threshold and type the Threshold.
5. Tick the actions you want, for example Raise alert and Log to file.
6. Click Save rule, then close the window.
7. Make sure Tools > Watchdog Alerts > Enable Watchdog is ticked.

Click to enlarge

↑ Back to top

17. Data logging and export

Log a poll to CSV

1. Select the poll tab you want to log.
2. Choose Tools > Data Logging > Start Logging Active Tab to CSV... and choose a file name.
3. Every successful read adds one line: Timestamp and one column per value.
4. Stop with Tools > Data Logging > Stop Logging.

The status bar shows 📝 Logging while logging runs. The CSV file opens in Excel.

Click to enlarge

Export one snapshot

Tools > Data Logging > Export Current Data... saves the values of the last successful read of the active tab to a CSV file.

Export the log

File > Export Log... or Export Log under the communication log saves the log lines to a file.

↑ Back to top

18. Workspaces

A workspace (.mbws file) saves your whole setup: all connections with their settings, all poll tabs, names, formats, scaling and units.

Click to enlarge

To start polling automatically when a workspace opens, tick Connect when the workspace is opened in each connection's Auto-reconnect section, then save. The CLI can run a workspace too: ModbusBB.CLI workspace run plant.mbws.

↑ Back to top

19. Command-line tool (CLI)

The CLI (ModbusBB.CLI.exe) does the same work as the program, in a terminal. Use it for scripts, scheduled tasks and automatic tests. It is in the CLI folder of the installation. If you ticked Add CLI to system PATH, you can type ModbusBB.CLI anywhere. The full reference is on the CLI page.

The basic pattern

ModbusBB.CLI <command> [options] <connection>

The connection options are the same for every command:

Example: read Float32 values and see the raw frames

Click to enlarge

Example: log to CSV and scan for devices

Click to enlarge

Example: device identification and statistics

Click to enlarge

All commands

Output formats

--output table (default, for people), --output csv (one row per value or sample) or --output json (one JSON object; poll writes one object per line). Data goes to stdout; messages, errors and --trace frames go to stderr. Colors switch off automatically when the output is redirected, or with --no-color.

Exit codes

Scripting tips

• Set default connection options once: set MODBUSBB_OPTS=--tcp 192.168.1.10 --unit 1 (PowerShell: $env:MODBUSBB_OPTS="--tcp 192.168.1.10 --unit 1").
• Use --quiet to hide the banner and --no-prompt (or MODBUSBB_NO_PROMPT=1) so the CLI never waits for input.
• Check %ERRORLEVEL% (cmd) or $LASTEXITCODE (PowerShell) after each command.
• Without a command, ModbusBB.CLI starts an interactive mode: connect once, then type commands without connection options.

foreach ($u in 1..5) {
  $r = ModbusBB.CLI read --rtu COM3 --unit $u --input --address 0 --format float32 --output json --quiet | ConvertFrom-Json
  if ($LASTEXITCODE -eq 0) { "Unit $u : $($r.values[0].value)" } else { "Unit $u : no answer" }
}

The trial limits apply to the CLI as well. With a license, the CLI checks the license online at most once a day.

↑ Back to top

20. Themes and view options

• View > Dark Theme: switches between light and dark. ModbusBB remembers your choice.
• View > Show Hex Addresses: addresses in hex.
• View > Address Notation: 0-based, 1-based or Modicon (display only).
• View > Communication Log, Traffic Monitor (raw frames), Alerts: jump to that bottom tab.
• Help > Keyboard Shortcuts: the list of shortcuts (see Appendix C).

Click to enlarge

↑ Back to top

21. License

Trial

The trial lasts 30 days from the first start. Each session is limited to 15 minutes. All functions work during the trial.

Buy and activate

1. Buy a license on the buy page. You receive the key by e-mail.
2. Start ModbusBB. In the license window, type the key (XXXXX-XXXXX-XXXXX-XXXXX).
3. Click Activate License. The PC must be online.
4. The status bar shows Licensed.

How many computers?

One license can be active on 3 computers at the same time. Changing small hardware parts does not count as a new computer.

Move the license to another computer

1. Open the license portal and sign in with your license key.
2. Deactivate the computer you no longer use. You can deactivate up to 5 computers in 30 days.
3. Activate the key on the new computer.

Working offline

After activation, ModbusBB works offline. It must reach the license server at least once every 30 days. If the server rejects the key (for example because it was refunded or is used on too many computers), ModbusBB returns to trial mode. A network error never removes your license.

Lost key?

Open Have your key e-mailed again (also linked from the license portal), or write to support@maxenergic.com.

↑ Back to top

22. Updates

ModbusBB checks for updates once a day at start. When a new version exists, it tells you. You can also check by hand: Help > Check for Updates.

1. Click Download Update. The download page opens in your browser.
2. Download the new installer.
3. Close ModbusBB and run the installer over the old version. Your license and settings stay.

↑ Back to top

23. Troubleshooting

RS-485 wiring in short

• Connect all devices in a line (daisy chain), not as a star.
• A to A (often D−/TX−) and B to B (often D+/TX+). Names differ between vendors; if nothing answers, swap A and B.
• Put a 120 Ω terminating resistor at both ends of the line.
• Connect the signal ground of all devices.
• Every device on the line needs its own slave ID and the same serial settings.

More: RS-485 wiring guide, timeout guide, error codes guide.

↑ Back to top

24. FAQ

↑ Back to top

Appendix A: Modbus function codes

More: function codes guide.

↑ Back to top

Appendix B: Modbus exception codes

A device signals an exception by returning the function code + 0x80 (for example 0x83 for FC03) followed by the exception code.

↑ Back to top

Appendix C: Keyboard shortcuts

In the watchdog editor: Ctrl+N new rule, Ctrl+S save rule. In the trend window: Home resets the view.

↑ Back to top

Appendix D: File locations

↑ Back to top

Appendix E: Glossary

ASCII (Modbus ASCII)

Serial Modbus variant that sends each byte as two text characters. Older and slower than RTU.

Baud rate

Speed of a serial line in bits per second, for example 9600.

Byte order

The order in which a device stores the bytes of a value that uses more than one register (ABCD, CDAB, BADC, DCBA).

Coil

A single on/off output bit that can be read and written (FC01, FC05, FC15).

CRC

Checksum at the end of an RTU frame. A wrong CRC means the frame was damaged.

Discrete input

A single on/off input bit that can only be read (FC02).

Exception

An error answer from a device: function code + 0x80 and an exception code.

Float32 / Float64

Decimal numbers in IEEE 754 format, using 2 / 4 registers.

Function code (FC)

The number in a Modbus request that says what to do, for example 03 = read holding registers.

Holding register

A 16-bit register that can be read and written (FC03, FC06, FC16).

Input register

A 16-bit register that can only be read (FC04).

Master / client

The device that asks (ModbusBB). The slave / server answers.

MBAP header

The 7-byte header in front of every Modbus TCP frame (transaction ID, protocol ID, length, unit ID).

Modicon notation

Old numbering with a prefix: 0xxxx coils, 1xxxx discrete inputs, 3xxxx input registers, 4xxxx holding registers.

PDU

Protocol Data Unit: the function code and data, without address/CRC or MBAP header.

Poll

A read request that ModbusBB repeats at a fixed interval.

Register

A 16-bit value in a Modbus device.

RS-485

The usual two-wire serial bus for Modbus RTU. Many devices can share one line.

RTU

Remote Terminal Unit: the binary serial Modbus variant with CRC.

RTU over TCP

RTU frames sent unchanged through a TCP connection, usually to a serial gateway.

Slave ID / unit ID

The address of a device on a line (1–247).

Workspace

A file (.mbws) that stores all connections, polls and settings.

↑ Back to top