Generic Modbus Reader

Almost every plant has a controller that knows things nothing else reports: the door contact of the transfer station, the UPS of the communication cabinet, a transformer's over-temperature relay, a fire detection panel. The Generic Modbus reader lets you read such signals from any Modbus TCP device yourself — you say which address means what, watch the live value while you do it, and decide per signal whether it is only recorded or raises an alarm. This guide walks through setting one up and explains every choice on the way.

What It Is For

The reader turns values of a Modbus device into signals of the plant's alarm system:

• a contact or status bit — door open, breaker tripped, UPS on battery;
• a measured value — a cabinet temperature, a pressure, a battery voltage — optionally compared against a limit.

Each signal appears as a live tile and on the state timeline of the plant's Alarm system page, and — if you choose so — opens a park event that notifies people. It is not a way to collect production data: inverters, meters and plant controllers are onboarded as data loggers with their own adapters.

Strictly Read-Only

The reader can only ask a device for values. It uses the four reading requests of Modbus and nothing else:

It never writes a coil or a register, never changes a setting and never sends a command — neither in normal operation nor in any of the tools. It also never scans: only the addresses you define, or explicitly ask for in a tool, are read. Addresses in between are not touched.

Setting Up a Reader

Open in Mirox: Dataflow — or open Your plants, pick a plant, and switch to the Dataflow tab.

A reader is set up in the same dialog as every other logger and stays in that one dialog from the first step to the last:

1. Click Add Logger, pick the device from the network-device list and choose the adapter Generic Modbus reader (read-only). The reader is never offered in Possible Loggers — nothing on the wire says what a controller's addresses mean, so it is always added by hand.
2. Continue. The dialog widens and carries on with the reader's steps: Device → Connection → Signals → Review. You can step back at any time; nothing is saved before the Review step.

The left sidebar of the dialog shows the live status the whole time: the device and its address, whether the live connection to the plant is up, the Device check, and — from the Signals step on — the Live values with the time of the last reading and how many of your signals could be read. A Read-only badge in the header is the reminder that nothing is ever written to the device.

Device

The reader is bound to one network device of the plant and reads exactly that device's IP address. Three rules follow from this:

• The address must lie inside the plant's networks. A device outside them is refused with a hint.
• One device feeds one reader. If a reader already reads the device, add your signals to that reader instead.
• A device a reader reads cannot be deleted from the plant; delete the reader first.

Connection

Under Advanced you find the timeout (1–30 s, default 5 s), the default word and byte order for all signals, and whether addresses are displayed starting at 0 or at 1.

The Device check in the sidebar tests the connection as you type: Modbus answers (with one result per table), TCP open but no Modbus reply (something listens on the port, but it is not Modbus or the unit ID is wrong) or Not reachable.

Signals

The Signals step is the workbench: the list of your signals, each row with what the device answers for it right now. An empty list asks how you want to start — Add signal, Paste a list or Find contacts with Learn. All three are described under Adding signals and can be mixed freely.

The Read and Learn tools open from the toolbar next to the list and close again; in a narrow window the tool takes the place of the list until you go back to it. The last step, Review, is described further down.

Adding Signals

A signal is one value read from one address of the device, plus what it means and what should happen when it changes. There are three ways to add signals. They all end in the same list, so use whichever fits what you have in hand:

While you work, every row shows its live value: the list is read every two seconds, so you see at once whether an address answers and whether its condition is met right now. Nothing in the draft raises an alarm — that only starts once the reader is saved and its changes are applied.

Add a Signal by Hand

What it is for. Full control over a single signal. It is the way to add a measured value with a limit, and to fine-tune a row that came from a pasted list or from Learn.

What happens. Add signal appends a row and opens its editor in place. As soon as table and address are set, the row is read from the device and shows its value; whenever you change a field, it is read again. A field that is missing or contradicts another one is marked in the row with a hint, and you cannot continue to Review until it is resolved.

What to do. The editor has four sections; work through them from top to bottom.

