Gateway Simulator¶

A page where you run simulated Qundis Q gateway 6 units on an MQTT broker. Each one behaves like a real gateway: it connects only while it is awake, with the real client id, it receives what the broker kept for it, and it answers every message the vendor's notes describe. You give it meters, and it sends their telegrams during a readout, with readings that grow over time.

Use it to test a tool that reads gateways, when no real gateway is at hand, or when you need a gateway to do something on request: connect now, restart, lose its network.

It is not a real gateway, and it is not the system that collects a building's readings. It sends what you give it, to the broker you name.

Words used in this manual¶

A gateway is one simulated Q gateway 6 direct, with its own serial, broker, meters and state.
A wake is the time a gateway is connected to its broker. A real gateway sleeps the rest of the time, and so does this one.
A task is a direct metering readout: the period the gateway listens for meters, from the moment it starts until it finishes or is stopped. Only a telegram sent during a task is forwarded.
A seed is one captured wireless M-Bus telegram. A simulated meter sends it again and again, with its readings and its date brought to the present.

Starting a gateway¶

Type the serial: 8 digits. The gateway's client id is nrg_qgw6d_ followed by the serial, and its topics start with nrg/qgw6direct/ and the serial.
Name the broker: its address, its port, whether it uses TLS, and the username and password the gateway connects with. If you are signed in, you can choose a preset instead: a broker an administrator saved, whose address and password stay on the bench.
Press Start.

The page then shows the gateway, and its address changes to the link to this gateway. Keep that link: whoever has it can see and change this gateway, and nobody else can. Press Copy beside it to copy it.

← Back, at the top left, returns to the start page, with the start form and your gateways. The browser's own Back does the same. The gateway keeps running: only the page stops showing it.

The gateway keeps running when you close the page. It keeps running when the bench restarts too: it is kept in the bench's database, with its meters.

A real serial on a real broker

A gateway with the serial of a real gateway, on the broker that real gateway uses, disconnects the real gateway while it is connected, because both use the same client id. Its readings also arrive as if they were the real gateway's readings, for the real meters of a real building.

The bench cannot prevent this: the broker is a real one, and you have its password. So use a serial that no real gateway has, or a broker made for tests. Every start, every change and every button you press is logged with your address, your account if you are signed in, the broker and the serial.

The buttons¶

Manual connection: Like a long press of the real gateway's button. The gateway wakes at once, with reason Manual connection. If it cannot connect, it does not try again, as a real gateway does not after a button wake.
Reboot: The power is cut and restored. The gateway wakes with reason Boot, its reset counter grows by one, and what a real gateway loses at a reboot is lost. A gateway with no power says nothing to the broker. So the offline message comes from the broker, when the broker stops waiting for the gateway: up to 7.5 minutes later. But the gateway is online again after 10 s. Some brokers send the offline message at that moment, and some send none at all.
No network: A switch. While it is on, every wake searches for a network for 5 minutes and then fails, so you can watch the gateway try again later, with a longer wait each time. This is a property of the place the gateway is in, not of the bench. If the gateway is connected when the switch is set, the gateway stops sending at once, as a modem with no network does. The offline message comes from the broker, up to 7.5 minutes later. The gateway tries again 7.5 minutes after it lost the network.
Delete: Stops the gateway at once and deletes it, with its meters and its settings. Its link stops working. You are asked first. The gateway closes its connection properly, so the broker sends no offline message. When the bench itself stops or restarts, the broker sends the offline message at once for every gateway that is connected at that moment. A gateway that is asleep has no connection, so nothing is sent for it.

Nothing else on the page acts on a gateway. Everything else is sent to it over MQTT, as to a real gateway: a readout, a new schedule, a filter list, a firmware image.

When a wake cannot connect¶

When a wake fails because the broker or the network refused it, the gateway's page says why, under the next wake, with the time. The card says the same. The reason is a sentence, for example:

The broker refused the username or password.
The broker refused this account. The broker knows the username, but the account may not connect.
The broker refused the client id.
The broker is not available.
The TLS connection to the broker failed. For example, the broker's certificate is not for its address.
Nothing answers at this address and port.
a sentence about the address or the port, when this bench may not connect to it;
No network: the gateway searched for 300 seconds and found none. This is the No network switch.
The broker refused the subscription.

Under the sentence, in small type, is the original text: the MQTT return code, or the message of the error. The reason is cleared when the gateway connects again. It is not a warning: a warning is about the system you test, and this is about the broker or the network.

Meters¶

A gateway has no meters when it starts. To add one, paste a seed under Add seed and press Add seed.

What a seed must be¶

Base64 or hex, one telegram.
Not encrypted. A telegram in security mode 0. Decrypt an encrypted one before you add it.
The length byte first, and the length byte is the frame's size minus one.
No block CRCs. This is the form the gateway itself sends a telegram in.
At least one current value in an OMS record: energy, volume, or heat cost allocator units, at storage 0. A value inside a manufacturer's own record does not count.

A seed that is not one of these is refused, and the page says why.

