Legacy Clients Settings
HandyCafe runs alongside older V3 and V4 client installations without disruption. The Legacy Clients settings page controls two distinct features:
- Runtime Protocol. Enables the network listeners that let V3 and V4 clients connect to this server on their original ports.
- Database Migration. Optionally imports members, pricing, products, orders, transactions, and logs from an older local installation into the new HandyCafe database. This is Windows only.
The two features are independent. You can enable runtime support without migrating data, migrate data without enabling runtime support, or do both.
Runtime Protocol Section
Enable Legacy Client Support
A master toggle at the top of the section. When on, the server starts three network listeners:
- A UDP listener on the configured multicast group.
- A TCP command listener on
UDP port + 2. - A TCP file transfer listener on
UDP port + 7.
Turning the toggle off stops all three listeners atomically. You can adjust port numbers or encoding while disabled, then re-enable to apply the changes.
Configuration Fields
| Field | Default | Description |
|---|---|---|
| Auth Key | HANDYCAFE | A shared 10-character key. Every inbound and outbound frame carries this string. Frames that do not match are dropped. All your legacy clients must use the same key. |
| UDP Multicast IP | 230.4.4.46 | The multicast group used for client discovery beacons and for UDP-based command dispatch. Hard-coded in most legacy client builds. |
| Server UDP Port | 710 | The UDP port the server listens on for client beacons and commands. Legacy clients send to this port. |
| Client UDP Port | 711 | The UDP port legacy clients listen on. The server sends unicast management commands to this port on the discovered client IP. |
| Encoding | cp1254 | Character encoding for wire-format string fields. Use cp1254 for Turkish installations, cp1252 for Western European. Unknown values fall back to cp1254 with a warning in the server log. |
| Server Version | 3.4.01 | The version string broadcast in every UDP beacon. Some legacy clients reject frames from versions they do not recognize. Set this to match the version string of your original server. |
| Protocol Variant | STE | Wire format selection. See the variant comparison below. |
| Inactivity Timeout | 10 | Seconds. A per-MAC watchdog. If no traffic arrives from a client within this window, the client is marked offline. A gap of 10 seconds is appropriate for legacy clients that beacon every 2 or 3 seconds. |
Derived Ports
Below the form, the page displays a read-only line that shows the derived TCP ports:
TCP Command Port: 712 File Transfer Port: 717
These ports are computed from the UDP server port. You do not configure them separately. If you change Server UDP Port to a different value, the derived ports move with it.
Protocol Variant
The Protocol Variant field selects the wire format used by the server. Pick the variant that matches how your legacy server was built.
| Variant | When to Use |
|---|---|
| STE (Smart/Turbo Edition) | The modern legacy codebase. Adds a 70-byte license-info prefix to the frame structure. Frame size is 1337 bytes. Choose this if your legacy installation used the Smart or Turbo edition. |
| Standard | The plain baseline legacy build. Frame size is 1267 bytes without the license-info prefix. Choose this only if your legacy installation was a Standard edition without license registration. |
Picking the wrong variant causes frames to be dropped or misread. Symptoms include clients appearing online but ignoring every command, or command data shifted by the 70-byte offset.
Coexistence with Modern Clients
The legacy ports (710, 711, 712, 717) are completely separate from the modern HandyCafe protocol ports (TCP 5001, 5002, 5003, UDP 5004). Both protocol stacks run simultaneously without conflict. You can mix old and new clients on the same LAN and manage them from the same Admin Panel.
Applying Changes
Every field in the Runtime Protocol section is saved with the global Save button at the bottom of the page. On save, the server:
- Stops the three legacy listeners if they were running.
- Validates the auth key (must not be empty).
- Builds new listener configurations from the updated fields.
- Restarts the listeners concurrently.
- Fires a notification when all three are back online.
If a port is already in use by another process, the server reports an error and the toggle flips back off. Check your firewall and other services with netstat and pick a free port range.
Database Migration Section (Windows Only)
This feature is available only when HandyCafe runs on Windows. On macOS and Linux, the section shows a notice: "Database migration is supported on Windows only."
Detection
On open, the server scans your system for a legacy installation. Detection looks in:
- Registry and typical install paths such as
Program Files\HandyCafeandC:\HandyCafe. - The database file alongside the installation.
- Configuration INI files in the installation directory.
When detection succeeds, the page displays:
| Label | Meaning |
|---|---|
| Install Path | Where the legacy installation lives on disk. |
| Database Path | Full path to the legacy database file. |
| Server Version | Parsed from the legacy configuration. |
| INI File Count | Number of configuration files detected. Useful for sanity checking that the installation is complete. |
If no installation is detected, the page displays "No legacy installation detected." You can still enable runtime support; the migration feature simply has nothing to import.
Migration Status
The page tracks the migration history:
| Status | Meaning |
|---|---|
| never | You have not run a migration yet. |
| in_progress | A migration is currently running. Do not close the server during this state. |
| completed | The most recent migration finished with no warnings. |
| completed_with_warnings | The most recent migration finished but some records were skipped (for example due to encoding errors or malformed dates). Review the warnings before proceeding. |
| undone | The most recent migration was rolled back. |
After the first successful run, the Start Migration button relabels to Re-run Migration.
What Gets Migrated
| Table | Description |
|---|---|
| Members | Customer records with names, contact info, and account balances. |
| Pricing | Price tables and hour-by-hour rates. |
| Products | Product catalog entries. |
| Orders | Order history with session references. |
| Transactions | Ledger entries with timestamps, amounts, and payment methods. |
| Logs | Audit and warning entries from the legacy database. |
The "Files Safe" Guarantee
The page displays a notice in blue: "The original database files are not deleted. You can safely delete them once migration is confirmed." Migration is read-only on the source. Even if you run the migration multiple times, the original legacy database stays untouched. This lets you experiment with the import, review counts, and roll back without risk.
Start, Re-run, and Undo
- Start Migration. Opens a progress modal. The modal shows the current phase and record counts as the import runs. Do not close HandyCafe during this time.
- Re-run Migration. Available after a completed run. Re-runs the import from scratch. The new import replaces the previous data in HandyCafe.
- Undo Migration. Available after a completed run. Opens a confirmation dialog. On confirm, every migrated row is deleted from HandyCafe. The legacy source is not touched. After undo, the status reverts to
never.
Completed with Warnings
If the migration finishes with completed_with_warnings, a yellow banner appears with a Details link. Click to expand a list of the skipped records with the reason. Common reasons:
- Encoding mismatch. The source row contains characters that do not decode cleanly in the configured encoding. Change the encoding field (cp1254 or cp1252) and re-run migration.
- Malformed dates. Some legacy records have invalid time stamps. These are skipped so that valid rows still import.
- Duplicate keys. A record with the same identifier already exists in HandyCafe. The migration preserves the existing record and skips the duplicate.
Tips
- Stop the legacy server before running a migration. If the legacy system is still writing to its database, the import may see stale or partial data.
- Match the Encoding field to your legacy locale before the first migration. Changing it after data has been imported will not retroactively fix already-corrupted names.
- Always run a test migration first. Check record counts under "Last Counts" and spot-check a few member and transaction rows before committing staff to the new system.
- Enable runtime support and keep your legacy clients connected for a transition period. This lets you verify that the new server serves them identically before you retire the old server.
- If you change the Server UDP Port, remember that the derived command and file transfer ports move with it. Firewall rules need updating accordingly.