1. Signal — what it is.
   • Name (up to 80 characters): this is the text people read in the notification, so write it the way you would say it on the phone — "Station door open", not "DI 3".
   • Kind: UPS, Door / gate, Transformer and so on. It decides the icon, the group on the Alarm system page and the level a new signal starts with, and it is the type named in every notification.
2. Source — where the value is read.
   • Table: one of the four Modbus tables — see Tables.
   • Address: type it the way the device list writes it. The notation switch next to the field accepts 0-based, 1-based, Modicon (40001, 30201, 400123 — the leading digit names the table) and Hex (0x0064). Choosing 0-based or 1-based also decides how addresses are displayed for this reader — in the list, in Review and on the Alarm system page; it changes nothing about what is read. Examples: Addresses and notations.
   • Read as: how the value is interpreted. A coil or a discrete input is always On / off. For a register, choose Single bit of a register for a status word, or one of the number types for a measurement — see Data types.
   • Bit (only for a single bit): which of the register's 16 bits. Bit 0 is the least significant. The live strip shows all 16 bits with yours highlighted, and the mask (bit 3 = 0x0008) to compare with the device list — see Bit numbering.
   • For numbers, optionally a Unit, a Factor and an Offset — see Scaling.
3. Active when — the condition that makes the signal count as active.
   • A contact or bit: Reads 1, Reads 0 or Never. If you are unsure how the contact is wired, bring the plant into its normal state and click Mark current state as normal.
   • A number: choose the comparison — above, at or above, below, at or below, equal to, not equal to — and the comparison value. For above and below, add a Hysteresis so that a value hovering at the limit does not raise and clear over and over.
   • Optionally a Minimum duration: the condition has to hold without interruption for this long before the signal counts as active. Leave it at At once if every occurrence matters. How it is counted: Minimum duration.
   • The line Right now: underneath says whether the condition is met at this moment — the quickest check that polarity and limit are right. While a minimum duration is running, it says so: met for 40 s of 5 min — not active yet.
4. Action — what the signal does: the Mode (Off, Record or Alarm) and, for Alarm, the Level (Levels). A signal needs a condition to be in mode Alarm.

Under Advanced you find the signal's own unit ID for a device behind a gateway, the word and byte order of 32-bit values, and the exact request that is sent to the device.

Typical signals:

Paste a List

What it is for. Taking over many signals at once from the controller's documentation or the integrator's spreadsheet instead of typing them.

What happens. Pasting alone adds nothing. Mirox reads the text and shows a preview of every row as the signal it would become; only Add n signals appends the valid rows to your list. Signals that are already in the list are not changed.

What to do.

1. Arrange the spreadsheet columns in this order — or keep your own order and put a header row with these names on top:

   #	Column	What to write	If left empty
   1	name	The signal's name	— (required)
   2	address	A plain number, counted from 0 or from 1 as the reader displays addresses; 0x0064 or 64h for hex; a Modicon reference such as 40001 when the table column is empty	— (required)
   3	table	coil, discrete input, holding register or input register (short: di, hr, ir, or fc1 … fc4)	Taken from a Modicon address
   4	type	bool, bit, uint16, int16, uint32, int32 or float32	On / off for coils and discrete inputs; for registers a single bit if a bit is given, otherwise a 16-bit whole number
   5	bit	0 … 15, for a single bit	Bit 0
   6	active value	Contact: 1 or 0. Number: a comparison such as >45, <=10, =3 or !=0	Contact: active at 1. Number: value only, no condition
   7	kind	ups, door, intrusion, fire smoke, power supply, breaker, main switch, transformer, switchgear, surge protection, grid protection, cabinet climate, water leak, communication, generator, other	Other
   8	level	critical, very high, high, normal, low, very low	The starting level of the kind
   9	minimum duration	5 min, 90 s, 2h; a plain number is seconds. Only on a row with a condition	At once

   The terms in the columns table, type, kind and level are written in English, as shown.

2. Copy the rows, click Paste a list and paste them into the field. Rows copied straight from a spreadsheet work, as do semicolon- or comma-separated lines.

