Skip to content
v26.3

🔌 Hardware Agent & Cloud Failover

In cloud operation, the POS runs on {name}.next.dikas.de — but the receipt printer and the card terminal are in your venue, on your own network. The cloud cannot reach into that network from the internet: your router does not let connections from outside into the venue network. The hardware agent bridges the gap. It is a program on a device in the venue that connects to the cloud from the inside and carries out the POS jobs — printing receipts, taking card payments, searching for devices — on site.

Who needs this?

Businesses whose POS runs in the cloud (temporarily or permanently) and that use devices in the venue: receipt printers, kitchen printers, card terminals. If the POS runs locally on a DiKAS box, it talks to printers and terminal directly and needs no agent. See also Cloud & Local Machine.

Labels in German

Some screens mentioned here are only available in German: the hardware agent page and the printer settings in the admin area, the Druckerstatus page of the POS, and the Android app „DiKAS Agent". Their labels are quoted in German below, with a translation in brackets.

Without an agent, the cloud POS does not print into the venue

If no hardware agent is connected, the cloud POS sends no receipts to printers with an address from the venue network (e.g. 192.168.…). Instead, the printer status shows „Kein Hardware-Agent verbunden" (no hardware agent connected), and the test print in the settings says so immediately instead of reporting "sent". The receipts stay in the list of failed jobs and can be reprinted later with „Alle wiederholen" (retry all).


Which Devices Can Be the Hardware Agent?

Device As hardware agent How it is paired
App „DiKAS Agent" on an Android tablet or smartphone ✓ via QR code from the POS settings
DiKAS box (DikasArch appliance, mini PC) ✓ connects by itself if the hardware agent has been set up for your business — otherwise contact support
DiKAS app (POS on Android) ✗ —
DiKAS Windows client (DiKAS-Client-Setup.exe) ✗ —
Browser on a PC or tablet ✗ —

The agent device must be on the same network as the printers and the card terminal, stay switched on, and have internet access. A tablet that goes home in the evening is therefore not suitable as the only agent.

The hardware agent must be set up for your business

You can tell by a tab of its own: Settings → Hardware → Hardware agent. If this tab is missing, the hardware agent has not been set up for your business — please contact DiKAS support. Only administrators see the tab.


What Runs Through the Agent?

Function Through the agent
Card payment (ZVT) ✓ payment, reversal, refund, end-of-day — on the network terminal in the venue
Receipt and kitchen printing (ESC/POS) ✓ to network receipt printers on the venue network
Device search ✓ „Drucker suchen" (search printers) and the terminal search scan the venue network
A4 document printing ✗ — on a DiKAS box the POS prints A4 directly via the box; otherwise the PDF opens in the browser for printing
TSE signature ✗ — the TSE stays bound to the local POS (or cloud TSE), see TSE

Direct or via the agent — automatically

When the POS runs locally, DiKAS talks to the devices directly. When it runs in the cloud and an agent is connected, jobs go through the agent automatically — you do not switch anything in the POS.


Setting Up

App „DiKAS Agent" on an Android device

  1. Install the app „DiKAS Agent" — you get it from DiKAS support.
  2. On the POS, as an administrator, open Settings → Hardware → Hardware agent. It shows the cloud address („Cloud-Adresse"), the pairing secret („Kopplungs-Secret") and a QR code.
  3. In the app, choose the role „Hardware-Agent (Kasse: ZVT/Druck)".
  4. Tap „Per QR koppeln" (pair via QR) and scan the QR code on the POS screen. Cloud address and secret are taken over. Alternatively, enter both by hand and tap „Speichern & Verbinden" (save & connect).
  5. The app shows „Verbunden ✓" (connected). In the POS settings, the status now reads „1 Gerät verbunden" (1 device connected).

The secret applies to your whole business

Anyone who knows the pairing secret can connect a device as a hardware agent of your business. Do not pass it on, and show the QR code only while setting up.

You can pair several devices. If one fails, another takes over (see Several devices: the master).

DiKAS box

A DiKAS box connects to the cloud by itself if the hardware agent has been set up for your business. You do not enter anything on the box. If the status in the settings shows „Kein Gerät verbunden" (no device connected) even though the box is running, contact DiKAS support.

Why the agent on the box survives a server outage

On the DiKAS box, the hardware agent runs as a separate service, independent of the POS server. If the POS server crashes, the agent stays connected — printers and card terminal remain usable in cloud operation (see Cloud failover).

Checking that everything works

Under Settings → Hardware → Hardware agent, the status shows:

Display Meaning
„1 Gerät verbunden" / „2 Geräte verbunden" (1 / 2 devices connected) The agent is ready. Prints and card payments from the cloud go through it.
„Kein Gerät verbunden" (no device connected) No agent reachable — switch the device on, check network and internet, open the app.
„Nicht eingerichtet" (not set up) Setup is missing for your business — contact DiKAS support.

The status updates by itself. When the last device disconnects, „Kein Gerät verbunden" appears only after about 20 seconds — so a short connection drop does not cause a false alarm.


Setting Up Printers When the POS Runs in the Cloud

You set up printers as usual under Settings → Hardware → Printers (in detail: Hardware → Receipt printers). In cloud operation, the following also applies:

  1. Connect the hardware agent first (see above). Without an agent, the cloud finds no printer in the venue and does not print there.
  2. Choose „Drucker suchen" (search printers) — with a connected agent, the venue network is scanned. Or choose the connection type „IP" and enter the address of the printer on your venue network in the field „IP-Adresse", with port, usually 9100 — e.g. 192.168.1.50:9100. The address is usually printed on the printer's self-test page or shown in your router's device list.
  3. Save and trigger a test print („Testdruck"). If no agent is connected, the test print answers immediately with „Kein Hardware-Agent verbunden …" instead of "sent". The same applies to the width test („Breiten-Test") and to the test print in the receipt editor.

Do not enter 127.0.0.1

127.0.0.1 means "this device itself". Seen from the cloud, that is the DiKAS server — there is no printer there, whatever port (9100, 9101 …) is entered. With an agent, it is the agent device itself. That only works for a printer connected via USB or serial to a DiKAS box that is itself the agent — that is what the connection type „Lokal" with „Usb 1" to „Com 4" is for. For a network printer, always enter its own address on the venue network.

Printers with a public address

If a printer is reachable via a public IP address or an internet host name with port forwarding, the cloud prints there directly, even without an agent.

What the printer status reports

When a print fails, a red printer icon appears at the top of the POS. It leads — just like Menu → Printers — to the Druckerstatus page (printer status). For every failed job, it shows an instruction, with the technical message in small print below:

Message starts with What is wrong What to do
„Kein Hardware-Agent verbunden" (no hardware agent connected) The POS runs in the cloud and no agent is connected. Switch on the agent device in the venue, open the app „DiKAS Agent" or check the DiKAS box; check the status under Settings → Hardware → Hardware agent. Then „Alle wiederholen" (retry all).
„Drucker nicht erreichbar" (printer not reachable) The printer does not respond. Is it switched on and connected to the network? Are the IP address and port (usually 9100) correct under Settings → Hardware → Printers?
„Der Hardware-Agent hat den Auftrag erhalten …" (the agent received the job …) The agent is connected, but the printer did not accept the receipt. Check the printer as seen from the agent device: switched on, paper loaded, address correct, on the same network as the agent.

Several Devices: the Master

If several agent devices are connected, exactly one works as the master: receipts, card payments and the device search go to this device. If the master fails, jobs go to another connected device right away; if the master is gone for more than about 20 seconds, that device becomes the master itself.

Every agent device must reach all printers

Whoever is master prints all receipts. If agent devices sit on different networks, or a printer is attached via USB to a DiKAS box, another device cannot reach that printer. In that case, pair only devices on the same network, or only the box.

The device list

Under Settings → Hardware → Hardware agent, the section „Gekoppelte Geräte" (paired devices) lists every individually paired device with:

  • name and type: „Windows-Kasse" (Windows POS), „DiKAS-Box" or „Android-Gerät" (Android device),
  • „Online" or „Offline" (or „Gesperrt", blocked),
  • „Master" if the device is currently carrying out the jobs,
  • „(fest)" (fixed) if it has been set as master by hand.

If none is paired yet, it reads „Noch kein Gerät gekoppelt." (no device paired yet). Devices that connect via the QR code or the pairing secret — the app „DiKAS Agent" and the DiKAS box — are counted in the status above („1 Gerät verbunden"); they do not appear individually in the list. Among them, DiKAS picks the master itself: the device that has been connected the longest.

Button Effect
„Als Master festlegen" (set as master) This device receives the jobs as long as it is connected — even if another device was master. If it is not connected, another one steps in.
„Automatisch wählen" (choose automatically) Removes the fixed setting; DiKAS picks the master itself again.
„Sperren" (block) After a confirmation prompt, the device is disconnected immediately. It can no longer print or take payments, and it cannot pair again until it is unblocked. Meant for lost or retired devices.
„Entsperren" (unblock) Lifts the block. The device must then pair again.

A short connection drop (under about 20 seconds) does not cost a device from the list its master role.

Check the fixed master after maintenance

A setting made with „Als Master festlegen" can be lost after maintenance work on the server. If the note „(fest)" is missing afterwards, set the device again.

Only administrators can see and change the device list.


Cloud Failover: the Local Server Fails

If the local POS server goes offline (power outage, network, defect), business has to go on. DiKAS detects the outage and offers to switch to the cloud:

  1. The POS regularly checks whether the local server is reachable.
  2. If it fails and the cloud is reachable, a notice appears at the bottom: "Local server unreachable — switch to cloud?"
  3. After confirming, the POS loads the cloud address {name}.next.dikas.de. The local settings (workstation, printer/terminal assignment) are carried over and the user name is pre-filled — just sign in again.
  4. Hardware keeps working if a hardware agent is connected: card payment and receipt printing now go through the agent, which keeps running independently of the POS server. Without an agent, the POS reports „Kein Hardware-Agent verbunden".
  5. Once the local server is back, the POS offers to switch back.

Instant relay during failover

The instant relay requires the running local server and is therefore not available during failover. Printing and card payment in cloud operation run through the hardware agent.


Switching Online Manually

You can also switch from local operation to the cloud without an outage — e.g. to keep working while on the road. For this, the POS main menu shows the entry "Switch online" (with local operation, e.g. on the DiKAS box or the Windows register, as soon as a cloud address is known). It performs the same switch as a failover. The Android app does not have this entry.


Troubleshooting

What you see Cause What to do
The cloud POS prints nothing, the printer status shows „Kein Hardware-Agent verbunden" No agent device connected Switch on the agent device, open the app „DiKAS Agent" or check the DiKAS box; the status under Settings → Hardware → Hardware agent must show "… verbunden". Then „Alle wiederholen".
The test print answers immediately „Kein Hardware-Agent verbunden …" As above — the test print first checks whether the way to the printer is open Connect the agent, then test print again
The Hardware agent tab is missing in the settings The hardware agent has not been set up for your business (or you are not signed in as administrator) Sign in as administrator; if the tab is still missing, contact DiKAS support
„Drucker nicht erreichbar" Printer off, cable unplugged, wrong address or wrong port Switch the printer on, check the network cable, check IP address and port (usually 9100)
„Der Hardware-Agent hat den Auftrag erhalten, der Drucker hat ihn aber nicht angenommen" The agent device cannot reach the printer, or the printer has a problem Check paper, cover, power; is the printer on the same network as the agent device?
The printer is set to 127.0.0.1 (e.g. with port 9100 to 9108) That is the device itself, not the printer Enter the real address of the printer on the venue network, e.g. 192.168.1.50:9100. Use „Lokal" (Usb/Com) only for printers attached directly to a DiKAS box that is the agent
A device shows „Offline" in the list Device off, asleep, without internet, or app closed Switch the device on, check the network, open the app; if needed, turn off battery optimisation for the app so that Android does not close it
A device shows „Gesperrt" and no longer connects An administrator blocked it If it should work again: „Entsperren", then pair it again
Status „Kein Gerät verbunden" although the DiKAS box is running The hardware agent is not set up on the box Contact DiKAS support

Frequently Asked Questions

Do I need to install anything on the DiKAS box? No. The agent is part of the box software and connects by itself as soon as the hardware agent has been set up for your business.

Can my Windows POS be the hardware agent? No. The DiKAS Windows client is a POS interface and does not control devices for the cloud POS. Use a DiKAS box or an Android device with the app „DiKAS Agent".

Do I need port forwarding on the router? No. The agent builds the connection to the cloud from the inside.

Do card payment and printing work when the local server is off? Yes — through the hardware agent, as long as an agent device in the venue is connected. The cloud must know the addresses of terminal and printers; they are found and saved via the device search.

What if no agent is connected? The cloud POS then reports „Kein Hardware-Agent verbunden". Printing and card payment in the venue are only possible again once an agent device is connected. Failed receipts can then be reprinted with „Alle wiederholen".

Are card payments charged twice during failover? No. If the result of a payment gets lost, the POS reports an error instead of retrying automatically — this prevents a double charge.


Next Step

→ Hardware: setting up receipt printers · Cloud & Local Machine · Card Payment