rbzk 0.1.3 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15c22b690a9f4468b2cd2a819f0d98002c7127ca05a60d32900ffbb93b1785c1
-  data.tar.gz: 6bdccf44dc137c44fa32502a33b5e22331535c628413b99049186c84ef38ab2e
+  metadata.gz: dc6b7b78fa88e4e3cbea5a63aff9a333e1dea98a796de0cc2ab1a8d875f10a64
+  data.tar.gz: ab1527c24665247a5de3393fdf83a9aa0f4c74fe9fe933554ed105968584b56e
 SHA512:
-  metadata.gz: 00710ea8cd440e358a368179472ed0e3663368c93b9c73b3eb4247da44a2bfb8d4890b5a1d228373f2414fa24af330388bbc5095aca027a97cc0acdd0d293387
-  data.tar.gz: ebfee036a5b801a0186e5bf59afedce2e5ef9cd4301fce3c02000b1601198d3a6acf6eb6a59fb531061540a26973ddb1e673894263b6df68b777e1d04138d836
+  metadata.gz: ee91215cdd36830c39e259ab1e42384c8f155d896cb52254105aaf6d36b4167fc7becbd9b4cb632631e32ef23ce2ac57c2de3ecc32990857a56b74a25e26b2d2
+  data.tar.gz: 9bad7c48f98845263d7183362ae7d19a453035747100605e05f6523a0dafd5d9ce9e264dcbfdf2950c297dcff448027716f9edc1a41c18196d89acf4e5942e8e

data/README.md

@@ -24,7 +24,9 @@ Or install it yourself as:
 $ gem install rbzk
 ```
 
-## Usage
+## Library Usage
+
+The `rbzk` gem provides a `RBZK::ZK` class to interact with ZKTeco devices.
 
 ### Basic Connection
 
@@ -32,7 +34,8 @@ $ gem install rbzk
 require 'rbzk'
 
 # Create a new ZK instance
-zk = RBZK::ZK.new('192.168.1.201', port: 4370)
+# Replace with your device's IP address
+zk = RBZK::ZK.new('192.168.1.201', port: 4370, timeout: 60, password: 0)
 
 # Connect to the device
 begin
@@ -46,329 +49,376 @@ begin
     exit 1
   end
 
-  # Disable the device to ensure exclusive access
+  # Disable the device to ensure exclusive access for sensitive operations
   puts 'Disabling device...'
   conn.disable_device
 
-  # Your operations here...
+  # --- Your operations here ---
+  puts "Device Firmware Version: #{conn.get_firmware_version}"
+  puts "Serial Number: #{conn.get_serialnumber}"
+  # --- End of operations ---
 
   # Re-enable the device when done
   puts 'Enabling device...'
   conn.enable_device
-rescue => e
-  puts "Error: #{e.message}"
+rescue RBZK::ZKError => e # Catch specific RBZK errors
+  puts "ZK Error: #{e.message}"
+rescue => e # Catch other potential errors
+  puts "Generic Error: #{e.message}"
 ensure
   # Always disconnect when done
   conn.disconnect if conn && conn.connected?
+  puts "Disconnected."
 end
 ```
 
-### Getting Users
+### Device Information
 
 ```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
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+# (See Basic Connection example)
+
+puts "--- Device Information ---"
+puts "Firmware Version: #{conn.get_firmware_version}"
+puts "Serial Number: #{conn.get_serialnumber}"
+puts "MAC Address: #{conn.get_mac}"
+puts "Device Name: #{conn.get_device_name}"
+puts "Platform: #{conn.get_platform}"
+puts "Fingerprint Algorithm Version: #{conn.get_fp_version}"
+# puts "Face Algorithm Version: #{conn.get_face_version}" # If applicable
+puts "Device Time: #{conn.get_time}"
+
+# Get user, fingerprint, and record counts/capacities
+conn.read_sizes # Updates internal counts
+puts "User Count: #{conn.instance_variable_get(:@users)}"
+puts "Fingerprint Count: #{conn.instance_variable_get(:@fingers)}"
+puts "Attendance Record Count: #{conn.instance_variable_get(:@records)}"
+puts "User Capacity: #{conn.instance_variable_get(:@users_cap)}"
+puts "Fingerprint Capacity: #{conn.instance_variable_get(:@fingers_cap)}"
+puts "Record Capacity: #{conn.instance_variable_get(:@rec_cap)}"
 ```
 