3. Check the preview. Each valid row shows its name, table and address, how it is read, when it is active (with its minimum duration), its kind and its level. A row with an active value becomes a signal in mode Alarm; a row without one is a plain value in mode Record.

4. Rows with a problem are marked in red and say what is wrong instead — for example Unknown table, No table given, and the address is not a Modicon reference, or The bit must be a number from 0 to 15. They are left out; the button counts only the valid rows. Correct them in the spreadsheet and paste again, or add them by hand afterwards.

5. Click Add n signals. Back in the list, look at the live values: a row that cannot be read, or that is active although the plant is in its normal state, needs a second look.

A list you can copy and try:

name;address;table;type;bit;active value;kind;level;minimum duration
Station door;100;discrete input;bool;;1;door;normal;2 min
UPS on battery;101;discrete input;bool;;0;ups;high;
Transformer over-temperature;40011;;bit;3;1;transformer;very high;
Cabinet temperature;200;input register;int16;;>45;cabinet climate;normal;10 min

The third row has no table: the Modicon reference 40011 makes it holding register 10, bit 3. Scaling (factor, offset, unit) is not part of the list — set it in the row afterwards.

Find Contacts with Learn

What it is for. Finding the address of a contact when you have no list, when the list is doubtful, or when you want proof that the address you entered really is that door.

What happens. Learn reads one small window of one table over and over — the range you give it: up to 64 coils or discrete inputs, or up to 16 registers. The first reading is the baseline. From then on, everything that differs from the baseline is highlighted, with the value before and now and how often it changed. A contact that was operated and has already returned stays listed as changed and came back, so a short pulse is not lost.

Learn reads only this window. Nothing outside it is touched, no address range is searched, and — as everywhere in the reader — nothing is written. While Learn runs, the live values of the signal list pause; a reader that is already in operation keeps polling and alarming.

What to do.

1. Bring the plant into its normal state — doors closed, breakers in, mains present.
2. On the Signals step, open Learn (on an empty list: Find contacts with Learn). Choose the Table, the Start address and the Count for the range where the contacts are expected. The digital inputs of a controller usually sit side by side.
3. Click Start and wait for the first reading. The tool then says Nothing changed yet.
4. Have the person on site operate one contact — open the door, trip the breaker — and tell you when. The address that changed (for registers: the bit) is highlighted.
5. Click Add as signal on that row. Table, address, bit and condition are filled in: the baseline is taken as the normal position, the other position as active. Give the signal its name and kind.
6. Have the contact put back, then repeat with the next one. If things got mixed up — several contacts moved, or the plant was not in its normal state when you started — click New baseline to start again from the current state.
7. Click Stop when you are done. If the device refuses the window, choose a smaller or a different one.

The Read Tool and the Live Status

Everything in this section asks the live device, read-only. While you use it, a reader that is already in operation keeps polling and alarming — there is no blind window. One live session runs per plant at a time: it ends with a note if someone else starts one, and it closes by itself after 15 minutes without activity.

Read

What it is for. Finding out what an address really holds when the documentation is vague — the right data type, word order or bit.

What happens. One read of 1 to 16 addresses of one table, once. The result shows the Raw words with their 16 bits each and, under As a number, the value in every data type and word/byte order. Nothing is scanned: Previous address and Next address are each a new single read of the neighbour.

What to do.

1. On the Signals step, open Read from the toolbar.
2. Enter the table, the address and the count, and click Read.
3. Find the interpretation that gives a plausible value and click Add as signal next to it — table, address, type and order are taken over.
4. In a status word, click a bit to add that bit as a signal; what it reads now is taken as normal.

Live Values and Device Check

• Live values — the signal list is read every two seconds. Each row shows the raw value, the decoded and scaled value and whether the condition is met right now — and, if the read failed, why: Address not available on this device or Device did not answer. The sidebar sums it up: the time of the last reading and how many signals were read.
• Device check — in the sidebar: is the port open, does the device speak Modbus, and which of the four tables answer.
• Request on the wire — under Advanced in a row: the exact request that was sent for this signal.

Review

