pyzkaccess-native 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyzkaccess_native-0.1.0/.gitignore +13 -0
- pyzkaccess_native-0.1.0/CHANGELOG.md +15 -0
- pyzkaccess_native-0.1.0/LICENSE +21 -0
- pyzkaccess_native-0.1.0/PKG-INFO +505 -0
- pyzkaccess_native-0.1.0/README.md +480 -0
- pyzkaccess_native-0.1.0/docs/PROTOCOL.md +308 -0
- pyzkaccess_native-0.1.0/pyproject.toml +50 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/__init__.py +22 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/__main__.py +3 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/backup.py +107 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/cli.py +244 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/client.py +499 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/codec.py +232 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/discovery.py +53 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/emulator.py +275 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/errors.py +26 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/events.py +216 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/models.py +109 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/protocol.py +123 -0
- pyzkaccess_native-0.1.0/src/pyzkaccess_native/py.typed +0 -0
- pyzkaccess_native-0.1.0/tests/test_client.py +117 -0
- pyzkaccess_native-0.1.0/tests/test_codec.py +111 -0
- pyzkaccess_native-0.1.0/tests/test_events.py +24 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 - 2026-11
|
|
4
|
+
|
|
5
|
+
First public release.
|
|
6
|
+
|
|
7
|
+
- Pure-Python PullSDK / ZKAccess client: session, parameters, clock, tables
|
|
8
|
+
(read with buffered transfers, write, delete, count), real-time log, control commands.
|
|
9
|
+
- Typed helpers for users, fingerprint templates and door authorizations, with safety
|
|
10
|
+
checks (record merge, UID collision, no accidental table wipe, cascade delete).
|
|
11
|
+
- JSON backup / restore, byte-exact for fingerprint templates.
|
|
12
|
+
- `zkaccess` command line tool.
|
|
13
|
+
- Device emulator for tests.
|
|
14
|
+
- Home Assistant integration (HACS): access event entity, bus events, door sensors,
|
|
15
|
+
counters, open-door buttons, user management services.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Avataar120
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,505 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pyzkaccess-native
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Pure-Python, cross-platform client for ZKTeco PullSDK / ZKAccess access-control devices (C3, inBio, MA500...) - no DLL required
|
|
5
|
+
Project-URL: Homepage, https://github.com/Avataar120/pyzkaccess
|
|
6
|
+
Project-URL: Documentation, https://github.com/Avataar120/pyzkaccess#readme
|
|
7
|
+
Project-URL: Issues, https://github.com/Avataar120/pyzkaccess/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/Avataar120/pyzkaccess/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Avataar120
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: access-control,c3,fingerprint,home-assistant,inbio,ma500,pullsdk,zkaccess,zkteco
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: Home Automation
|
|
18
|
+
Classifier: Topic :: Security
|
|
19
|
+
Classifier: Topic :: System :: Hardware
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Provides-Extra: test
|
|
23
|
+
Requires-Dist: pytest>=7; extra == 'test'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# pyzkaccess-native
|
|
27
|
+
|
|
28
|
+
**Talk to ZKTeco access-control devices from any OS, in pure Python. No DLL, no Windows,
|
|
29
|
+
no ZKAccess.**
|
|
30
|
+
|
|
31
|
+
[](https://pypi.org/project/pyzkaccess-native/)
|
|
32
|
+
[](https://pypi.org/project/pyzkaccess-native/)
|
|
33
|
+
[](https://github.com/Avataar120/pyzkaccess/actions/workflows/ci.yml)
|
|
34
|
+
[](https://hacs.xyz/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
ZKTeco panels and readers that are managed by **ZKAccess** (C3-100/200/400, inBio,
|
|
38
|
+
MA500...) speak a binary TCP protocol. The only official way to use it is the PullSDK
|
|
39
|
+
(`plcommpro.dll`), a 32-bit Windows DLL. This project reimplements that protocol from
|
|
40
|
+
scratch, from captures of the DLL's own traffic, so you can:
|
|
41
|
+
|
|
42
|
+
- read and manage **users, RFID cards, PIN codes and fingerprint templates**;
|
|
43
|
+
- grant and revoke **door access**;
|
|
44
|
+
- receive **access events in real time** (who opened which door, refused attempts...);
|
|
45
|
+
- **open doors**, drive auxiliary outputs, set the clock, read and write parameters;
|
|
46
|
+
- **back up and restore** a whole device, fingerprint templates included, byte for byte;
|
|
47
|
+
|
|
48
|
+
from Linux, macOS, Windows, a Raspberry Pi or a container, with no dependency at all.
|
|
49
|
+
|
|
50
|
+
It comes with:
|
|
51
|
+
|
|
52
|
+
| | |
|
|
53
|
+
|---|---|
|
|
54
|
+
| 🐍 **Python library** | `pip install pyzkaccess-native` |
|
|
55
|
+
| 💻 **Command line tool** | `zkaccess --host 192.168.1.201 users` |
|
|
56
|
+
| 🏠 **Home Assistant integration** | installable from HACS, see [below](#home-assistant-integration) |
|
|
57
|
+
| 🧪 **Device emulator** | test your code without hardware |
|
|
58
|
+
| 📖 **Protocol documentation** | [docs/PROTOCOL.md](docs/PROTOCOL.md) |
|
|
59
|
+
|
|
60
|
+
> [!NOTE]
|
|
61
|
+
> Not to be confused with [`pyzkaccess`](https://github.com/bdragon300/pyzkaccess), a
|
|
62
|
+
> different project that wraps the official Windows DLL. This one does not need the DLL.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Contents
|
|
67
|
+
|
|
68
|
+
- [Supported devices](#supported-devices)
|
|
69
|
+
- [Installation](#installation)
|
|
70
|
+
- [Quick start](#quick-start)
|
|
71
|
+
- [Library guide](#library-guide)
|
|
72
|
+
- [Command line tool](#command-line-tool)
|
|
73
|
+
- [Home Assistant integration](#home-assistant-integration)
|
|
74
|
+
- [Safety notes (read this)](#safety-notes-read-this)
|
|
75
|
+
- [Testing without hardware](#testing-without-hardware)
|
|
76
|
+
- [Troubleshooting](#troubleshooting)
|
|
77
|
+
- [Contributing](#contributing)
|
|
78
|
+
|
|
79
|
+
## Supported devices
|
|
80
|
+
|
|
81
|
+
Any device that ZKAccess / the PullSDK can manage *should* work, since they share the
|
|
82
|
+
protocol.
|
|
83
|
+
|
|
84
|
+
| Device | Status |
|
|
85
|
+
|---|---|
|
|
86
|
+
| **MA500** (fingerprint + RFID reader), firmware 6.64 | ✅ tested (reboot and normal-open state excepted) |
|
|
87
|
+
| C3-100 / C3-200 / C3-400 | 🟡 expected to work (same protocol); please report |
|
|
88
|
+
| inBio 160/260/460 | 🟡 expected to work; please report |
|
|
89
|
+
| Push-protocol / "standalone attendance" devices (`pyzk`, port 4370 UDP) | ❌ different protocol |
|
|
90
|
+
|
|
91
|
+
If you try another model, please open an issue with the output of `zkaccess info` and
|
|
92
|
+
`zkaccess tables`: it helps a lot.
|
|
93
|
+
|
|
94
|
+
## Installation
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
pip install pyzkaccess-native
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Python 3.10 or newer, no other dependency.
|
|
101
|
+
|
|
102
|
+
## Quick start
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from pyzkaccess_native import ZKAccess
|
|
106
|
+
|
|
107
|
+
with ZKAccess("192.168.1.201") as dev: # password="..." if one is set
|
|
108
|
+
info = dev.info()
|
|
109
|
+
print(info.serial_number, info.firmware)
|
|
110
|
+
|
|
111
|
+
for user in dev.get_users():
|
|
112
|
+
print(user.pin, user.name, user.card_no)
|
|
113
|
+
|
|
114
|
+
for event in dev.events(): # Ctrl+C to stop
|
|
115
|
+
print(event.time, event.pin, event.label, "granted" if event.granted else "")
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
From a shell:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
zkaccess --host 192.168.1.201 info
|
|
122
|
+
zkaccess --host 192.168.1.201 events
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Library guide
|
|
126
|
+
|
|
127
|
+
### Connecting
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
from pyzkaccess_native import ZKAccess
|
|
131
|
+
|
|
132
|
+
dev = ZKAccess("192.168.1.201", port=4370, password="", timeout=5.0)
|
|
133
|
+
dev.connect()
|
|
134
|
+
...
|
|
135
|
+
dev.disconnect()
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Or, better, `with ZKAccess(...) as dev:`. The client is thread-safe: requests from
|
|
139
|
+
several threads are serialized on its session.
|
|
140
|
+
|
|
141
|
+
> [!IMPORTANT]
|
|
142
|
+
> Share one `ZKAccess` instance inside your program. A device may accept a second
|
|
143
|
+
> session (the MA500 does), but **real-time events are delivered to every session**, and
|
|
144
|
+
> writes from two programs are not coordinated. Do not manage the same device from
|
|
145
|
+
> ZKAccess and from this library at the same time.
|
|
146
|
+
|
|
147
|
+
### Device information, parameters and clock
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
info = dev.info() # DeviceInfo(serial_number, firmware, lock_count, ...)
|
|
151
|
+
dev.get_params(["~SerialNumber", "Door1Drivertime", "MThreshold"])
|
|
152
|
+
dev.set_params({"Door1Drivertime": 5})
|
|
153
|
+
|
|
154
|
+
dev.get_time() # naive datetime, device local time
|
|
155
|
+
dev.set_time() # sync with this computer (or pass a datetime)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Users
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
from pyzkaccess_native import User
|
|
162
|
+
|
|
163
|
+
dev.get_users() # list[User]
|
|
164
|
+
dev.get_user(105) # User | None
|
|
165
|
+
|
|
166
|
+
# Create, or update only the given fields (the others are kept):
|
|
167
|
+
dev.save_user(User(pin=105, name="Alice", card_no=12345678, password="1234"))
|
|
168
|
+
dev.save_user(User(pin=105, name="Alice Smith")) # rename, card and password kept
|
|
169
|
+
|
|
170
|
+
dev.delete_user(105) # also deletes its fingerprint templates and authorizations
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`User` fields: `pin`, `name`, `card_no`, `password`, `group`, `start_time`, `end_time`,
|
|
174
|
+
`privilege`, `super_authorize`, and `uid` (read-only, assigned by the device).
|
|
175
|
+
|
|
176
|
+
### Door access
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
dev.grant(105) # time zone 1 ("always"), door 1
|
|
180
|
+
dev.grant(105, timezone_id=2, door_mask=0b0101) # doors 1 and 3 during time zone 2
|
|
181
|
+
dev.get_authorizations(105) # list[Authorization]
|
|
182
|
+
dev.revoke(105) # remove all of them
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
A user can open a door only if they have an authorization for it **and** a credential
|
|
186
|
+
(fingerprint, card or password).
|
|
187
|
+
|
|
188
|
+
### Fingerprint templates
|
|
189
|
+
|
|
190
|
+
Fingerprints are enrolled **on the device** (keypad menu or ZKAccess with a USB reader).
|
|
191
|
+
The library can copy, back up and restore the resulting templates:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from pyzkaccess_native import Template
|
|
195
|
+
|
|
196
|
+
templates = dev.get_templates() # all of them (large transfer handled for you)
|
|
197
|
+
mine = dev.get_templates(pin=105)
|
|
198
|
+
|
|
199
|
+
# Copy a template to another device (the user must exist there):
|
|
200
|
+
other.save_user(User(pin=105, name="Alice"))
|
|
201
|
+
other.save_template(Template(pin=105, finger_id=0, template=mine[0].template))
|
|
202
|
+
|
|
203
|
+
dev.delete_templates(105) # or delete_templates(105, finger_id=3)
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
`save_template()` refuses to write when another user has the same internal UID (see
|
|
207
|
+
[safety notes](#safety-notes-read-this)).
|
|
208
|
+
|
|
209
|
+
### Real-time events
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from pyzkaccess_native import AccessEvent, EventType
|
|
213
|
+
|
|
214
|
+
for ev in dev.events(interval=0.5): # reconnects automatically
|
|
215
|
+
if ev.granted:
|
|
216
|
+
print(f"{ev.pin} opened door {ev.door} ({ev.label})")
|
|
217
|
+
elif ev.event == EventType.UNREGISTERED_FINGERPRINT:
|
|
218
|
+
print("unknown finger")
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Or poll yourself: `dev.poll()` returns the records received since the previous call:
|
|
222
|
+
`AccessEvent` objects, plus a `DoorStatus` (door sensors, alarms) on every call.
|
|
223
|
+
|
|
224
|
+
`AccessEvent` has `event` (an `EventType`, or a plain `int` for unlisted codes), `pin`,
|
|
225
|
+
`card`, `door`, `verify_mode`, `in_out`, `time`, plus the helpers `granted`, `denied` and
|
|
226
|
+
`label`.
|
|
227
|
+
|
|
228
|
+
### Doors and outputs
|
|
229
|
+
|
|
230
|
+
```python
|
|
231
|
+
dev.open_door(1, seconds=5) # pulse the lock relay of door 1
|
|
232
|
+
dev.hold_door_open(1) # until close_door()
|
|
233
|
+
dev.close_door(1)
|
|
234
|
+
dev.set_aux_output(1, 3) # aux output 1 for 3 s (0 = off, 255 = on)
|
|
235
|
+
dev.cancel_alarm()
|
|
236
|
+
dev.restart()
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Generic table access
|
|
240
|
+
|
|
241
|
+
Everything above is built on four generic calls. They work on any table the device
|
|
242
|
+
reports (`dev.tables()`), with the device's own field names:
|
|
243
|
+
|
|
244
|
+
```python
|
|
245
|
+
dev.read_table("transaction", where={"Pin": 105}) # list[dict]
|
|
246
|
+
dev.read_table("user", fields=["Pin", "Name"])
|
|
247
|
+
dev.write_records("timezone", [{"TimezoneId": 2, "MonTime1": ...}])
|
|
248
|
+
dev.delete_records("holiday", where={"Holiday": 20261225})
|
|
249
|
+
dev.count("user")
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Backup and restore
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
from pyzkaccess_native import backup
|
|
256
|
+
|
|
257
|
+
snap = backup.backup(dev) # users, templates, authorizations, time zones...
|
|
258
|
+
backup.save(snap, "device.json")
|
|
259
|
+
|
|
260
|
+
backup.restore(dev, backup.load("device.json")) # merge
|
|
261
|
+
backup.restore(dev, backup.load("device.json"), wipe=True) # exact copy
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
> [!WARNING]
|
|
265
|
+
> Backups contain **biometric data** (fingerprint templates) and user passwords.
|
|
266
|
+
> Store them like any other secret.
|
|
267
|
+
|
|
268
|
+
### Discovery
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
from pyzkaccess_native import discover
|
|
272
|
+
discover() # UDP broadcast; only finds devices on the same subnet
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### Errors
|
|
276
|
+
|
|
277
|
+
All exceptions derive from `ZKError`: `ZKConnectionError` (network),
|
|
278
|
+
`DeviceError` (the device refused, `.code` = -14 for a wrong password...),
|
|
279
|
+
`ProtocolError` (unexpected answer), `SafetyError` (refused by a safety check).
|
|
280
|
+
|
|
281
|
+
## Command line tool
|
|
282
|
+
|
|
283
|
+
```text
|
|
284
|
+
zkaccess [--host HOST] [--port 4370] [--password PWD] [-v|-vv] <command>
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
`--host` and `--password` can also come from `ZKACCESS_HOST` / `ZKACCESS_PASSWORD`.
|
|
288
|
+
|
|
289
|
+
| Command | Description |
|
|
290
|
+
|---|---|
|
|
291
|
+
| `discover` | find devices on the local network |
|
|
292
|
+
| `info` | serial number, firmware, doors, readers... |
|
|
293
|
+
| `tables` | tables and fields supported by the device |
|
|
294
|
+
| `params NAME... / NAME=VALUE...` | read / write parameters |
|
|
295
|
+
| `time [--set [ISO date]]` | read, or set the clock (default: now) |
|
|
296
|
+
| `users [--json]` | list users |
|
|
297
|
+
| `user-set PIN [--name] [--card] [--user-password]` | create or update a user |
|
|
298
|
+
| `user-delete PIN [--yes]` | delete a user, its templates and authorizations |
|
|
299
|
+
| `grant PIN [--timezone 1] [--doors 1]` / `revoke PIN` | door access |
|
|
300
|
+
| `read TABLE [--where F=V] [--fields a,b] [--json]` | dump any table |
|
|
301
|
+
| `count TABLE` | number of records |
|
|
302
|
+
| `events [--status] [--json]` | live events, Ctrl+C to stop |
|
|
303
|
+
| `door open\|close\|hold [--door 1] [--seconds 5]` | drive a lock relay |
|
|
304
|
+
| `aux OUTPUT SECONDS` | drive an auxiliary output |
|
|
305
|
+
| `backup FILE [--logs]` / `restore FILE [--wipe] [--yes]` | full backup / restore |
|
|
306
|
+
| `cancel-alarm`, `restart` | |
|
|
307
|
+
|
|
308
|
+
`-vv` prints every frame in hex, handy for protocol work. `python -m pyzkaccess_native`
|
|
309
|
+
works too.
|
|
310
|
+
|
|
311
|
+
Example:
|
|
312
|
+
|
|
313
|
+
```console
|
|
314
|
+
$ export ZKACCESS_HOST=192.168.1.201
|
|
315
|
+
$ zkaccess users
|
|
316
|
+
Pin Name CardNo Password Group StartTime EndTime Privilege SuperAuthorize UID
|
|
317
|
+
101 Alice 12345678 0 0 0 0 0 1
|
|
318
|
+
$ zkaccess events
|
|
319
|
+
2026-11-21 08:02:11 door 1 pin 101 card 0 14 Fingerprint open
|
|
320
|
+
2026-11-21 08:05:40 door 1 pin 0 card 0 34 Unregistered fingerprint
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
## Home Assistant integration
|
|
324
|
+
|
|
325
|
+
The repository is also a **HACS** custom integration built on the library.
|
|
326
|
+
|
|
327
|
+
### Install
|
|
328
|
+
|
|
329
|
+
1. HACS → ⋮ → **Custom repositories** → add `https://github.com/Avataar120/pyzkaccess`,
|
|
330
|
+
type **Integration**.
|
|
331
|
+
2. Install **ZKAccess Native** and restart Home Assistant.
|
|
332
|
+
3. **Settings → Devices & services → Add integration → ZKAccess Native**, enter the IP
|
|
333
|
+
address (and the communication password, if any).
|
|
334
|
+
|
|
335
|
+
### What you get
|
|
336
|
+
|
|
337
|
+
| Entity | Description |
|
|
338
|
+
|---|---|
|
|
339
|
+
| `event.<device>_access` | fires `granted`, `denied` or `other` with `pin`, `card`, `door`, `event`, `event_name`, `verify_mode`, `time` |
|
|
340
|
+
| `binary_sensor.<device>_door_N` | door contact (unknown when no sensor is wired) |
|
|
341
|
+
| `binary_sensor.<device>_door_N_alarm` | alarm / door open too long |
|
|
342
|
+
| `sensor.<device>_last_user` | PIN of the last granted user |
|
|
343
|
+
| `sensor.<device>_users`, `_fingerprint_templates` | counters |
|
|
344
|
+
| `button.<device>_open_door_N` | pulse the lock relay |
|
|
345
|
+
| `button.<device>_sync_clock` | set the device clock |
|
|
346
|
+
|
|
347
|
+
Every access event is also fired on the bus as **`zkaccess_native_access`** with the same
|
|
348
|
+
data plus `device_id`.
|
|
349
|
+
|
|
350
|
+
Services: `zkaccess_native.set_user`, `delete_user`, `grant`, `revoke`, `open_door`,
|
|
351
|
+
`sync_clock`, `list_users` (returns the users) and `backup` (writes a JSON file in
|
|
352
|
+
`/config/zkaccess_native/`).
|
|
353
|
+
|
|
354
|
+
Options: polling interval (default 1 s), door open duration, clock sync on connection.
|
|
355
|
+
|
|
356
|
+
### Example automations
|
|
357
|
+
|
|
358
|
+
Turn on the hall light when a known user opens the door at night:
|
|
359
|
+
|
|
360
|
+
```yaml
|
|
361
|
+
automation:
|
|
362
|
+
- alias: "Front door - welcome light"
|
|
363
|
+
triggers:
|
|
364
|
+
- trigger: state
|
|
365
|
+
entity_id: event.front_door_access
|
|
366
|
+
to: ~
|
|
367
|
+
conditions:
|
|
368
|
+
- condition: template
|
|
369
|
+
value_template: "{{ trigger.to_state.attributes.event_type == 'granted' }}"
|
|
370
|
+
- condition: sun
|
|
371
|
+
after: sunset
|
|
372
|
+
actions:
|
|
373
|
+
- action: light.turn_on
|
|
374
|
+
target:
|
|
375
|
+
entity_id: light.hall
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Different action per user, with the bus event:
|
|
379
|
+
|
|
380
|
+
```yaml
|
|
381
|
+
automation:
|
|
382
|
+
- alias: "Front door - per user"
|
|
383
|
+
triggers:
|
|
384
|
+
- trigger: event
|
|
385
|
+
event_type: zkaccess_native_access
|
|
386
|
+
event_data:
|
|
387
|
+
granted: true
|
|
388
|
+
actions:
|
|
389
|
+
- choose:
|
|
390
|
+
- conditions: "{{ trigger.event.data.pin == 101 }}"
|
|
391
|
+
sequence:
|
|
392
|
+
- action: notify.mobile_app_phone
|
|
393
|
+
data:
|
|
394
|
+
message: "Alice is home"
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Notify on refused attempts:
|
|
398
|
+
|
|
399
|
+
```yaml
|
|
400
|
+
automation:
|
|
401
|
+
- alias: "Front door - refused"
|
|
402
|
+
triggers:
|
|
403
|
+
- trigger: event
|
|
404
|
+
event_type: zkaccess_native_access
|
|
405
|
+
event_data:
|
|
406
|
+
denied: true
|
|
407
|
+
actions:
|
|
408
|
+
- action: notify.mobile_app_phone
|
|
409
|
+
data:
|
|
410
|
+
message: "Refused at the front door: {{ trigger.event.data.event_name }}"
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
More in [examples/](examples/).
|
|
414
|
+
|
|
415
|
+
## Safety notes (read this)
|
|
416
|
+
|
|
417
|
+
Lessons learned the hard way while reverse-engineering. The library protects you
|
|
418
|
+
against each of them, but you should know them:
|
|
419
|
+
|
|
420
|
+
1. **Writing a user replaces the whole record.** Sending only a new name erases the
|
|
421
|
+
password and the card number. → `save_user()` reads the record and merges first.
|
|
422
|
+
2. **Deleting without a condition erases the whole table.** → `delete_records()` refuses
|
|
423
|
+
unless you pass `allow_wipe=True`.
|
|
424
|
+
3. **Some firmware give a new user a UID that another user already has.** Templates are
|
|
425
|
+
bound to the UID, so a template written then could identify the wrong person.
|
|
426
|
+
→ `save_template()` checks for duplicates and refuses.
|
|
427
|
+
4. **Deleting a user does not delete its templates or its door rights.**
|
|
428
|
+
→ `delete_user()` cascades by default.
|
|
429
|
+
5. **ZKAccess "Add device" with "Clear data in device" checked erases the device**, even
|
|
430
|
+
when it then fails with *"Unknown Device Model"*. Back up first
|
|
431
|
+
(`zkaccess backup device.json`).
|
|
432
|
+
6. ZKAccess does not read door authorizations from the device: syncing its database back
|
|
433
|
+
to the device can leave users without access.
|
|
434
|
+
7. Events are delivered to every open session: if two programs act on events, both will
|
|
435
|
+
act. Do not manage a device from ZKAccess and this library at the same time.
|
|
436
|
+
|
|
437
|
+
## Testing without hardware
|
|
438
|
+
|
|
439
|
+
An emulator speaking the same protocol is included:
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
python -m pyzkaccess_native.emulator --port 4370 &
|
|
443
|
+
zkaccess --host 127.0.0.1 user-set 1 --name Test
|
|
444
|
+
zkaccess --host 127.0.0.1 users
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
In tests:
|
|
448
|
+
|
|
449
|
+
```python
|
|
450
|
+
from pyzkaccess_native import ZKAccess
|
|
451
|
+
from pyzkaccess_native.emulator import Emulator
|
|
452
|
+
|
|
453
|
+
def test_something():
|
|
454
|
+
with Emulator() as emu, ZKAccess("127.0.0.1", emu.port) as dev:
|
|
455
|
+
emu.state.push_event(14, pin=1) # simulate a fingerprint
|
|
456
|
+
assert dev.poll()[0].pin == 1
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
The emulator reproduces the behaviour observed on real devices (whole-record writes,
|
|
460
|
+
device-assigned UIDs, buffered transfers...), but the real device remains the reference.
|
|
461
|
+
|
|
462
|
+
## Troubleshooting
|
|
463
|
+
|
|
464
|
+
| Symptom | Cause / fix |
|
|
465
|
+
|---|---|
|
|
466
|
+
| `cannot connect` / timeout | wrong IP, device on another VLAN without routing, firewall, or a firmware that accepts a single session while another program is connected. |
|
|
467
|
+
| `device error -14` | wrong communication password (`ComPwd`). |
|
|
468
|
+
| `device error -13` | command not supported by this firmware. |
|
|
469
|
+
| no event received | check the polling loop is running; time zone / authorization of the user (event 23 = access denied). |
|
|
470
|
+
| `discover()` finds nothing | broadcasts do not cross routers; connect by IP. |
|
|
471
|
+
| clock drifts | call `set_time()` daily (the integration does it on each connection). |
|
|
472
|
+
|
|
473
|
+
Run with `-vv` (CLI) or `logging.getLogger("pyzkaccess_native").setLevel("DEBUG")` to see
|
|
474
|
+
every frame.
|
|
475
|
+
|
|
476
|
+
## Contributing
|
|
477
|
+
|
|
478
|
+
Issues and pull requests are welcome, especially:
|
|
479
|
+
|
|
480
|
+
- reports from other devices (`zkaccess info`, `zkaccess tables`);
|
|
481
|
+
- captures of PullSDK calls that are not documented yet (see the open questions at the
|
|
482
|
+
end of [docs/PROTOCOL.md](docs/PROTOCOL.md)).
|
|
483
|
+
|
|
484
|
+
```bash
|
|
485
|
+
git clone https://github.com/Avataar120/pyzkaccess && cd pyzkaccess
|
|
486
|
+
pip install -e ".[test]"
|
|
487
|
+
pytest
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
Please never attach real fingerprint templates, passwords or card numbers to an issue.
|
|
491
|
+
|
|
492
|
+
### Releasing (maintainers)
|
|
493
|
+
|
|
494
|
+
1. Bump the version in `src/pyzkaccess_native/__init__.py`, and both `version` and the
|
|
495
|
+
`pyzkaccess-native==` requirement in `custom_components/zkaccess_native/manifest.json`.
|
|
496
|
+
2. Update `CHANGELOG.md`, commit, then create a GitHub release with tag `vX.Y.Z`.
|
|
497
|
+
3. The `Publish to PyPI` workflow builds and uploads the package (PyPI trusted
|
|
498
|
+
publishing, environment `pypi`; no token in the repository). HACS picks up the release.
|
|
499
|
+
|
|
500
|
+
## Legal
|
|
501
|
+
|
|
502
|
+
This is an independent project, not affiliated with or endorsed by ZKTeco. "ZKTeco" and
|
|
503
|
+
"ZKAccess" are trademarks of their owners. The protocol was documented by observing the
|
|
504
|
+
network traffic of software and devices legitimately owned by the author, for
|
|
505
|
+
interoperability purposes. Released under the [MIT license](LICENSE).
|