Download the PHP package olorunda/laravel-aiface-websocket without Composer

Laravel AiFace Biometric WebSocket Server & Device Command SDK

A high-performance, asynchronous pure-PHP RFC 6455 WebSocket / WSS Server and complete Command Interaction SDK for TimyTeco AiFace Biometric Terminals (Visible Light Facial Recognition, Fingerprint, Palm Vein, RFID Card, PIN, QR Code Access Control & Time Attendance).

⚡ Architecture Overview

In the TimyTeco AiFace BS communication protocol, the physical biometric device acts as a client that initiates an outbound persistent WebSocket connection to your Laravel server. This enables seamless Wide Area Network (WAN) and cloud deployment across network segments without requiring static public IPs or port forwarding on the device's local network.

🚀 Quickstart Installation

1. Register Package in your Laravel Application

In your Laravel project composer.json, add this package:

(If testing locally in the same monorepo/workspace, add as a path repository):

2. Publish Configuration & Run Database Migrations

Daemon Logging Configuration (.env)

Fine-tune or isolate daemon logs to prevent log pollution on high-traffic servers:

3. Start the WebSocket Server Daemon

Output:

To run on a custom port or with TLS/WSS:

📱 Hardware Device Configuration

On your physical AiFace device touchscreen:

1. Tap [Menu / Settings] ➔ Comm. (Communication) ➔ Server Settings / Cloud Settings.
2. Set Protocol Mode: WebSocket (or BS / Cloud Server).
3. Set Server IP / Domain: Your server IP address (e.g. 192.168.1.100 or cloud.yourdomain.com).
4. Set Server Port: 7788 (or 433 for WSS).
5. Set Server Path: /pub/chat (default path).
6. Save and restart network. The device will immediately connect and send the reg registration handshake.

💻 Laravel Facade Usage

Interact with any connected device using the AiFace facade:

🚀 Realistic Real-World Workflow Example

Below is a complete, production-grade example illustrating how to manage employee lifecycles (enrolling and offboarding users) via a Controller and automatically track attendance punches using Event Listeners.

1. Employee Biometric Controller (Enrolling & Deleting Users)

Create a controller (app/Http/Controllers/BiometricEmployeeController.php):

2. Real-Time Attendance Event Listener

Create an event listener (app/Listeners/HandleBiometricAttendance.php) to automatically process punches when employees clock in or clock out:

3. Registering the Listener in Laravel

In your app/Providers/AppServiceProvider.php (Laravel 11 & 12) or EventServiceProvider.php (Laravel 9 & 10):

🛠️ Complete Command Reference (All 80+ Commands)

Every command defined in the TimyTeco AiFace specification is implemented with typed methods:

1. User Management (17 Commands)

2. Log Management (4 Commands)

3. Device Management (15 Commands)

4. Access Control (9 Commands)

5. Attendance Management (6 Commands)

6. File Management (3 Commands)

7. Other System Commands (15 Commands)

8. Video Intercom Commands (11 Commands)

🌐 HTTP REST API & Webhooks

REST Endpoints

• GET /api/aiface/devices: List all online and registered hardware.
• GET /api/aiface/devices/{sn}: Detailed parameters of a specific device.
• POST /api/aiface/devices/{sn}/command: Send arbitrary JSON command to device.
• POST /api/aiface/devices/{sn}/opendoor: Quick remote door unlock.
• POST /api/aiface/devices/{sn}/reboot: Hardware reboot.
• POST /api/aiface/devices/{sn}/users: Create / update user on terminal.
• DELETE /api/aiface/devices/{sn}/users/{enrollid}: Delete user immediately or schedule delayed deletion (?delay=3600).
• GET /api/aiface/devices/{sn}/delayed-deletes: List all scheduled delayed deletions for device.
• DELETE /api/aiface/devices/{sn}/delayed-deletes/{enrollid}: Cancel a scheduled delayed deletion.
• GET /api/aiface/devices/{sn}/queued-commands: List all pending queued & scheduled commands for device.
• DELETE /api/aiface/devices/{sn}/queued-commands/{taskId}: Cancel a pending queued command by task ID.
• GET /api/aiface/devices/{sn}/new-logs: Fetch unread logs.
• GET /api/aiface/logs: View stored attendance punches.
• GET /api/aiface/commands/catalog: Complete command schema catalog.

🛡️ Automatic Offline Command Queueing & Auto-Flush on Reconnect

In real-world deployments, biometric devices may temporarily lose Wi-Fi or go offline during maintenance. Rather than displaying errors or timing out waiting for a device response:

The server automatically intercepts offline or unresponsive states and queues the command:

1. Persistent Backing: Commands are persisted in memory and in the aiface_scheduled_commands database table. If the server daemon restarts, pending commands are recovered automatically.
2. Auto-Flush Upon Reconnect: The instant the physical device connects and registers with the WebSocket daemon (cmd: reg), the daemon flushes and dispatches all pending queued commands in FIFO order!
3. Event & Webhook: Fires the CommandQueued event (command.queued webhook).

Import postman_collection.json into Postman for ready-to-use requests.

Webhook & Laravel Event Listeners

The package routes all hardware events through Laravel's standard Event Dispatcher and a dedicated event listener (DispatchAiFaceWebhook):

1. Listening to Clock-In & Biometric Events in Laravel

You can attach listeners or subscribers in your own application:

2. External Webhook Event Forwarding

Configure external HTTP webhook endpoints in config/aiface.php:

Incoming webhook requests include HMAC SHA-256 signatures for tamper verification:

🧪 Testing with Mock Device Simulator

Run the included pure-PHP mock terminal simulator to test end-to-end communication without physical hardware:

The mock device maintains its own local SQLite database (tynyteko_{SN}.sqlite) simulating real hardware storage:

• Persistent Biometric Storage: Real CRUD for users, credentials (passwords, RFID cards, facial feature templates, fingerprints).
• Dynamic Command Handling: Responds to setuserinfo, deleteuser, cleanuser, getusername, getuserlist, getuserids, getunuserdid, checkuserid, getuserinfo, getallusers, getdevcap, getdevinfo, settime, etc.
• Realistic Attendance Simulation: Generates facial scan punch logs (sendlog) for enrolled database users and processes server confirmations (mark: true).

Run the test suite:

📜 License

MIT License.