README

A Filament plugin to receive attendance data from ZKTeco devices via ADMS (Automatic Data Master Server) protocol. This package provides ADMS endpoints, database storage, and a complete Filament admin interface for managing devices and attendance logs.

Version Compatibility

Features

• ADMS protocol endpoints (/iclock/cdata, /iclock/getrequest, /iclock/devicecmd)
• Automatic device registration
• Attendance log storage with user sync
• Device command queue (reboot, clear logs, sync users)
• Full Filament admin panel integration
• Configurable table prefixes and route settings
• Event dispatching for real-time integrations

Installation

For Filament 4.x:

composer require syofyanzuhad/filament-zkteco-adms:^2.0

For Filament 3.x:

composer require syofyanzuhad/filament-zkteco-adms:^1.0

Publish and run the migrations:

php artisan vendor:publish --tag="filament-zkteco-adms-migrations"
php artisan migrate

Optionally, publish the config file:

php artisan vendor:publish --tag="filament-zkteco-adms-config"

Usage

1. Register the Plugin

Add the plugin to your Filament panel provider:

// app/Providers/Filament/AdminPanelProvider.php

use Syofyanzuhad\FilamentZktecoAdms\FilamentZktecoAdmsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(FilamentZktecoAdmsPlugin::make());
}

You can selectively disable resources:

->plugin(
    FilamentZktecoAdmsPlugin::make()
        ->deviceResource()
        ->attendanceLogResource()
        ->userResource(false)      // Disable user resource
        ->commandResource(false)   // Disable command resource
)

2. Configure Your ZKTeco Device

On your ZKTeco device, configure the ADMS settings:

1. Go to COMM > Cloud Server Setting (or ADMS)
2. Set Server Address: your-domain.com or IP address
3. Set Server Port: 80 (or your app's port)
4. Enable Domain Name if using a domain
5. The device will connect to /iclock/cdata

3. Available Endpoints

4. Filament Admin Panel

The plugin adds four resources to your Filament panel:

• Devices - View and manage connected ZKTeco devices
• Attendance Logs - View attendance records with filters
• ZKTeco Users - View synced users from devices
• Device Commands - View and manage command queue

5. Sending Commands to Devices

You can send commands to devices programmatically:

use Syofyanzuhad\FilamentZktecoAdms\Models\Device;
use Syofyanzuhad\FilamentZktecoAdms\Services\DeviceCommandBuilder;

$device = Device::where('serial_number', 'ABC123')->first();
$commandBuilder = app(DeviceCommandBuilder::class);

// Reboot device
$commandBuilder->reboot($device);

// Clear attendance logs on device
$commandBuilder->clearAttendanceLogs($device);

// Get device info
$commandBuilder->info($device);

// Add user to device
$commandBuilder->addUser($device, [
    'pin' => '1',
    'name' => 'John Doe',
    'card' => '12345678',
    'privilege' => 0,  // 0 = user, 14 = admin
]);

// Delete user from device
$commandBuilder->deleteUser($device, '1');

// Sync time
$commandBuilder->syncTime($device);

6. Listening to Events

The package dispatches events that you can listen to:

// app/Providers/EventServiceProvider.php

protected $listen = [
    \Syofyanzuhad\FilamentZktecoAdms\Events\AttendanceReceived::class => [
        \App\Listeners\ProcessAttendance::class,
    ],
    \Syofyanzuhad\FilamentZktecoAdms\Events\DeviceConnected::class => [
        \App\Listeners\OnDeviceConnected::class,
    ],
    \Syofyanzuhad\FilamentZktecoAdms\Events\UserSynced::class => [
        \App\Listeners\OnUserSynced::class,
    ],
];

Example listener:

// app/Listeners/ProcessAttendance.php

namespace App\Listeners;

use Syofyanzuhad\FilamentZktecoAdms\Events\AttendanceReceived;

class ProcessAttendance
{
    public function handle(AttendanceReceived $event): void
    {
        $log = $event->attendanceLog;
        $device = $event->device;

        // Process attendance...
        // e.g., sync to HR system, send notification, etc.
    }
}

Configuration

// config/zkteco-adms.php

return [
    // Database table prefix
    'table_prefix' => env('ZKTECO_TABLE_PREFIX', 'zkteco_'),

    // Route configuration
    'routes' => [
        'prefix' => env('ZKTECO_ROUTE_PREFIX', 'iclock'),
        'middleware' => ['api'],
        'domain' => env('ZKTECO_ROUTE_DOMAIN', null),
    ],

    // Device settings
    'device' => [
        'auto_register' => env('ZKTECO_AUTO_REGISTER_DEVICES', true),
        'offline_threshold_minutes' => env('ZKTECO_OFFLINE_THRESHOLD', 10),
    ],

    // Event dispatching
    'events' => [
        'dispatch_attendance_received' => true,
        'dispatch_device_connected' => true,
        'dispatch_user_synced' => true,
    ],

    // Filament navigation
    'filament' => [
        'navigation_group' => 'ZKTeco ADMS',
        'navigation_icon' => 'heroicon-o-finger-print',
        'navigation_sort' => 50,
    ],
];

Customizing Models

You can extend the default models by updating the config:

// config/zkteco-adms.php

'models' => [
    'device' => \App\Models\CustomDevice::class,
    'attendance_log' => \App\Models\CustomAttendanceLog::class,
    'user' => \App\Models\CustomZktecoUser::class,
    'device_command' => \App\Models\CustomDeviceCommand::class,
],

Testing

composer test

Screenshots

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Syofyan Zuhad
• All Contributors

License

The MIT License (MIT). Please see License File for more information.