ZKTeco Java Bridge Service

REST API bridge service for ZKTeco fingerprint devices using Pull SDK. This service allows you to connect to ZKTeco devices (like MVL10) from any programming language via HTTP REST API.

Features

✅ Connect/Disconnect to ZKTeco devices via TCP/IP
✅ User Management (Add, Get, Delete)
✅ Fingerprint Management (Upload, Get, Delete templates)
✅ Real-time Access Log Monitoring
✅ Attendance Log Retrieval
✅ Device Information & Status
✅ Device Control (Unlock doors, trigger outputs)
✅ Network Device Discovery
✅ CORS enabled for web applications
✅ Comprehensive error handling
✅ Request validation

Technology Stack

Java 17
Spring Boot 3.2.0
JNA (Java Native Access) for DLL integration
Lombok for cleaner code
Maven for dependency management

Prerequisites

Java Development Kit (JDK) 17 or higher
- Download: https://adoptium.net/
Maven 3.6+
- Download: https://maven.apache.org/download.cgi
- Or use IntelliJ IDEA / Eclipse which includes Maven
ZKTeco Pull SDK DLLs (included in this project)
- Located in: /pull_sdk/SDK-Ver2.2.0.220/
- Required DLLs:
  - plcommpro.dll (main SDK)
  - pltcpcomm.dll (TCP communication)
  - plrscomm.dll (RS485 communication)
  - plusbcomm.dll (USB communication)
  - Other supporting DLLs
Windows Operating System (required for DLLs)
- Windows 10/11 recommended
- Windows Server 2016+ supported
ZKTeco Device (e.g., MVL10)
- Connected to same network
- IP address accessible
- Port 4370 open (default)

Installation

Step 1: Copy DLL Files

# Navigate to project directory
cd zkteco-java-bridge

# Create dll directory
mkdir dll

