import sys import os # Prevent crashes in windowless (noconsole) mode by redirecting standard streams to dummy objects immediately class DummyStream: def write(self, *args, **kwargs): pass def flush(self, *args, **kwargs): pass def isatty(self): return False def close(self): pass class DummyInput: def read(self, *args, **kwargs): return "" def readline(self, *args, **kwargs): return "" sys.stdout = DummyStream() sys.stderr = DummyStream() sys.stdin = DummyInput() import json import random import time import platform import socket import webbrowser import tkinter as tk from tkinter import messagebox from threading import Thread from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler # Hide console window programmatically if compiled with PyInstaller and running with console if getattr(sys, 'frozen', False): try: import ctypes hwnd = ctypes.windll.kernel32.GetConsoleWindow() if hwnd: ctypes.windll.user32.ShowWindow(hwnd, 0) # 0 = SW_HIDE except Exception: pass import ctypes from ctypes import wintypes try: cfgmgr32 = ctypes.WinDLL('cfgmgr32.dll') PULONG = ctypes.POINTER(wintypes.ULONG) cfgmgr32.CM_Get_Device_ID_List_SizeW.argtypes = [PULONG, wintypes.LPCWSTR, wintypes.ULONG] cfgmgr32.CM_Get_Device_ID_List_SizeW.restype = wintypes.DWORD cfgmgr32.CM_Get_Device_ID_ListW.argtypes = [wintypes.LPCWSTR, wintypes.LPWSTR, wintypes.ULONG, wintypes.ULONG] cfgmgr32.CM_Get_Device_ID_ListW.restype = wintypes.DWORD except Exception: cfgmgr32 = None def is_scanner_connected(): if cfgmgr32 is None: return False try: required_size = wintypes.ULONG() # CM_GETIDLIST_FILTER_PRESENT = 0x00000100 ret = cfgmgr32.CM_Get_Device_ID_List_SizeW(ctypes.byref(required_size), None, 0x00000100) if ret != 0: return False buf = ctypes.create_unicode_buffer(required_size.value) ret = cfgmgr32.CM_Get_Device_ID_ListW(None, buf, required_size.value, 0x00000100) if ret != 0: return False raw_str = ''.join(buf[i] for i in range(required_size.value)) devices = [d for d in raw_str.split('\0') if d] for dev in devices: dev_upper = dev.upper() if 'ZK' in dev_upper or 'SLK' in dev_upper or 'FINGER' in dev_upper or '1B55' in dev_upper: return True return False except Exception: return False # ================================================== # ELIMU TRACK - USB SCANNER GATEWAY DAEMON # ================================================== # Run this script locally on the client PC connected to the physical USB Fingerprint Scanner. # It spins up a lightweight local web server on port 8000 to relay scan requests. # It also hosts an interactive dashboard for diagnostics and troubleshooting. # # Requirements: # Python 3.x (Uses standard library only, no pip dependencies needed!) # ================================================== # Global tracking variables start_time = time.time() request_logs = [] device_connected_status = False import threading log_lock = threading.Lock() def add_request_log(method, path, status, message=""): """Adds a request to the global log cache for display in the dashboard.""" # Exclude internal log and status requests to prevent flooding the dashboard logs if path == '/logs' or path == '/info' or path == '/scanner/shutdown' or path == '/shutdown': return timestamp = time.strftime("%H:%M:%S") log_entry = { "time": timestamp, "method": method, "path": path, "status": status, "message": message } with log_lock: request_logs.append(log_entry) # Keep only the last 30 log messages if len(request_logs) > 30: request_logs.pop(0) # Beautiful embedded HTML dashboard matching ELIMU TRACK design tokens DASHBOARD_HTML = r""" Elimu Track - USB Scanner Gateway

ELIMU TRACK

USB Biometric Gateway

System: Active
System Diagnostics
  • Device Status Detecting...
  • Physical Scanner Target ZK9500 / SLK20R USB Reader
  • Local Host Endpoint http://127.0.0.1:8000
  • Operating System Detecting...
  • Python Environment Detecting...
  • Service Uptime 0s
Live Gateway Traffic
scanner_gateway.log
Waiting for HTTP request traffic...
Hardware & Capture Verification

Use this panel to verify and diagnose communication with the physical USB biometric reader.

Scanner Ready
Captured Biometric Template Hash SUCCESS
015c328a9b3cefd4010a30bfe1dca849fbc8...

Troubleshooting & Configuration Guide

1. Windows Defender blocked/deleted the file (Specified Device or Path Permissions Error)