The last step reads every signal once more from the device and shows what is about to be saved: the reader, its alarm system and the signals by mode. When you edit an existing reader, it also lists the signals that are removed (their history stays, their open alarms are closed) and those that are read differently afterwards.

Two findings need your attention before you can save:

• Signals that cannot be read block saving until you correct their address or switch them off — Switch off does that right there.

• Signals that would raise immediately. A signal in mode Alarm whose condition is met right now is listed with the note that it would raise an alarm once the reader is deployed — right away, or after its minimum duration, which is shown next to it. That is meant literally: the first reading after the change is applied opens an alarm and notifies people — for a signal with a minimum duration, once that time has passed and the condition still holds. Look at each one:

  • The condition is really present (the door is open): fine, the alarm is correct.
  • The plant is in its normal state: the polarity is wrong. Go back to Signals and use Mark current state as normal.

  To continue, tick I understand that these alarms are raised right away, or after their minimum duration.

If the signals could not be read once more — the live connection ended, for example — you can save anyway; the same applies unseen: an alarm signal whose condition holds raises its alarm once the reader is deployed.

Saving and Applying Changes

Saving a reader stores its definition; the plant's data collector starts using it when the change is deployed.

• Save and deploy applies it right away. The plant's data collector restarts and all of its data sources pause for about a minute. A signal with a minimum duration starts counting again after this restart; an alarm that is already open stays open meanwhile.
• Save only keeps the change pending. Apply it later with Apply changes on the Dataflow page, together with other pending changes.

Save and deploy also applies every other pending change of the plant, exactly like applying the pending changes on the Dataflow page, and it is offered only to people who may deploy there. When nothing the plant reads has changed — a new name or level only — the button is simply Save and no deploy is needed.

The Signals tab of the Alarm system page shows where each reader stands: Not deployed yet, Changes pending or deployed.

To change signals later, use Edit signals on the reader — on the Dataflow page or on the Signals tab. If someone else changed the reader in the meantime, the wizard tells you and lets you reload without losing your draft.

Deleting a reader takes effect immediately: the data collector restarts and all pending changes of the plant are applied with it. Alarms still open for the reader are closed without a notification; the alarm system the reader fed is removed with it, unless it still has other signals. Its events stay in the plant's activity list, and the recorded series are kept. If it was the plant's last alarm system, the alarm page and its navigation entry disappear again until a new reader is set up.

What You See Afterwards

Once the changes are applied, the reader polls the device at its interval and the plant's Alarm system page fills. If this is the plant's first reader, the page appears in the plant's navigation by itself.

• Status tab — one live tile per signal, grouped by kind. A contact shows Active or Normal and since when; a measured value shows the number with its unit; a signal in mode Record is labelled recorded only. Below the tiles are the history of each signal over 24 hours, 7 days or 30 days and the list of Raised alarms.
• Signals tab — the reader with its state (Not deployed yet, Changes pending or Deployed) and whether it is reading, and the signal table with the value now, mode and level. Name, kind, level and the switch between Record and Alarm can be changed right there and apply immediately; Edit signals opens the dialog again for everything else.
• Dataflow page — the reader appears among the plant's loggers.

A signal that is waiting out its minimum duration shows Normal until the time has passed.

Notifications

A signal in mode Alarm sends two notifications: one when it raises and one when it clears. You do not have to set up the second one — closing the alarm sends it.

• Name and type. Both notifications carry the plant, the alarm system, the signal's name exactly as you wrote it and its type — the kind you chose, such as UPS, Door / gate or Transformer, in the language of each recipient. This is the same on every channel: in the app and as mobile push, by email and by webhook. It is why a clear name pays off.
• Who receives them. That is not set at the signal. Every person decides in their own notification settings whether the Alarm system category is on and from which level; the signal's level has to reach it. Out of the box the category is on only for the technical manager, from Very high, in the app.
• How many people that is. An organization Admin sees next to the level picker how many of the people with access to the plant would be notified at that level — a number only, never names.
• What sends nothing. A signal in mode Record. An alarm that is closed because its signal was switched away from Alarm, removed, or its reader deleted. A changed name or level — nobody is notified a second time for an alarm that is already open.
• A chattering signal. If one signal raises four times within an hour, the fifth sends a single summary and that signal's notifications pause for 30 minutes — see Levels. A minimum duration or a hysteresis usually cures the cause.