-### Getting Attendance Logs
+### Device Control
 
 ```ruby
-require 'rbzk'
+# Assuming 'conn' is an active and connected RBZK::ZK instance
 
-zk = RBZK::ZK.new('192.168.1.201')
-begin
-  conn = zk.connect
-  conn.disable_device
+# Restart the device
+# conn.restart
+# puts "Device restarting..."
 
-  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
-```
+# Power off the device (use with caution)
+# conn.poweroff
+# puts "Device powering off..."
 
-### Device Operations
+# Test a voice prompt (e.g., "Thank you")
+# conn.test_voice(RBZK::Constants::EF_THANKYOU) # Check Constants for available voice enums
+# puts "Tested voice prompt."
 
-```ruby
-require 'rbzk'
+# Unlock the door for 5 seconds
+conn.unlock(5)
+puts "Door unlocked for 5 seconds."
 
-zk = RBZK::ZK.new('192.168.1.201')
-begin
-  conn = zk.connect
+# Get door lock state
+state = conn.get_lock_state
+puts "Door is #{state ? 'Open' : 'Closed'}."
+```
 
-  # Get device time
-  time = conn.get_time
-  puts "Device time: #{time}"
+### LCD Operations
 
-  # Set device time to current time
-  conn.set_time
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+# Write text to LCD (line number, text)
+conn.write_lcd(1, "Hello from RBZK!")
+puts "Text written to LCD line 1."
+conn.write_lcd(2, Time.now.strftime("%H:%M:%S"))
+puts "Text written to LCD line 2."
+
+# Clear the LCD display
+# sleep 5 # Keep text for 5 seconds
+# conn.clear_lcd
+# puts "LCD cleared."
+```
 
-  # 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]}"
+### User Management
 
-  # Test the device voice
-  conn.test_voice
+#### Getting Users
 
-rescue => e
-  puts "Error: #{e.message}"
-ensure
-  conn.disconnect if conn && conn.connected?
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+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}" # Be mindful of displaying passwords
+  puts "Group ID: #{user.group_id}"
+  puts "User ID (PIN2): #{user.user_id}"
+  puts "Card: #{user.card}"
+  puts "---"
 end
 ```
 
-### Getting Fingerprint Templates
+#### Add/Update User
 
 ```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?
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+puts '--- Add/Update User ---'
+# For a new user, UID can often be omitted if the device assigns it.
+# To update an existing user, provide their UID.
+# conn.read_sizes # Ensure @next_uid is populated if device assigns UIDs
+# new_uid = conn.instance_variable_get(:@next_uid) # Example for new user
+
+user_attributes = {
+  uid: 123, # Specify UID to update, or omit for device to assign (check device behavior)
+  name: 'John Doe',
+  privilege: RBZK::Constants::USER_DEFAULT,
+  password: '1234',
+  group_id: '1',
+  user_id: 'JD123', # Custom User ID / PIN2
+  card: 7890
+}
+
+if conn.set_user(**user_attributes)
+  puts "User #{user_attributes[:name]} (UID: #{user_attributes[:uid] || 'auto'}) added/updated successfully."
+  conn.refresh_data # Good practice to refresh data after modifications
+else
+  puts "Failed to add/update user."
 end
 ```
 
-## Command Line Interface
-
-RBZK provides a powerful command-line interface for interacting with ZKTeco devices. The CLI is built using Thor, which provides a clean, intuitive interface similar to Git and other modern command-line tools.
+#### Delete User
 
-### Installation
-
-After installing the gem, you can use the `rbzk` command directly:
-
-```bash
-# Install the gem
-gem install rbzk
-
-# Use the command
-bin/rbzk info 192.168.100.201
-```
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
 
-If you're using Bundler, you can run the command through `bundle exec`:
+puts '--- Delete User ---'
+uid_to_delete = 123 # UID of the user to delete
 
-```bash
-bundle exec rbzk info 192.168.100.201
+if conn.delete_user(uid: uid_to_delete)
+  puts "User with UID #{uid_to_delete} deleted successfully."
+  conn.refresh_data
+else
+  puts "Failed to delete user with UID #{uid_to_delete} (may not exist)."
+end
 ```
 
-### Available Commands
-
-```bash
-# Get help
-bin/rbzk help
-
-# Get help for a specific command
-bin/rbzk help logs
-```
+### Attendance Log Management
 
-#### Device Information
+#### Getting Attendance Logs
 
-```bash
-# Get device information
-bin/rbzk info 192.168.100.201 [options]
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+puts '--- Get Attendance Logs ---'
+logs = conn.get_attendance_logs
+if logs.empty?
+  puts "No attendance logs found."
+else
+  logs.each_with_index do |log, index|
+    puts "Log ##{index + 1}:"
+    puts "  Device UID: #{log.uid}" # Internal device UID for the record
+    puts "  User ID (PIN2): #{log.user_id}"
+    # Status: Check-in, Check-out, etc. (Refer to ZK documentation for specific status codes)
+    puts "  Status: #{log.status}"
+    # Punch: Fingerprint, Password, Card, etc. (Refer to ZK documentation)
+    puts "  Punch Type: #{log.punch}"
+    puts "  Timestamp: #{log.timestamp.strftime('%Y-%m-%d %H:%M:%S')}"
+    puts "---"
+  end
+end
 ```
 
-#### Users
+#### Clear Attendance Logs
 
-```bash
-# Get users from the device
-bin/rbzk users 192.168.100.201 [options]
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+# puts '--- Clear Attendance Logs ---'
+# puts "WARNING: This will delete all attendance logs from the device."
+# print "Are you sure? (yes/N): "
+# confirmation = gets.chomp
+# if confirmation.downcase == 'yes'
+#   if conn.clear_attendance
+#     puts "Attendance logs cleared successfully."
+#     conn.refresh_data
+#   else
+#     puts "Failed to clear attendance logs."
+#   end
+# else
+#   puts "Operation cancelled."
+# end
 ```
 
-#### Attendance Logs
-
-```bash
-# Get all attendance logs
-bin/rbzk logs 192.168.100.201 [options]
+### Fingerprint Template Management
 
-# Get today's logs
-bin/rbzk logs 192.168.100.201 --today [options]
+*(Note: Fingerprint template data is binary and device-specific. Handling it requires careful understanding of the ZK protocol and template formats.)*
 
-# Get yesterday's logs
-bin/rbzk logs 192.168.100.201 --yesterday [options]
+#### Get All Fingerprint Templates
 
-# Get this week's logs
-bin/rbzk logs 192.168.100.201 --week [options]
-
-# Get this month's logs
-bin/rbzk logs 192.168.100.201 --month [options]
-
-# Get logs for a custom date range
-bin/rbzk logs 192.168.100.201 --start-date=2023-01-01 --end-date=2023-01-31 [options]
-```
-
-#### Clear Logs
-
-```bash
-# Clear attendance logs (will prompt for confirmation)
-bin/rbzk clear_logs 192.168.100.201 [options]
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+puts '--- Get All Fingerprint Templates ---'
+templates = conn.get_templates
+if templates.empty?
+  puts "No fingerprint templates found."
+else
+  templates.each do |fp_template|
+    puts "UID: #{fp_template.uid}, Finger ID: #{fp_template.fid}, Valid: #{fp_template.valid}, Size: #{fp_template.size}"
+  end
+end
 ```
 
-#### Test Voice
+#### Get a Specific User's Fingerprint Template
 
-```bash
-# Test the device voice
-bin/rbzk test_voice 192.168.100.201 [options]
-```
-
-### Global Options
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
 
-These options can be used with any command:
+user_uid = '123' # The user's main UID (often a string from device)
+finger_id = 0    # Finger index (0-9)
 