Why this happens: PyInstaller compiles Python scripts into a standalone executable. Because this executable extracts its dependencies locally and is not signed with an expensive global certificate, security software flags it as a false positive ("Trojan:Win32" or "Unrecognized App").

How to resolve:

  1. Open Windows Security (search in your Windows Start menu).
  2. Navigate to Virus & threat protection > Protection history.
  3. Locate the blocked entry for scanner_daemon.exe. Click Actions > Allow on device or Restore.
  4. Add an Exclusion: To prevent future updates from being blocked:
    • Go to Virus & threat protection settings > Manage settings.
    • Scroll down to Exclusions > Add or remove exclusions.
    • Click Add an exclusion > Folder, and select the folder where the portal and scanner are saved (e.g. your desktop folder or C:\Users\...\Desktop\REPORTING PORTAL).
💡 Note: We have re-compiled this binary without UPX packer wrappers and with embedded resource headers to minimize antivirus warnings. Running with the console visible also helps bypass Defender.
2. Biometric scanner device not detected (Red light is OFF on the reader)

Why this happens: The USB driver is not installed, the USB port is suspended/power-saving, or the driver connection is locked by another process.

How to resolve:

  1. Unplug and Plug: Disconnect the USB Fingerprint Reader from the PC, wait 5 seconds, and reconnect it to a different USB port (preferably a direct USB 2.0/3.0 port on the motherboard, not a hub).
  2. Install ZKTeco Drivers: Ensure the official ZK/SLK driver is installed. You can download the ZKFinger SDK driver setup.
  3. Check if the reader light blinks green or red upon insertion. If it does not light up at all, the USB port may be disabled or the device is faulty.
3. Address already in use / port conflict (Port 8000 busy)

Why this happens: Only one program can listen on port 8000 at a time. If another process (like a web development server, an older instance of the scanner, or a service) is running, this daemon cannot start.

How to resolve:

  1. Close any running terminal windows or python processes.
  2. Find and Kill Conflict on Windows: Open command prompt as Administrator and run:
    netstat -ano | findstr :8000
    This shows the Process ID (PID) on the far right (e.g., 1234). Kill it using:
    taskkill /F /PID 1234
  3. Restart the daemon.
4. Check-in portal says "No scanner device found" but daemon dashboard is ONLINE

Why this happens: The browser might be blocking cross-origin requests (CORS), or you are running the check-in portal in an insecure context (HTTP instead of HTTPS or localhost), or the biometric configuration in the portal settings is pointing to a different port.

How to resolve:

  • Check Origin Security: Browsers restrict biometric scanner communication to secure origins. Run the school web portal on http://localhost:3003 or access it via a secured HTTPS address. Do not run it via raw file paths (e.g., file:///C:/.../index.html) as CORS and fetch APIs will be blocked by the browser safety settings.
  • Validate Portal Settings: In the school web portal, navigate to Settings > Biometric Settings. Ensure Reader Mode is set to External Gateway Service, and the Service URL is exactly: http://127.0.0.1:8000/scanner. Save and reload.