If the reader cannot read the device at all, that is an alarm of its own with its own notification — see When signals are not readable.

Defining Signals

A signal is one value read from one address, plus what it means. Every signal has a name (up to 80 characters) and a kind — door, UPS, transformer and so on — that decides its icon, its group on the Alarm system page and the level it starts with.

Tables

Modbus keeps four separate tables. The device's documentation says which one a value lives in.

Addresses and Notations

Device lists write addresses in different ways. The address field has a notation switch so you can type what the list says:

In the Modicon notation the leading digit names the table — 0 coil, 1 discrete input, 3 input register, 4 holding register — and the rest is the 1-based number, in the 5-digit or the 6-digit form. If you type a number that looks like a Modicon reference while another notation is selected, Mirox offers to read it that way; it never converts silently.

Whatever you type, each row shows the address in your chosen notation, and its tooltip shows the plain 0-based address and the Modicon form. Addresses run from 0 to 65535.

Data Types

Bit Numbering

For the type Bit you choose which of the register's 16 bits is meant. Bit 0 is the least significant bit, bit 15 the most significant. The picker shows the mask next to the number — bit 3 is mask 0x0008 — and a strip with the register's 16 live bits, most significant on the left, with your bit highlighted. If the device list counts bits from 1 or from the other end, compare the mask.

Word and Byte Order

A 32-bit value occupies two registers, and devices disagree on which half comes first. Word order is high word first (the default) or low word first. Byte order — big-endian (the default) or little-endian — is the order of the two bytes inside each register. Both have a default for the whole reader and can be overridden per signal.

You rarely need to know the answer in advance: the Read tool shows the same registers decoded in every combination, and the one that gives a plausible value is the right one.

Scaling and Unit

For numeric types you can set a factor and an offset: displayed value = raw value × factor + offset. A temperature transmitted in tenths of a degree gets factor 0.1. The unit (up to 16 characters) is display text only.

Devices Behind a Gateway

A signal may carry its own unit ID that overrides the reader's. That is how several devices behind one Modbus gateway are read through a single reader.

Conditions and Hysteresis

The condition says when a signal counts as present. On the Alarm system page 1 always means "the condition is present" and 0 means normal — however the contact is wired.

• Contacts and bits — choose which value is the alarm state: active when 1 or active when 0. A fail-safe contact that opens on alarm is active when 0. If you are unsure, bring the plant into its normal state and use Mark current state as normal — per row or for all rows.
• Measured values — compare against a limit: equal, not equal, greater than, greater or equal, less than, less or equal.

For the four threshold comparisons you can add a hysteresis so that a value hovering around the limit does not raise and clear over and over. Example: greater than 70 with hysteresis 5 becomes present above 70 and clears only at 65 or below. Between the two, the signal keeps the state it had.

A signal without a condition is a plain value: it is shown and recorded, but it cannot raise an alarm.

Minimum Duration

Optionally, per signal, you can say how long the condition has to hold before the signal counts as active — one minute, five minutes, ten minutes or any other time up to 24 hours. Without it, which is the default, a signal is active as soon as a reading finds the condition met.

What it is for. Conditions that are harmless when they are brief: a door someone walks through, a temperature that peaks for a few minutes, a supply that dips for a moment. It works for contacts and for limits alike; a signal without a condition cannot have one.

What happens.