What the bench changes in a seed¶

Each time the meter transmits, the bench writes into a copy of the seed:

every current value at storage 0: the seed's value, plus its step for each radio interval since the meter was added;
every date at storage 0, from the gateway's clock, in the meter's own time. Meters keep standard time, so the default is UTC+1 all year.

Nothing else is changed. A value at another storage, such as a month end, and anything inside a manufacturer's record stay as they were captured. A reading never falls, also after a restart of the bench. A value that becomes too large for its record is shown as an error on that meter, and that telegram is not sent.

The other fields¶

Interval: How often the meter transmits, in seconds. 120 if you give nothing, and at least 10.
Steps: How much each current value grows at each interval, in the unit of its record. One step for each value, separated by commas. 1 for each value if you give nothing.
Signal: The signal strength the gateway reports for this meter, in dBm. A small random spread is added to each telegram.
Type: The telegram type a task's type filter compares. PDD, OMS meter is the usual choice.
Radio mode: The wireless M-Bus mode the meter transmits in. A task hears the meter only when the task listens in that mode.

Remove, in a meter's row, removes that meter.

What else the page shows¶

Gateway: the schedule (CRON, in UTC) and the timeout, the firmware, the reset counter, the battery, the network values, and the gateway's own counts of its connections and messages.
Filter lists: the lists the gateway holds, each with its count and its CRC.
Tasks: the task that is scheduled, and the one that is running.
Gateway raw data: every message in and out, live and newest at the top, with the time, the topic and the JSON. The topic is shown without nrg/qgw6direct/<serial>/, so ul/ is from the gateway and dl/ is to it. A line marked Note is not a message: it says what the bench did, such as a connection that failed. The (i) of a line explains the message as the gateway bench does: each value with its name and its meaning, then its QoS and whether the broker retained it. The Topic chips show only the lines of the topics you choose, and Clear filters shows them all again. The bench keeps the last 2,000 messages of each gateway, in memory, so a restart of the bench empties it. A JSON longer than 1,024 characters is kept cut, and ends with (cut). Copy copies the lines shown, with the whole topic, and Clear view empties the page and not the bench.

Signing in¶

You do not need an account. An account gives you two things:

the presets: brokers an administrator saved, which you choose by name;
Your gateways: the gateways you started, so you do not need to keep each link. An administrator sees every gateway. See below.

An administrator also keeps the presets and invites people. An invitation is a link the administrator copies and sends.

Edit, beside a preset, opens the preset in the same window as Add a preset. The password field is empty, because the page is never shown the password. Leave it empty to keep the password, or type a new one. Remove the password leaves the preset with no password. A gateway on the preset uses the change the next time it connects. A gateway that is connected now keeps its connection. The first administrator is invited by whoever installed the bench.

Your gateways¶

When you are signed in, the start page shows a card for each gateway you started. A card shows:

the serial, and the state: Asleep, Connecting, Awake, In a task, No network or Stopped, with the same words as the gateway's page;
the broker, and the next wake with its reason;
the number of meters, the telegrams of the last task (or of the task that runs now), the connections made and failed, and the battery charge;
the warnings, if there are any: how many, and the newest one in full;
why the last wake could not connect, if it could not. See When a wake cannot connect.

Manual connection on a card is the same as Manual connection on the gateway's page. You can press it only while the gateway is asleep. Otherwise the card says why, for example It is connected now. Open opens the gateway's page.

The cards change by themselves every few seconds. On a phone they are one under another.

Warnings¶

A gateway keeps a warning when the system you test sends it something a real gateway would not expect. The gateway still does what a real one does. The warning is there so that you see it, because the gateway's own answer is easy to miss in the log.

Several starts: A start arrived while another task was scheduled or running. The warning says what happened: the scheduled task was replaced and will not run, or the new task begins when the running one ends.
More than one start in one connection: A second start arrived while the gateway was connected once. The warning names every task of that connection and the reason the gateway woke.
A start in the past: The start time was before the moment the start arrived. The warning says how late it was, and whether the gateway accepted it (less than a day late) or refused it (more than a day). A start time of 0 means "now", and gives no warning.

The gateway's page lists the warnings, the newest first, each with the last time it happened and how many times. The same warning again is counted, not listed again. A gateway keeps the last 20, also when it reboots and when the bench restarts. Clear warnings empties the list.

Limits¶

At most 20 gateways from one address, and 200 on the whole bench.
At most 500 meters on one gateway.
A gateway whose page nobody has opened for 30 days is stopped and removed.
A broker can be named only on the ports the bench allows, and only at an address on the internet, or at this bench's own host when the bench allows it.

What a simulated gateway does not do¶

It cannot check the signature of a firmware image, because the key is Qundis's. An image of the right size and shape is accepted.
It has no repeaters, so it never reports a repeater table.
It does not connect with a client certificate: a broker with no authentication, or a username and password.
When the bench restarts, each gateway that should have woken in that time connects at once with reason Retry. The tool under test sees this.