rbzk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05c19d8aa64a72f6ca80b430058d5956f2c8250a59c60fb26548c9f546d62c3f
+  data.tar.gz: 3ddd33169741c8f2df4046e9add74e21b4f8e4faccc8b5beb25994ac4b546cdc
+SHA512:
+  metadata.gz: 296b1eba45da43e51ef8e228fec546ad6b14894f1279219e66ff8f546469bb81e3a848f857d30b352a6a9db201762eee41a438ff606d041fe2e574e254840eab
+  data.tar.gz: 6132ea677b868d354db28fc26e32087b933234985a7aaccfc029da1f220bd1655865350b086ef1cc8756f6f190ba41162ef5deaa36f8aa55c8f947d1076b9d38

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2023-05-04
+
+- Initial release
+- Basic ZK protocol implementation
+- Support for connecting to ZK devices (both UDP and TCP)
+- Support for getting users and attendance logs
+- Support for getting fingerprint templates
+- Support for basic device operations (restart, poweroff, test voice)
+- Support for getting and setting device time
+- Support for clearing data and attendance logs
+- Connection status checking with connected? method

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Khaled AbuShqear
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,213 @@
+# RBZK
+
+A Ruby implementation of the ZK protocol for fingerprint and biometric attendance devices.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rbzk'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install rbzk
+```
+
+## Usage
+
+### Basic Connection
+
+```ruby
+require 'rbzk'
+
+# Create a new ZK instance
+zk = RBZK::ZK.new('192.168.1.201', port: 4370)
+
+# Connect to the device
+begin
+  conn = zk.connect
+
+  # Check if connected successfully
+  if conn.connected?
+    puts "Connected successfully!"
+  else
+    puts "Connection failed!"
+    exit 1
+  end
+
+  # Disable the device to ensure exclusive access
+  puts 'Disabling device...'
+  conn.disable_device
+
+  # Your operations here...
+
+  # Re-enable the device when done
+  puts 'Enabling device...'
+  conn.enable_device
+rescue => e
+  puts "Error: #{e.message}"
+ensure
+  # Always disconnect when done
+  conn.disconnect if conn && conn.connected?
+end
+```
+
+### Getting Users
+
+```ruby
+require 'rbzk'
+
+zk = RBZK::ZK.new('192.168.1.201')
+begin
+  conn = zk.connect
+  conn.disable_device
+
+  puts '--- Get Users ---'
+  users = conn.get_users
+  users.each do |user|
+    privilege = 'User'
+    privilege = 'Admin' if user.privilege == RBZK::Constants::USER_ADMIN
+
+    puts "UID: #{user.uid}"
+    puts "Name: #{user.name}"
+    puts "Privilege: #{privilege}"
+    puts "Password: #{user.password}"
+    puts "Group ID: #{user.group_id}"
+    puts "User ID: #{user.user_id}"
+    puts "---"
+  end
+
+  conn.enable_device
+rescue => e
+  puts "Error: #{e.message}"
+ensure
+  conn.disconnect if conn && conn.connected?
+end
+```
+
+### Getting Attendance Logs
+
+```ruby
+require 'rbzk'
+
+zk = RBZK::ZK.new('192.168.1.201')
+begin
+  conn = zk.connect
+  conn.disable_device
+
+  puts '--- Get Attendance Logs ---'
+  logs = conn.get_attendance_logs
+  logs.each do |log|
+    puts "User ID: #{log.user_id}"
+    puts "Timestamp: #{log.timestamp}"
+    puts "Status: #{log.status}"
+    puts "Punch: #{log.punch}"
+    puts "UID: #{log.uid}"
+    puts "---"
+  end
+
+  conn.enable_device
+rescue => e
+  puts "Error: #{e.message}"
+ensure
+  conn.disconnect if conn && conn.connected?
+end
+```
+
+### Device Operations
+
+```ruby
+require 'rbzk'
+
+zk = RBZK::ZK.new('192.168.1.201')
+begin
+  conn = zk.connect
+
+  # Get device time
+  time = conn.get_time
+  puts "Device time: #{time}"
+
+  # Set device time to current time
+  conn.set_time
+
+  # Get device info
+  info = conn.get_free_sizes
+  puts "Users: #{info[:users]}"
+  puts "Fingers: #{info[:fingers]}"
+  puts "Capacity: #{info[:capacity]}"
+  puts "Logs: #{info[:logs]}"
+  puts "Passwords: #{info[:passwords]}"
+
+  # Test the device voice
+  conn.test_voice
+
+rescue => e
+  puts "Error: #{e.message}"
+ensure
+  conn.disconnect if conn && conn.connected?
+end
+```
+
+### Getting Fingerprint Templates
+
+```ruby
+require 'rbzk'
+
+zk = RBZK::ZK.new('192.168.1.201')
+begin
+  conn = zk.connect
+  conn.disable_device
+
+  puts '--- Get Fingerprint Templates ---'
+  templates = conn.get_templates
+  templates.each do |template|
+    puts "UID: #{template.uid}"
+    puts "Finger ID: #{template.fid}"
+    puts "Valid: #{template.valid == 1 ? 'Yes' : 'No'}"
+    puts "Template size: #{template.template.size} bytes"
+    puts "---"
+  end
+
+  # Get a specific user's template
+  if templates.any?
+    user_template = conn.get_user_template(templates.first.uid, templates.first.fid)
+    puts "Got specific template for user #{user_template.uid}, finger #{user_template.fid}"
+  end
+
+  conn.enable_device
+rescue => e
+  puts "Error: #{e.message}"
+ensure
+  conn.disconnect if conn && conn.connected?
+end
+```
+
+### Complete Example
+
+See the `examples/complete_example.rb` file for a comprehensive example that demonstrates all the main functionality of the gem.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/shqear93/rbzk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rbzk/attendance.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RBZK
+  class Attendance
+    attr_accessor :user_id, :timestamp, :status, :punch, :uid
+
+    def initialize(user_id, timestamp, status, punch, uid)
+      @user_id = user_id
+      @timestamp = timestamp
+      @status = status
+      @punch = punch
+      @uid = uid
+    end
+
+    def to_s
+      "#{@user_id} #{@timestamp} #{@status} #{@punch} #{@uid}"
+    end
+  end
+end

data/lib/rbzk/constants.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RBZK
+  module Constants
+    USHRT_MAX = 65535
+
+    # Command codes
+    CMD_DB_RRQ = 7 # Read in some kind of data from the machine
+    CMD_USER_WRQ = 8 # Upload the user information (from PC to terminal)
+    CMD_USERTEMP_RRQ = 9 # Read some fingerprint template or some kind of data entirely
+    CMD_USERTEMP_WRQ = 10 # Upload some fingerprint template
+    CMD_OPTIONS_RRQ = 11 # Read in the machine some configuration parameter
+    CMD_OPTIONS_WRQ = 12 # Set machines configuration parameter
+    CMD_ATTLOG_RRQ = 13 # Read all attendance record
+    CMD_CLEAR_DATA = 14 # clear Data
+    CMD_CLEAR_ATTLOG = 15 # Clear attendance records
+    CMD_DELETE_USER = 18 # Delete some user
+    CMD_DELETE_USERTEMP = 19 # Delete some fingerprint template
+    CMD_CLEAR_ADMIN = 20 # Cancel the manager
+    CMD_USERGRP_RRQ = 21 # Read the user grouping
+    CMD_USERGRP_WRQ = 22 # Set users grouping
+    CMD_USERTZ_RRQ = 23 # Read the user Time Zone set
+    CMD_USERTZ_WRQ = 24 # Write the user Time Zone set
+    CMD_GRPTZ_RRQ = 25 # Read the group Time Zone set
+    CMD_GRPTZ_WRQ = 26 # Write the group Time Zone set
+    CMD_TZ_RRQ = 27 # Read Time Zone set
+    CMD_TZ_WRQ = 28 # Write the Time Zone
+    CMD_ULG_RRQ = 29 # Read unlocks combination
+    CMD_ULG_WRQ = 30 # write unlocks combination
+    CMD_UNLOCK = 31 # unlock
+    CMD_CLEAR_ACC = 32 # Restores Access Control set to the default condition
+    CMD_CLEAR_OPLOG = 33 # Delete attendance machines all attendance record
+    CMD_OPLOG_RRQ = 34 # Read manages the record
+    CMD_GET_FREE_SIZES = 50 # Obtain machines condition, like user recording number and so on
+    CMD_ENABLE_CLOCK = 57 # Ensure the machine to be at the normal work condition
+    CMD_STARTVERIFY = 60 # Ensure the machine to be at the authentication condition
+    CMD_STARTENROLL = 61 # Start to enroll some user, ensure the machine to be at the registration user condition
+    CMD_CANCELCAPTURE = 62 # Make the machine to be at the waiting order status
+    CMD_STATE_RRQ = 64 # Gain the machine the condition
+    CMD_WRITE_LCD = 66 # Write LCD
+    CMD_CLEAR_LCD = 67 # Clear the LCD captions (clear screen)
+    CMD_GET_PINWIDTH = 69 # Obtain the length of user's serial number
+    CMD_SMS_WRQ = 70 # Upload the short message
+    CMD_SMS_RRQ = 71 # Download the short message
+    CMD_DELETE_SMS = 72 # Delete the short message
+    CMD_UDATA_WRQ = 73 # Set user's short message
+    CMD_DELETE_UDATA = 74 # Delete user's short message
+    CMD_DOORSTATE_RRQ = 75 # Obtain the door condition
+    CMD_WRITE_MIFARE = 76 # Write the Mifare card
+    CMD_EMPTY_MIFARE = 78 # Clear the Mifare card
+    CMD_PREPARE_BUFFER = 80 # Prepare buffer for data transfer
+    CMD_READFILE_DATA = 81 # Read data from buffer
+    CMD_GET_USERTEMP = 88 # Get an specific user template (uid, fid)
+    CMD_SAVE_USERTEMPS = 110 # Save user and multiple templates
+    CMD_DEL_USER_TEMP = 134 # Delete an specific user template (uid, fid)
+
+    CMD_GET_TIME = 201 # Obtain the machine time
+    CMD_SET_TIME = 202 # Set machines time
+    CMD_REG_EVENT = 500 # Register the event
+
+    CMD_CONNECT = 1000 # Connections requests
+    CMD_EXIT = 1001 # Disconnection requests
+    CMD_ENABLEDEVICE = 1002 # Ensure the machine to be at the normal work condition
+    CMD_DISABLEDEVICE = 1003 # Make the machine to be at the shut-down condition
+    CMD_RESTART = 1004 # Restart the machine
+    CMD_POWEROFF = 1005 # Shut-down power source
+    CMD_SLEEP = 1006 # Ensure the machine to be at the idle state
+    CMD_RESUME = 1007 # Awakens the sleep machine (temporarily not to support)
+    CMD_CAPTUREFINGER = 1009 # Captures fingerprints picture
+    CMD_TEST_TEMP = 1011 # Test some fingerprint exists or does not
+    CMD_CAPTUREIMAGE = 1012 # Capture the entire image
+    CMD_REFRESHDATA = 1013 # Refresh the machine interior data
+    CMD_REFRESHOPTION = 1014 # Refresh the configuration parameter
+    CMD_TESTVOICE = 1017 # Play voice
+    CMD_GET_VERSION = 1100 # Obtain the firmware edition
+    CMD_CHANGE_SPEED = 1101 # Change transmission speed
+    CMD_AUTH = 1102 # Connections authorizations
+    CMD_PREPARE_DATA = 1500 # Prepares to transmit the data
+    CMD_DATA = 1501 # Transmit a data packet
+    CMD_FREE_DATA = 1502 # Clear machines opened buffer
+    CMD_PREPARE_BUFFER = 1503 # Initialize buffer for partial reads
+    CMD_READ_BUFFER = 1504 # Ready a partial chunk of data from buffer
+
+    CMD_ACK_OK = 2000 # Return value for order perform successfully
+    CMD_ACK_ERROR = 2001 # Return value for order perform failed
+    CMD_ACK_DATA = 2002 # Return data
+    CMD_ACK_RETRY = 2003 # Registered event occurred
+    CMD_ACK_REPEAT = 2004 # Not available
+    CMD_ACK_UNAUTH = 2005 # Connection unauthorized
+
+    CMD_ACK_UNKNOWN = 0xffff # Unknown order
+    CMD_ACK_ERROR_CMD = 0xfffd # Order false
+    CMD_ACK_ERROR_INIT = 0xfffc # Not Initialized
+    CMD_ACK_ERROR_DATA = 0xfffb # Not available
+
+    # Event flags
+    EF_ATTLOG = 1 # Be real-time to verify successfully
+    EF_FINGER = (1 << 1) # Be real-time to press fingerprint
+    EF_ENROLLUSER = (1 << 2) # Be real-time to enroll user
+    EF_ENROLLFINGER = (1 << 3) # Be real-time to enroll fingerprint
+    EF_BUTTON = (1 << 4) # Be real-time to press button
+    EF_UNLOCK = (1 << 5) # Be real-time to unlock
+    EF_VERIFY = (1 << 7) # Be real-time to verify fingerprint
+    EF_FPFTR = (1 << 8) # Be real-time capture fingerprint minutia
+    EF_ALARM = (1 << 9) # Alarm signal
+
+    # User types
+    USER_DEFAULT = 0
+    USER_ENROLLER = 2
+    USER_MANAGER = 6
+    USER_ADMIN = 14
+
+    # Data flags
+    FCT_ATTLOG = 1
+    FCT_WORKCODE = 8
+    FCT_FINGERTMP = 2
+    FCT_OPLOG = 4
+    FCT_USER = 5
+    FCT_SMS = 6
+    FCT_UDATA = 7
+
+    # Machine constants
+    # These values are in little-endian format when packed
+    # 0x5050 = 'PP' in ASCII when packed as '<H'
+    MACHINE_PREPARE_DATA_1 = 20560 # 0x5050 = 'P' + 'P'*256 in little-endian
+    # 0x7D82 = 0x827D in little-endian format
+    MACHINE_PREPARE_DATA_2 = 32130 # 0x7D82
+  end
+end

data/lib/rbzk/exceptions.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RBZK
+  class ZKError < StandardError; end
+
+  class ZKNetworkError < ZKError
+    def initialize(msg = "Network error")
+      super
+    end
+  end
+
+  class ZKErrorConnection < ZKError
+    def initialize(msg = "Connection error")
+      super
+    end
+  end
+
+  class ZKErrorResponse < ZKError
+    def initialize(msg = "Invalid response")
+      super
+    end
+  end
+end

data/lib/rbzk/finger.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RBZK
+  class Finger
+    attr_accessor :uid, :fid, :valid, :template
+
+    def initialize(uid, fid, valid, template = "")
+      @uid = uid
+      @fid = fid
+      @valid = valid
+      @template = template
+    end
+
+    def to_s
+      "#{@uid} #{@fid} #{@valid} #{@template.length}"
+    end
+  end
+end

data/lib/rbzk/user.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RBZK
+  class User
+    attr_accessor :uid, :user_id, :name, :privilege, :password, :group_id, :card
+
+    @@encoding = "UTF-8"
+
+    def self.encoding=(encoding)
+      @@encoding = encoding
+    end
+
+    def self.encoding
+      @@encoding
+    end
+
+    # Match Python's User constructor exactly
+    # In Python:
+    # def __init__(self, uid, name, privilege, password='', group_id='', user_id='', card=0):
+    def initialize(uid = 0, name = "", privilege = 0, password = "", group_id = "", user_id = "", card = 0)
+      @uid = uid
+      @name = name
+      @privilege = privilege
+      @password = password
+      @group_id = group_id
+      @user_id = user_id
+      @card = card
+    end
+
+    def to_s
+      "#{@uid} #{@user_id} #{@name} #{@privilege} #{@password} #{@group_id} #{@card}"
+    end
+  end
+end

data/lib/rbzk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RBZK
+  VERSION = "0.1.0"
+end