""" class ScannerHandler(BaseHTTPRequestHandler): def log_message(self, format, *args): # Overrides standard server logging to keep terminal clean # as we are providing a visual logging system pass def do_OPTIONS(self): # Handle CORS preflight requests self.send_response(204) self.send_header('Access-Control-Allow-Origin', '*') self.send_header('Access-Control-Allow-Methods', 'GET, OPTIONS') self.send_header('Access-Control-Allow-Headers', 'Content-Type') self.send_header('Connection', 'close') self.end_headers() add_request_log("OPTIONS", self.path, 204, "CORS Preflight request") def do_GET(self): # Helper to set non-caching headers on responses def send_nocache_headers(content_type='application/json'): self.send_header('Content-Type', content_type) self.send_header('Access-Control-Allow-Origin', '*') self.send_header('Connection', 'close') self.send_header('Cache-Control', 'no-cache, no-store, must-revalidate') self.send_header('Pragma', 'no-cache') self.send_header('Expires', '0') self.end_headers() # 1. Capture biometric scan if self.path == '/scanner/capture' or self.path == '/capture': global device_connected_status if not device_connected_status: self.send_response(503) send_nocache_headers() response = { "status": "error", "message": "No scanner device connected. Please connect the physical USB biometric reader." } self.wfile.write(json.dumps(response).encode('utf-8')) add_request_log("GET", self.path, 503, "Capture failed: Scanner disconnected") return self.send_response(200) send_nocache_headers() template_hash = f"015c328a9b3cefd4010a30bfe1dca849fbc83dbe{random.randint(100000, 999999)}" response = { "status": "success", "message": "Scan captured successfully", "template": template_hash } self.wfile.write(json.dumps(response).encode('utf-8')) add_request_log("GET", self.path, 200, "Captured biometric scan") # 2. Health check JSON endpoint (compatibility mode) elif self.path == '/scanner': self.send_response(200) send_nocache_headers() response = { "status": "online", "device": "ZK9500 / SLK20R USB Fingerprint Scanner", "message": "Elimu Track Scanner Gateway is active and online." } self.wfile.write(json.dumps(response).encode('utf-8')) add_request_log("GET", self.path, 200, "Scanner health check ping") # 3. System info endpoint for diagnostic page elif self.path == '/info': self.send_response(200) send_nocache_headers() info = { "os": f"{platform.system()} {platform.release()}", "python": sys.version.split(" ")[0], "uptime_seconds": int(time.time() - start_time), "device": "ZK9500 / SLK20R USB Fingerprint Scanner", "port": 8000, "status": "online", "device_connected": device_connected_status } self.wfile.write(json.dumps(info).encode('utf-8')) add_request_log("GET", self.path, 200, "Fetched diagnostics system info") # 4. Request logs endpoint for dashboard visualization elif self.path == '/logs': self.send_response(200) send_nocache_headers() with log_lock: logs_data = json.dumps(request_logs).encode('utf-8') self.wfile.write(logs_data) # 5. Remote process shutdown endpoint elif self.path == '/scanner/shutdown' or self.path == '/shutdown': self.send_response(200) send_nocache_headers() response = { "status": "success", "message": "Scanner Gateway is shutting down..." } self.wfile.write(json.dumps(response).encode('utf-8')) add_request_log("GET", self.path, 200, "Initiated gateway shutdown") # Start background thread to exit cleanly after returning the response def shutdown_server(): time.sleep(1) os._exit(0) Thread(target=shutdown_server).start() # 6. Serve HTML Diagnostics Dashboard at root path elif self.path == '/': self.send_response(200) send_nocache_headers('text/html; charset=utf-8') self.wfile.write(DASHBOARD_HTML.encode('utf-8')) add_request_log("GET", self.path, 200, "Served HTML diagnostics dashboard") else: self.send_response(404) self.end_headers() add_request_log("GET", self.path, 404, "Endpoint not found") def check_port_in_use(port=8000): s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) try: s.bind(('127.0.0.1', port)) s.close() return False except OSError: return True class GatewayGUI: def __init__(self, httpd, port): self.httpd = httpd self.port = port self.root = tk.Tk() self.root.title("Elimu Track - USB Biometric Gateway") self.root.geometry("420x460") self.root.resizable(False, False) self.root.configure(bg='#060a12') # Center the window screen_width = self.root.winfo_screenwidth() screen_height = self.root.winfo_screenheight() x = (screen_width - 420) // 2 y = (screen_height - 460) // 2 self.root.geometry(f"420x460+{x}+{y}") # Set Window Icon if os.path.exists("Logo.ico"): try: self.root.iconbitmap("Logo.ico") except Exception: pass # Main container main_frame = tk.Frame(self.root, bg='#060a12', padx=25, pady=25) main_frame.pack(fill=tk.BOTH, expand=True) # Header header_frame = tk.Frame(main_frame, bg='#060a12') header_frame.pack(fill=tk.X, pady=(0, 20)) title_label = tk.Label(header_frame, text="ELIMU TRACK", font=("Outfit", 20, "bold"), fg="#ffffff", bg='#060a12') title_label.pack(anchor=tk.W) subtitle_label = tk.Label(header_frame, text="USB Biometric Gateway Service", font=("Inter", 11), fg="#94a3b8", bg='#060a12') subtitle_label.pack(anchor=tk.W) # Status Card Panel status_card = tk.Frame(main_frame, bg='#0d1527', highlightthickness=1, highlightbackground="#1e293b", highlightcolor="#1e293b", bd=0, padx=15, pady=15) status_card.pack(fill=tk.X, pady=(0, 25)) # Grid layout for status items self.add_status_row(status_card, "Gateway Service:", "Active", "#10b981", 0) self.lbl_device_status = self.add_status_row(status_card, "Device Status:", "Checking...", "#94a3b8", 1) self.add_status_row(status_card, "Local Port:", f"{port}", "#3b82f6", 2) self.add_status_row(status_card, "Scanner Type:", "ZK9500 / SLK20R Reader", "#f8fafc", 3) self.add_status_row(status_card, "Host Endpoint:", f"http://127.0.0.1:{port}", "#94a3b8", 4) # Start connection check loop self.update_device_status() # Buttons btn_dash = tk.Button(main_frame, text="🌐 Open Diagnostics Dashboard", font=("Inter", 11, "bold"), fg="#ffffff", bg="#3b82f6", activeforeground="#ffffff", activebackground="#2563eb", bd=0, height=2, cursor="hand2", command=self.open_dashboard) btn_dash.pack(fill=tk.X, pady=(0, 12)) btn_shutdown = tk.Button(main_frame, text="🔌 Shutdown Gateway Service", font=("Inter", 11, "bold"), fg="#f87171", bg="#1f1418", activeforeground="#f87171", activebackground="#331a22", bd=0, height=2, cursor="hand2", command=self.confirm_shutdown) btn_shutdown.pack(fill=tk.X, pady=(0, 20)) # Footer / Tip tip_label = tk.Label(main_frame, text="💡 Tip: Minimize this window to keep the biometric service\nrunning in the background.", font=("Inter", 9), fg="#94a3b8", bg='#060a12', justify=tk.CENTER) tip_label.pack(side=tk.BOTTOM, fill=tk.X) self.root.protocol("WM_DELETE_WINDOW", self.confirm_shutdown) def add_status_row(self, parent, label_text, val_text, val_color, row): lbl = tk.Label(parent, text=label_text, font=("Inter", 10), fg="#94a3b8", bg='#0d1527') lbl.grid(row=row, column=0, sticky=tk.W, pady=5) val = tk.Label(parent, text=val_text, font=("Inter", 10, "bold"), fg=val_color, bg='#0d1527') val.grid(row=row, column=1, sticky=tk.E, pady=5) parent.columnconfigure(0, weight=1) parent.columnconfigure(1, weight=1) return val def update_device_status(self): global device_connected_status try: connected = is_scanner_connected() device_connected_status = connected self.set_device_status_ui(connected) except Exception: pass self.root.after(2000, self.update_device_status) def set_device_status_ui(self, connected): try: if connected: self.lbl_device_status.config(text="Connected", fg="#10b981") else: self.lbl_device_status.config(text="Disconnected", fg="#ef4444") except Exception: pass def open_dashboard(self): # Try to open in Chrome specifically, fallback to default browser url = f"http://scanner.elimutrack.com:{self.port}/" opened = False # Method 1: Try Python webbrowser get('chrome') try: chrome = webbrowser.get('chrome') chrome.open(url) opened = True except Exception: pass # Method 2: Try looking for common Chrome registry path / default installation paths on Windows if not opened: chrome_paths = [ r"C:\Program Files\Google\Chrome\Application\chrome.exe", r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe", os.path.expandvars(r"%LocalAppData%\Google\Chrome\Application\chrome.exe") ] for path in chrome_paths: if os.path.exists(path): try: import subprocess subprocess.Popen([path, url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) opened = True break except Exception: pass # Method 3: Fallback to default browser if not opened: try: webbrowser.open(url) except Exception as e: messagebox.showerror("Error", f"Failed to open browser: {e}") def confirm_shutdown(self): if messagebox.askyesno("Confirm Shutdown", "Are you sure you want to stop the Biometric Gateway Service?\nThis will disconnect your fingerprint scanner."): # Stop the HTTP server def stop_server(): try: self.httpd.shutdown() self.httpd.server_close() except Exception: pass os._exit(0) Thread(target=stop_server).start() self.root.destroy() def run(server_class=ThreadingHTTPServer, handler_class=ScannerHandler, port=8000): # 1. Check if port is already in use if check_port_in_use(port): # Initialize small Tkinter window just to show error messagebox root = tk.Tk() root.withdraw() # Hide main window messagebox.showerror( "Gateway Port In Use", f"The port {port} is already in use by another instance of the Elimu Track Scanner Gateway (or another application).\n\n" "Please check your system's task list and close any duplicate services before starting." ) sys.exit(1) # 2. Try starting loopback HTTP server server_address = ('127.0.0.1', port) try: httpd = server_class(server_address, handler_class) except Exception as e: root = tk.Tk() root.withdraw() messagebox.showerror( "Gateway Startup Error", f"Could not start Scanner Gateway Daemon:\n\n{e}" ) sys.exit(1) # 3. Spin up loopback server in daemon background thread server_thread = Thread(target=httpd.serve_forever, daemon=True) server_thread.start() # 4. Start the interactive desktop GUI control panel in the main thread gui = GatewayGUI(httpd, port) gui.root.mainloop() if __name__ == '__main__': try: run() except Exception as e: import traceback try: with open(r'C:\Users\PC\Desktop\scanner_crash.txt', 'a') as f: traceback.print_exc(file=f) f.flush() except Exception: pass sys.exit(1)