+begin
+  fp_template = conn.get_user_template(user_uid, finger_id)
+  if fp_template
+    puts "Template for UID #{user_uid}, Finger ID #{finger_id}: Size #{fp_template.size}, Valid: #{fp_template.valid}"
+    # fp_template.template contains the binary data
+  else
+    puts "Template not found for UID #{user_uid}, Finger ID #{finger_id}."
+  end
+rescue RBZK::ZKErrorResponse => e
+  puts "Error getting template: #{e.message}"
+end
 ```
---ip=IP                    # Device IP address (default: from config or 192.168.100.201)
---port=PORT                # Device port (default: from config or 4370)
---timeout=SECONDS          # Connection timeout in seconds (default: from config or 30)
---password=PASSWORD        # Device password (default: from config or 0)
---verbose                  # Enable verbose output (default: from config or false)
---force-udp                # Use UDP instead of TCP (default: from config or false)
---no-ping                  # Skip ping check (default: from config or true)
---encoding=ENCODING        # Character encoding (default: from config or UTF-8)
-```
-
-### Configuration
-
-RBZK supports persistent configuration through a configuration file. This allows you to set default values for IP address and other options without having to specify them every time.
-
-#### Configuration File Location
 
-The configuration file is stored in one of the following locations (in order of precedence):
+#### Set a User's Fingerprint Template
 
-1. `$XDG_CONFIG_HOME/rbzk/config.yml` (if `$XDG_CONFIG_HOME` is set)
-2. `$HOME/.config/rbzk/config.yml` (on most systems)
-3. `.rbzk.yml` in the current directory (fallback)
-
-#### Configuration Commands
-
-```bash
-# Show current configuration
-bin/rbzk config
-
-# Set a configuration value
-bin/rbzk config-set ip 192.168.1.201
-bin/rbzk config-set port 4371
-bin/rbzk config-set password 12345
-bin/rbzk config-set verbose true
-
-# Reset configuration to defaults
-bin/rbzk config-reset
+*(This is an advanced operation. You need valid template data.)*
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+# And `valid_template_data` is a binary string of a valid fingerprint template
+
+# user_uid = '123'
+# finger_id = 0
+# valid_flag = 1 # 1 for valid, 0 for invalid/duplicate
+# valid_template_data = "BINARY_TEMPLATE_DATA_HERE" # Replace with actual binary data
+
+# begin
+#   if conn.set_user_template(valid_template_data, user_uid, finger_id, valid_flag)
+#     puts "Fingerprint template set successfully for UID #{user_uid}, Finger ID #{finger_id}."
+#     conn.refresh_data
+#   else
+#     puts "Failed to set fingerprint template."
+#   end
+# rescue RBZK::ZKErrorResponse => e
+#   puts "Error setting template: #{e.message}"
+# end
 ```
 
-When you run commands, the CLI will use values from the configuration file as defaults. Command-line options will override the configuration file values.
-
-### Examples
+#### Delete/Clear Fingerprint Templates
 
-```bash
-# Get device information
-bin/rbzk info 192.168.100.201
-
-# Get users with custom port and password
-bin/rbzk users 192.168.100.201 --port=4371 --password=12345
-
-# Get today's attendance logs with verbose output
-bin/rbzk logs 192.168.100.201 --today --verbose
-
-# Get logs for a custom date range (two ways)
-bin/rbzk logs-custom 2023-01-01 2023-01-31 192.168.100.201
-bin/rbzk logs 192.168.100.201 --start-date=2023-01-01 --end-date=2023-01-31
-
-# Get logs from a specific date to today
-bin/rbzk logs 192.168.100.201 --start-date=2023-01-01
-
-# Get logs from 30 days before to a specific date
-bin/rbzk logs 192.168.100.201 --end-date=2023-01-31
-
-# Test voice with UDP connection
-bin/rbzk test_voice 192.168.100.201 --force-udp
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+# Delete a specific fingerprint for a user
+# user_uid_for_fp_delete = '123'
+# finger_id_to_delete = 0
+# if conn.delete_user_template(user_uid_for_fp_delete, finger_id_to_delete)
+#   puts "Template for UID #{user_uid_for_fp_delete}, FID #{finger_id_to_delete} deleted."
+#   conn.refresh_data
+# else
+#   puts "Failed to delete template."
+# end
+
+# Clear all fingerprint templates for a specific user
+# user_uid_to_clear_fps = '123'
+# if conn.clear_user_template(user_uid_to_clear_fps) # Method name might vary, e.g., delete_user_fingerprints
+#   puts "All templates for UID #{user_uid_to_clear_fps} cleared."
+#   conn.refresh_data
+# else
+#   puts "Failed to clear user templates."
+# end
+
+# Clear ALL fingerprint templates on the device (Use with extreme caution!)
+# puts "WARNING: This will delete ALL fingerprint templates from the device."
+# print "Are you sure? (yes/N): "
+# confirmation_clear_all_fp = gets.chomp
+# if confirmation_clear_all_fp.downcase == 'yes'
+#   if conn.clear_templates # Or clear_fingerprints
+#     puts "All fingerprint templates cleared from device."
+#     conn.refresh_data
+#   else
+#     puts "Failed to clear all fingerprint templates."
+#   end
+# else
+#   puts "Operation cancelled."
+# end
 ```
 