# Copy all DLLs from Pull SDK
cp ../pull_sdk/SDK-Ver2.2.0.220/*.dll ./dll/

Important: The application looks for DLLs in these locations (in order):

ZKTECO_DLL_PATH environment variable
./dll/ directory (relative to project)
Pull SDK path: ~/Desktop/zlink_java_code/pull_sdk/SDK-Ver2.2.0.220/

Step 2: Build the Project

# Using Maven
mvn clean package

# Or if using Maven wrapper
./mvnw clean package

This will create: target/zkteco-bridge-1.0.0.jar

Step 3: Run the Service

Option A: Using Maven

mvn spring-boot:run

Option B: Using JAR file

java -jar target/zkteco-bridge-1.0.0.jar

Option C: With custom DLL path

# Windows
set ZKTECO_DLL_PATH=C:\path\to\dlls
java -jar target/zkteco-bridge-1.0.0.jar

# Or inline
java -Djna.library.path=C:\path\to\dlls -jar target/zkteco-bridge-1.0.0.jar

Option D: Using IDE

Open project in IntelliJ IDEA or Eclipse
Right-click on Application.java
Select "Run Application"

Step 4: Verify Service is Running

# Health check
curl http://localhost:8080/api/device/health

# Expected response:
{
  "status": "UP",
  "service": "ZKTeco Bridge",
  "version": "1.0.0",
  "connected": false
}

Configuration

Application Settings

Edit src/main/resources/application.properties:

# Change port (default: 8080)
server.port=8080

# Logging level
logging.level.com.zkteco.bridge=DEBUG

Environment Variables

ZKTECO_DLL_PATH - Path to DLL files
SERVER_PORT - Override server port

API Documentation

Base URL: http://localhost:8080/api/device

1. Connect to Device

POST /connect

curl -X POST http://localhost:8080/api/device/connect \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.201",
    "port": 4370,
    "timeout": 4000
  }'

Response:

{
  "success": true,
  "message": "Connected to device at 192.168.1.201",
  "data": {
    "ip": "192.168.1.201",
    "port": 4370,
    "connected": true
  }
}

2. Disconnect from Device

POST /disconnect

curl -X POST http://localhost:8080/api/device/disconnect

3. Get Connection Status

GET /status

curl http://localhost:8080/api/device/status

Response:

{
  "success": true,
  "message": "Status retrieved",
  "data": {
    "connected": true,
    "deviceIp": "192.168.1.201"
  }
}

4. Add User

POST /user

curl -X POST http://localhost:8080/api/device/user \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1001",
    "cardNo": "12345",
    "name": "John Doe",
    "password": "",
    "group": 1
  }'

Response:

{
  "success": true,
  "message": "User added successfully",
  "data": {
    "pin": "1001",
    "cardNo": "12345",
    "recordsAffected": 1
  }
}

5. Get All Users

GET /users

curl http://localhost:8080/api/device/users

Response:

{
  "success": true,
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "CardNo": "12345",
        "Pin": "1001",
        "Password": "",
        "Group": "1"
      }
    ],
    "count": 1
  }
}

6. Delete User

DELETE /user/{pin}

curl -X DELETE http://localhost:8080/api/device/user/1001

7. Upload Fingerprint

POST /fingerprint

curl -X POST http://localhost:8080/api/device/fingerprint \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1001",
    "fingerID": 0,
    "template": "BASE64_ENCODED_TEMPLATE_DATA",
    "valid": 1
  }'

Response:

{
  "success": true,
  "message": "Fingerprint uploaded successfully",
  "data": {
    "pin": "1001",
    "fingerID": 0,
    "recordsAffected": 1
  }
}

8. Get Fingerprints for User

GET /fingerprint/{pin}

curl http://localhost:8080/api/device/fingerprint/1001

9. Delete Fingerprint

DELETE /fingerprint/{pin}?fingerID=0

curl -X DELETE "http://localhost:8080/api/device/fingerprint/1001?fingerID=0"

10. Get Real-Time Access Log

GET /rtlog

curl http://localhost:8080/api/device/rtlog

Response:

{
  "success": true,
  "message": "Log entry retrieved",
  "data": {
    "log": {
      "cardNo": "12345",
      "pin": "1001",
      "verified": "1",
      "doorID": "1",
      "eventType": "0",
      "inOutState": "0",
      "time": "1642156800"
    }
  }
}

11. Get Device Information

GET /info

curl http://localhost:8080/api/device/info

Response:

{
  "success": true,
  "message": "Device info retrieved",
  "data": {
    "DeviceID": "1",
    "DateTime": "2024-01-15 10:30:00",
    "LockCount": "4",
    "ReaderCount": "2"
  }
}

12. Get Attendance Logs

GET /logs?filter=Pin=1001

# All logs
curl http://localhost:8080/api/device/logs

# Filtered by user
curl "http://localhost:8080/api/device/logs?filter=Pin=1001"

13. Control Device (Unlock Door)

POST /control

# Unlock door 1 for 5 seconds
curl -X POST http://localhost:8080/api/device/control \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": 1,
    "param1": 1,
    "param2": 1,
    "param3": 5,
    "param4": 0
  }'

Operation IDs:

1 = Output control (unlock door, trigger relay)
4 = Door normal open/close control

14. Search for Devices on Network

GET /search

curl http://localhost:8080/api/device/search

Integration with Node.js

Install in Node.js Project

npm install axios

Create Service Wrapper

Create services/zktecoService.js:

const axios = require('axios');

const JAVA_BRIDGE_URL = process.env.JAVA_BRIDGE_URL || 'http://localhost:8080/api/device';

class ZKTecoService {
  async connect(ip, port = 4370, timeout = 4000) {
    const response = await axios.post(`${JAVA_BRIDGE_URL}/connect`, {
      ip, port, timeout
    });
    return response.data;
  }

  async disconnect() {
    const response = await axios.post(`${JAVA_BRIDGE_URL}/disconnect`);
    return response.data;
  }

  async addUser(pin, cardNo, name, password = '', group = 1) {
    const response = await axios.post(`${JAVA_BRIDGE_URL}/user`, {
      pin, cardNo, name, password, group
    });
    return response.data;
  }

  async getUsers() {
    const response = await axios.get(`${JAVA_BRIDGE_URL}/users`);
    return response.data;
  }

  async uploadFingerprint(pin, fingerID, template) {
    const response = await axios.post(`${JAVA_BRIDGE_URL}/fingerprint`, {
      pin, fingerID, template, valid: 1
    });
    return response.data;
  }

  async getRealTimeLog() {
    const response = await axios.get(`${JAVA_BRIDGE_URL}/rtlog`);
    return response.data;
  }
}

module.exports = new ZKTecoService();

Use in Express Routes

const express = require('express');
const zkService = require('./services/zktecoService');

const router = express.Router();

router.post('/connect', async (req, res) => {
  const { ip, port } = req.body;
  const result = await zkService.connect(ip, port);
  res.json(result);
});

router.post('/users', async (req, res) => {
  const { pin, cardNo, name } = req.body;
  const result = await zkService.addUser(pin, cardNo, name);
  res.json(result);
});

module.exports = router;

Troubleshooting

Issue: "Can't load library: plcommpro.dll"

Solution:

Verify DLLs are in ./dll/ directory
Check file permissions
Set ZKTECO_DLL_PATH environment variable
Ensure you're running on Windows

Issue: "Connection failed. Error code: -1"

Solution:

Check device IP address is correct
Verify device is on same network
Test connectivity: ping 192.168.1.201
Check port 4370 is not blocked by firewall
Verify device is powered on

Issue: "Failed to add user. Error code: XXX"

Solution:

Ensure device is connected first
Check user PIN doesn't already exist
Verify PIN format (usually numeric)
Check device memory is not full

Issue: Port 8080 already in use

Solution:

# Change port in application.properties
server.port=8081

# Or set environment variable
set SERVER_PORT=8081
java -jar target/zkteco-bridge-1.0.0.jar

Enable Debug Logging

Edit application.properties:

logging.level.com.zkteco.bridge=DEBUG
logging.level.com.sun.jna=DEBUG

Architecture

┌─────────────────────────────────────────────┐
│         Frontend / Node.js Backend          │
└─────────────────┬───────────────────────────┘
                  │ HTTP REST API
                  │
┌─────────────────▼───────────────────────────┐
│      ZKTeco Java Bridge (Spring Boot)       │
│  ┌──────────────────────────────────────┐   │
│  │         REST Controllers             │   │
│  └──────────┬───────────────────────────┘   │
│             │                                │
│  ┌──────────▼───────────────────────────┐   │
│  │       Service Layer (Business)       │   │
│  └──────────┬───────────────────────────┘   │
│             │                                │
│  ┌──────────▼───────────────────────────┐   │
│  │    JNA Interface (PullSDK.java)      │   │
│  └──────────┬───────────────────────────┘   │
└─────────────┼───────────────────────────────┘
              │ JNI/JNA
┌─────────────▼───────────────────────────────┐
│         Native DLLs (Pull SDK)              │
│  - plcommpro.dll (Main SDK)                 │
│  - pltcpcomm.dll (TCP)                      │
│  - plrscomm.dll (RS485)                     │
└─────────────┬───────────────────────────────┘
              │ TCP/IP
┌─────────────▼───────────────────────────────┐
│      ZKTeco Fingerprint Device (MVL10)      │
└─────────────────────────────────────────────┘

Project Structure

zkteco-java-bridge/
├── dll/                          # DLL files location
│   └── *.dll
├── src/
│   └── main/
│       ├── java/com/zkteco/bridge/
│       │   ├── Application.java          # Main application
│       │   ├── config/
│       │   │   └── GlobalExceptionHandler.java
│       │   ├── controller/
│       │   │   └── DeviceController.java # REST endpoints
│       │   ├── model/
│       │   │   ├── ApiResponse.java
│       │   │   ├── ConnectRequest.java
│       │   │   ├── UserRequest.java
│       │   │   └── FingerprintRequest.java
│       │   ├── sdk/
│       │   │   └── PullSDK.java          # JNA interface
│       │   └── service/
│       │       └── ZKTecoService.java    # Business logic
│       └── resources/
│           └── application.properties     # Configuration
├── pom.xml                       # Maven dependencies
└── README.md                     # This file

Error Codes

Common Pull SDK error codes:

-1 - Connection failed / Device not reachable
-2 - Invalid parameters
-3 - Command failed
-4 - Device busy
-5 - Timeout
-6 - Insufficient permissions
-10 - Data not found

License

This project uses the ZKTeco Pull SDK which is proprietary software. Please ensure you have appropriate licensing from ZKTeco for commercial use.

Support

For issues related to:

This bridge service: Create an issue in the project repository
ZKTeco Pull SDK: Contact ZKTeco support at support@zkteco.com
Device hardware: Contact your device vendor

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Version History

1.0.0 (2024-01-20)
- Initial release
- Full CRUD operations for users
- Fingerprint management
- Real-time log monitoring
- Device control functions

Acknowledgments

ZKTeco for providing the Pull SDK
Spring Boot team for the excellent framework
JNA project for native library access

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src/main		src/main
.gitignore		.gitignore
PROJECT-STRUCTURE.md		PROJECT-STRUCTURE.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
build.bat		build.bat
nodejs-integration-example.js		nodejs-integration-example.js
pom.xml		pom.xml
setup-dlls.bat		setup-dlls.bat
start.bat		start.bat

Folders and files

Latest commit

History

Repository files navigation

ZKTeco Java Bridge Service

Features

Technology Stack

Prerequisites

Installation

Step 1: Copy DLL Files

Step 2: Build the Project

Step 3: Run the Service

Step 4: Verify Service is Running

Configuration

Application Settings

Environment Variables

API Documentation

1. Connect to Device

2. Disconnect from Device

3. Get Connection Status

4. Add User

5. Get All Users

6. Delete User

7. Upload Fingerprint

8. Get Fingerprints for User

9. Delete Fingerprint

10. Get Real-Time Access Log

11. Get Device Information

12. Get Attendance Logs

13. Control Device (Unlock Door)

14. Search for Devices on Network

Integration with Node.js

Install in Node.js Project

Create Service Wrapper

Use in Express Routes

Troubleshooting

Issue: "Can't load library: plcommpro.dll"

Issue: "Connection failed. Error code: -1"

Issue: "Failed to add user. Error code: XXX"

Issue: Port 8080 already in use

Enable Debug Logging

Architecture

Project Structure

Error Codes

License

Support

Contributing

Version History

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages