🔌 Hardware Agent & Cloud Failover¶
In cloud operation, the POS runs on {name}.next.dikas.de — but the actual hardware (card
terminal, receipt printer) is in the store. The hardware agent bridges this gap: a
lightweight program on the store network that executes payments and printing locally and is
controlled from the cloud via an outbound connection. This way, the hardware keeps working
even when the POS is no longer running locally but in the cloud.
Who needs this?
Locations that run their POS in the cloud (temporarily or permanently) but use local devices. Purely locally operated POS systems talk to their hardware directly and don't need the agent. See also Cloud & Local Machine.
Who Can Be an Agent?¶
The hardware agent is already built into the DiKAS device apps — nothing extra needs to be installed:
| Host | Platform | Role |
|---|---|---|
| DikasArch appliance | Mini PC (Arch Linux, Electron kiosk) | POS and hardware agent in one |
| DiKAS Mobile | Android (MAUI app) | Mobile POS with agent function |
| DiKAS Device Agent | Android tablet | pure hardware agent (without POS UI) |
Any device on the store network can be an agent. If several are connected, one takes on the task; if one fails, the others continue serving.
What Runs Through the Agent?¶
| Function | Via the agent |
|---|---|
| Card payment (ZVT) | ✓ Payment, void, refund, cash register cut — at the network terminal |
| Receipt printing (ESC/POS) | ✓ to network receipt printers or locally connected USB/serial printers |
| Device discovery on the network | ✓ finding terminals and printers on the store network |
| A4 document printing (CUPS) | ✓ via the appliance's local printer bridge |
| TSE signature | ✗ — the TSE remains bound to the local POS (or Cloud TSE), see TSE |
Direct vs. agent — automatic
If the server can reach the device directly on the network (local operation), DiKAS talks to it directly. If the POS is in the cloud and an agent is connected, it runs automatically through the agent — without any switching in the operation.
Pairing¶
The agent connects to the cloud on its own (outbound, NAT-friendly — no port forwarding needed). Authentication happens per tenant via a secret derived from the license.
- DikasArch appliance: pairs automatically — it knows its tenant from the license and
derives the cloud address (
{name}.next.dikas.de) and pairing secret itself. - Tablet/Mobile: pairing via QR code from the admin area (cloud address + secret).
The connection status (connected devices) is shown in the admin area under Settings → Hardware → Hardware Agent.
Cloud Failover: Local Server Goes Down¶
If the local POS server goes offline (power outage, network, hardware fault), the business must keep running. DiKAS detects the outage and offers to switch to the cloud:
- The POS regularly checks whether the local server is reachable.
- If it goes down and the cloud is reachable, a notice appears at the bottom: „Lokaler Server nicht erreichbar — auf Cloud wechseln?" (Local server unreachable — switch to cloud?)
- After confirming, the POS loads the cloud address
{name}.next.dikas.de. The local settings (workstation, printer/terminal assignment) are carried over, and the username is pre-filled — you just need to log in again. - Hardware keeps working: card payment and receipt printing now go through the hardware agent, which continues running independently of the POS server. A4 printouts run via the local printer bridge.
- Once the local server is back, the POS offers to switch back.
Why the agent survives the outage
On the DikasArch appliance, the hardware agent runs as its own service, separate from the POS server. If the POS server crashes, the agent stays connected — the devices remain operable in cloud mode.
Instant relay during failover
The instant relay requires the running local server and is therefore not available during a failover. Local printing and card payment in cloud mode run through the hardware agent (or the printer bridge for A4).
Switching Online Manually¶
Even without an outage, you can switch from local operation to the cloud — e.g. to keep working while on the move. For this, the main menu of the POS shows (on appliance and mobile, as soon as a cloud address is known) the entry „Online wechseln" (Switch online). It performs the same switch as during a failover.
Frequently Asked Questions¶
Do I need to install anything on the appliance? No. The agent is part of the DikasArch software and pairs automatically via the license.
Do card payment and printing really work when the local server is down? Yes — via the hardware agent, provided a device is connected on the store network. The cloud must know the devices (terminal/printer addresses); these are found and stored via device discovery.
What if no agent is connected? In cloud mode, the POS then reports a clear error message ("no hardware agent connected") — card payment/printing become possible again only once a device is connected.
Are receipts double-charged during a failover? No. If the result of a payment is lost, the POS reports an error instead of automatically retrying — this avoids a double charge.