Legacy Clients Settings
HandyCafe runs alongside older V3 and V4 client installations without disruption. The Legacy Clients settings page controls the Runtime Protocol: the network listeners that let V3 and V4 clients connect to this server on their original ports.
Importing data from an older installation is a separate job on its own settings page. See Data Migration. The two features are independent. Runtime support works without migrating any data. A migration works without runtime support. You can also use both together.
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
Importing data from a HandyCafe 3.x or 4.x installation no longer happens on this page. It lives on the Data Migration settings page under the HandyCafe Legacy source, next to the EveryCafe and Pancafe importers.
That page covers detection of the old installation, what gets imported, the read-only guarantee on the source files, re-running an import and undoing one. For a step-by-step walkthrough see How to Migrate from a Legacy Installation.
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.