-### Pretty Output
-
-The command line interface uses the `terminal-table` gem for prettier output if it's available. To enable this feature, install the gem:
+### Device Time
 
-```bash
-gem install terminal-table
+```ruby
+# Assuming 'conn' is an active and connected RBZK::ZK instance
+
+# Get device time
+current_device_time = conn.get_time
+puts "Current device time: #{current_device_time}"
+
+# Set device time (to current system time)
+# new_time = Time.now
+# if conn.set_time(new_time)
+#   puts "Device time set to #{new_time} successfully."
+# else
+#   puts "Failed to set device time."
+# end
 ```
 
-If the gem is not available, the CLI will fall back to plain text output.
+## Command Line Interface (CLI)
 
-## Development
+The `rbzk` gem also provides a command-line tool named `rbzk` for quick interactions with your ZKTeco devices.
 
-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).
+### Global Options
 
-## Contributing
+These options can be used with most commands:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/shqear93/rbzk.
+*   `--ip <IP_ADDRESS>`: IP address of the device.
+*   `--port <PORT>`: Port number (default: 4370).
+*   `--timeout <SECONDS>`: Connection timeout in seconds (default: 30 or 60).
+*   `--password <PASSWORD>`: Device communication password (default: 0).
+*   `--verbose`: Enable verbose output.
+*   `--force-udp`: Force UDP mode for communication.
+*   `--no-ping`: Skip the initial ping check.
+*   `--encoding <ENCODING>`: String encoding (default: UTF-8).
 
-## License
+### Available Commands
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Here are some of the primary commands available:
+
+*   `rbzk info [--ip IP]`: Get detailed device information.
+*   `rbzk refresh [--ip IP]`: Refresh the device's internal data (useful after making changes).
+*   `rbzk users [--ip IP]`: List all users on the device.
+*   `rbzk logs [--ip IP] [options]`: Get attendance logs.
+    *   `--today`: Get today's logs.
+    *   `--yesterday`: Get yesterday's logs.
+    *   `--week`: Get logs for the current week.
+    *   `--month`: Get logs for the current month.
+    *   `--start-date YYYY-MM-DD`: Filter logs from a specific start date.
+    *   `--end-date YYYY-MM-DD`: Filter logs up to a specific end date.
+    *   `--limit N`: Limit the number of logs displayed (0 for all).
+    *   Aliases: `rbzk logs-today`, `rbzk logs-yesterday`, `rbzk logs-week`, `rbzk logs-month`.
+*   `rbzk logs-all [--ip IP]`: Get all attendance logs without any limit.
+*   `rbzk logs-custom <START_DATE> <END_DATE> [--ip IP]`: Get logs for a custom date range (YYYY-MM-DD).
+*   `rbzk clear-logs [--ip IP]`: Clear all attendance logs from the device (prompts for confirmation).
+*   `rbzk unlock [--ip IP] [--time SECONDS]`: Unlock the connected door (default 3 seconds).
+*   `rbzk door-state [--ip IP]`: Get the current state of the door lock (Open/Closed).
+*   `rbzk write-lcd <LINE_NUMBER> <TEXT> [--ip IP]`: Write text to the device's LCD screen.
+*   `rbzk clear-lcd [--ip IP]`: Clear the device's LCD screen.
+*   `rbzk add-user [--ip IP] [options]`: Add or update a user.
+    *   `--uid <UID