• The clock starts with the first reading that finds the condition met.
• The signal becomes active at the first reading at or after the end of the duration that still finds it met. The alarm's start time is that moment — when the duration was reached, not when the condition was first seen.
• Any reading that finds the condition not met resets the clock. Separate short periods are never added up.
• While the clock runs, the signal is normal. Its tile and its history show Normal — not No reading — and nothing is raised or sent.
• After a restart of the data collector the clock starts again. Every deploy restarts it. If the condition is met at the first reading afterwards, the signal is not reported until its duration has passed again or the condition is gone — its tile can show No reading for that time. An alarm that was already open stays open and nobody is notified a second time; a condition that is new at that moment raises after the duration, as always.
• Clearing is immediate. The duration only delays raising. The first reading that finds the condition gone clears the signal and closes the alarm; for limits the hysteresis still applies.
• A reading that fails neither resets the clock nor completes it; the decision waits for the next reading that succeeds.

What to do. In the row editor, under Active when, set the time in seconds or minutes. In a pasted list it is the ninth column. Changing it needs a deploy.

Do not put a minimum duration on signals where every second counts — an intrusion or fire alarm should stay At once.

Modes: Off, Record, Alarm

• Record suits what you want to look up but not be called for — a gate that is opened every day.
• Off stops the reading itself. Use it for a contact that is documented but not wired, so that it cannot stand in alarm forever.
• New signals start in Alarm with the level of their kind; a signal needs a condition to be in this mode.

Switching between Record and Alarm applies immediately. Switching to or from Off changes what is read from the device and needs a deploy. When a signal leaves the Alarm mode, an alarm still open for it is closed without a notification.

Levels

Every signal in mode Alarm has one of the six alarm levels, from Critical down to Very low.

For signals read by the generic Modbus reader, the level is assigned by the plant's technical operator, per signal — only they know what a contact means on that plant. Every other alarm keeps its fixed, platform-defined level. Whether a signal notifies you still depends only on whether you enabled the Alarm system category and on your own minimum level there (enabled by default only for the technical manager, from Very high).

The kind proposes a starting level, which you may change:

Keep the meaning of the levels in mind when you choose: Critical is for possible physical danger, and it is what people leave switched on. A signal placed too high is soon ignored.

• Who would be notified. An organization Admin sees next to the level picker how many of the people with access to the plant would be notified at that level. It is a number only — never names — and it counts people who selected a channel for the category at that level.
• Changes apply immediately. A new name or level takes effect at once, without a deploy. An alarm that is already open keeps who was notified for it; nobody is notified a second time.
• A chattering signal is muted, not the plant. If one signal raises four times within an hour, the fifth sends a single summary and that signal's notifications pause for 30 minutes. Other signals are unaffected, and every occurrence is still recorded as an event.

When Signals Are Not Readable

If the device does not answer three polls in a row, or keeps refusing a configured address, the plant shows 'Alarm signals not readable' — the signals are then unknown, not normal.

• It is an event of its own in the Alarm system category with the fixed level High, and it sends a resolution notice when reading works again.
• "Three polls" follows your polling interval: about 30 seconds at 10 s, three minutes at the default 60 s, 45 minutes at 900 s.
• While a signal is unknown, nothing is cleared: an alarm that was open stays open until the device itself reports the condition as gone. A missing reading is drawn as a gap on the timeline and marks the tile as stale — never as normal.
• Device does not answer points to the network path, the port or the unit ID. Address refused points to the signal definition — wrong table or address. The Review step and the live watch show which signal is affected.

Limits

• 64 signals per reader.
• Polling interval 10–900 seconds. Anything shorter than the interval can be missed; a reader is not a substitute for a latching contact or for the alarm transmission of a certified alarm panel.
• One reader per device, and one reader per alarm system.
• Modbus TCP only, reading only — no writing, no scanning of address ranges.
• Whole numbers and 32-bit floats — bool, bit, 16- and 32-bit integers, float32. Text and 64-bit values are not read.
• Signal values appear on the Alarm system page; they are not part of Metric Export or reports today.
• A plant that still runs on a hand-written configuration (see Configuring Data Loggers) cannot take a reader until it has been migrated.

Related Guides

• Alarm System — the page your signals appear on
• Alarm Levels — what each level means and who is notified from which level
• Configuring Data Loggers — onboarding inverters, meters and controllers
• Managing Network Devices — discovering the device a reader is bound to
• Notifications — switching the Alarm system category on and choosing your minimum level