rbzk 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05c19d8aa64a72f6ca80b430058d5956f2c8250a59c60fb26548c9f546d62c3f
-  data.tar.gz: 3ddd33169741c8f2df4046e9add74e21b4f8e4faccc8b5beb25994ac4b546cdc
+  metadata.gz: c4e93719b6428a029bf767e708352ee0ac29e26735050288b5848eb9aea2c7b7
+  data.tar.gz: b40b96e9c5b4f123f93314a4f51730286a7b5a1d59b5f6e16322b6a583e9f766
 SHA512:
-  metadata.gz: 296b1eba45da43e51ef8e228fec546ad6b14894f1279219e66ff8f546469bb81e3a848f857d30b352a6a9db201762eee41a438ff606d041fe2e574e254840eab
-  data.tar.gz: 6132ea677b868d354db28fc26e32087b933234985a7aaccfc029da1f220bd1655865350b086ef1cc8756f6f190ba41162ef5deaa36f8aa55c8f947d1076b9d38
+  metadata.gz: be9a441a5718f1733bfd03181461767f4f2c3f76951f643e35d8c17efbfceef7b3db420fbf58ba757ab146a0b2756fcdfc4ad791dfea67536ed11b26019cdc29
+  data.tar.gz: 73687d3eb95d16bb53e6e2e1abb33e94e14afd8f235610933d3923284f213b4b73a61fbec2d8d20d8459bc33e03d8311bdff5e4cdd612907b45412b912535016

data/README.md

@@ -2,6 +2,8 @@
 
 A Ruby implementation of the ZK protocol for fingerprint and biometric attendance devices.
 
+This project is inspired by and based on the [pyzk Python library](https://github.com/fananimi/pyzk), adapting its protocol implementation to Ruby while maintaining compatibility with ZKTeco devices.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -191,9 +193,168 @@ ensure
 end
 ```
 
-### Complete Example
+## 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.
+
+### 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
+```
+
+If you're using Bundler, you can run the command through `bundle exec`:
+
+```bash
+bundle exec rbzk info 192.168.100.201
+```
+
+### Available Commands
+
+```bash
+# Get help
+bin/rbzk help
+
+# Get help for a specific command
+bin/rbzk help logs
+```
+
+#### Device Information
+
+```bash
+# Get device information
+bin/rbzk info 192.168.100.201 [options]
+```
+
+#### Users
+
+```bash
+# Get users from the device
+bin/rbzk users 192.168.100.201 [options]
+```
+
+#### Attendance Logs
+
+```bash
+# Get all attendance logs
+bin/rbzk logs 192.168.100.201 [options]
+
+# Get today's logs
+bin/rbzk logs 192.168.100.201 --today [options]
+
+# Get yesterday's logs
+bin/rbzk logs 192.168.100.201 --yesterday [options]
+
+# 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]
+```
+
+#### Test Voice
+
+```bash
+# Test the device voice
+bin/rbzk test_voice 192.168.100.201 [options]
+```
+
+### Global Options
+
+These options can be used with any command:
+
+```
+--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):
+
+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
+```
+
+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
+
+```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
+```
+
+### 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:
+
+```bash
+gem install terminal-table
+```
 
-See the `examples/complete_example.rb` file for a comprehensive example that demonstrates all the main functionality of the gem.
+If the gem is not available, the CLI will fall back to plain text output.
 
 ## Development
 

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rbzk"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rbzk

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'rbzk/cli/commands'
+
+RBZK::CLI::Commands.start(ARGV)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install