Legacy Clients
HandyCafe can manage V3 and V4 client installations alongside modern clients on the same server. Legacy clients appear in the Admin Panel as their own card type, with a reduced action set that matches what the original protocol supports.
Before you can see legacy clients in the Admin Panel, enable runtime support under Settings > Legacy Clients.
How Legacy Clients Appear
Legacy clients connect to the server over the original UDP multicast protocol. They do not use mDNS like modern clients. Instead the server discovers them in two ways:
| Discovery Path | Trigger |
|---|---|
| TCP Login | The client sends a LoginRequest on the TCP command port. The server records the peer and emits a connected event. |
| UDP Ping | The client broadcasts a Ping frame on the multicast group. The server receives it, updates the peer record, and emits an online event. |
Per-MAC state is kept in a legacy client store with IP, hostname, logged-in user, client version, session timers, and a last-seen timestamp. Every inbound frame resets the inactivity timer. If the timer fires without traffic (default 10 seconds), the client is marked offline. The record persists in the database so history is not lost.
The Legacy Client Card
Each legacy client renders as a card distinct from modern client cards. The header shows the display name (hostname when available, MAC when not), an online or offline badge with color, and a status label.
Status Colors and Labels
| Status | Color | Meaning |
|---|---|---|
| Online | Green | An active session is running. |
| Idle | Cyan | The client is connected and waiting. No session active. |
| Paused | Amber | The session is paused. Billing is halted. |
| Busy | Purple | The client is processing a request. |
| Payment | Rose | The client is in a payment flow. |
| Admin | Indigo | The client is in an admin or maintenance mode. |
| Offline | Gray | No recent traffic. Actions are disabled until the client comes back online. |
| Timed | Sky | A time-limited session is running with a deadline. |
Session Clock
When a session is active, the card displays a clock block:
- Start time.
- End time (for time-limited sessions).
- Used minutes.
- Remaining minutes with a live countdown.
- Accrued cost.
Identity Info
The card always shows:
- MAC address.
- IP address.
- Client version (for example "3.4.01").
- Logged-in user if any.
Action Toolbar
When the client is online, an action toolbar below the identity info offers the available operations.
Session Control
| Button | Visible When | Behavior |
|---|---|---|
| Login | Status is idle | Opens the Device Login dialog. Select minutes and payment method. The server sends a Login command with the chosen values. The session starts on the client. |
| Logout | Status is online, timed, paused, busy, or payment | If the session is postpaid, a payment dialog collects the amount and method. A transaction is written to the ledger. The server sends a Logout command. The session closes on the client. |
Add Time
Opens a minutes picker. Accepts positive values (extend) or negative values (deduct). The maximum magnitude is 10,000 minutes in either direction. Works for both prepaid and postpaid sessions.
If you configured preset minute values in your pricing settings, the card also shows a row of preset buttons. Tap a preset to apply the value without opening the picker.
Screenshot
Requests a live screenshot from the legacy client over the file transfer port. The flow is:
- The server sends a screenshot request command.
- The client opens a short-lived TCP listener on an ephemeral port.
- The server connects, sends a 9-byte file transfer header, and waits.
- The client captures the screen, encodes it as a compressed BMP, and streams it back.
- The server decompresses the BMP and stores it in the
legacy_screenshotsfolder under your HandyCafe data directory. - The screenshot viewer opens with the new image.
If the client does not respond within the timeout (default 30 seconds to connect, 20 seconds for data), the request fails and an error toast appears. You can retry immediately.
Power Actions
| Action | Confirmation | Effect |
|---|---|---|
| Logoff | None | Logs off the Windows user on the client machine. The Windows session ends but the computer stays powered on. |
| Reboot | Yes | Sends a reboot command. The client machine restarts. |
| Shutdown | Yes | Sends a shutdown command. The client machine powers off. |
Reboot and Shutdown show a confirmation dialog to prevent accidental power actions.
Unsupported Operations
Legacy clients do not support every feature available on modern HandyCafe clients. Key gaps:
- No mid-session pause adjustments. Time changes submitted while the session is paused are queued but the client may ignore them. Resume the session first, apply the change, then pause again if needed.
- No Admin mode via server command. The client's internal admin status cannot be toggled from the server. Admin mode is controlled only on the client machine itself.
- No license registration from server. The server mirrors the license bytes it sees in client frames but cannot push a new license to the client. Register the client locally.
- No member wallet integration for sessions started on legacy clients. Payments are recorded as plain
transactionsrows withtransaction_type=sessionsand the client MAC. Modern wallet flows do not apply. - No remote desktop. The remote desktop feature uses a UDP streaming path not present in legacy clients.
- No file sync push. Sync Explorer pushes files over the modern protocol only.
For full functionality, migrate to modern HandyCafe clients when possible.
Offline Behavior
When the inactivity timeout expires, the card dims, the status badge turns gray, and every action button is disabled. The client record remains in the store so history, MAC, hostname, and last seen data are preserved. When the client comes back online (new UDP ping or TCP login), the card revives and actions become available again.
The record is not automatically removed. To remove an old client permanently, edit it from the admin database or delete it through the relevant admin tool.
Tips
- Keep the inactivity timeout at 10 seconds unless you know your legacy clients beacon slower than that. A shorter timeout incorrectly marks healthy clients as offline during brief network hiccups.
- If a legacy client appears online but does not respond to commands, confirm the Protocol Variant in Settings. A mismatch between the server variant (STE vs Standard) and the client build causes silent command drops.
- Screenshots from legacy clients are compressed BMPs, which are larger than modern PNG captures. Keep the
legacy_screenshotsfolder on a drive with adequate free space if you take many captures. - Use Add Time with preset buttons during shift transitions. A single tap extends a session by a predefined increment, which is faster than typing minutes manually.
- Retire legacy clients gradually. Migrate one batch at a time, confirm the new clients work identically in the Admin Panel, and only then decommission the old ones.