Asus ProArt P16 Face Lock Utility for Arch Linux

This project provides an automated tool to configure and manage facial recognition unlock (Windows Hello-style face lock) on Arch Linux, specifically optimized for the Asus ProArt P16 (H7606WV) laptop.

It automates the installation of the modernized C++ and OpenCV-based face unlock framework (howdy-next), dynamically configures the system to use the correct persistent hardware path of the Asus IR camera, downloads the necessary ONNX models, and manages Pluggable Authentication Modules (PAM) safely.

Features

1. Automated Dependency Check and Installation: Detects and installs howdy-next from the Arch User Repository (AUR) using yay.
2. Dynamic IR Camera Discovery: Scans sysfs to identify the ASUS IR camera device, resolving it to a persistent device path under /dev/v4l/by-path to avoid interface index swaps across reboots.
3. Optimal Hardware Tuning: Configures Howdy to match the ProArt P16 IR camera sensor capabilities (grayscale, 640x400 resolution, custom frame rates, and settings).
4. Safe PAM Authentication Injection: Injects PAM lines selectively into targets like sudo, sddm (display manager), and hyprlock (screen locker) instead of modifying global modules like system-auth.
5. Configuration Safeguards: Creates backups of all edited PAM files with a rollback command to restore system state in case of issues.
6. Diagnostic Tools: Wraps CLI testing commands to preview the camera feed and diagnose hardware states.

Architecture and Asus ProArt P16 Hardware Quirk

The Asus ProArt P16 contains an FHD infrared (IR) camera alongside the main RGB camera. Under Linux, this device is listed as:

• Name: ASUS FHD webcam: ASUS IR camera
• Pixel Format: Grayscale (GREY / Y800)
• Supported Resolutions: 640x400 at 15 FPS

Proximity Sensor Behavior

A common challenge on Asus ProArt and Vivobook laptops is that the IR LED emitter is gated by a hardware-based proximity/motion sensor for power-saving purposes. The IR LED will only pulse or activate when it detects motion or presence close to the display. If the camera captures a black or static frame, move your head slightly or wave your hand in front of the screen to activate the emitter.

Requirements

• Arch Linux
• An AUR helper (yay must be installed)
• Python 3

Installation and Usage

To run the manager, clone this repository and run the proart-face-lock script. The utility will automatically elevate itself to root privileges via sudo where necessary.

1. Install Face Lock

Run the install command to install dependencies, identify the camera, download models, and configure hardware settings:

python3 proart-face-lock install

2. Add Face Model

Enroll a face model for a specific user:

python3 proart-face-lock add <username>

3. Test Authentication

Test that the camera captures frames and is able to recognize your face:

python3 proart-face-lock test

4. Enable PAM Authentication

Enable face lock for specific modules. You can select one or more targets:

python3 proart-face-lock enable-pam <service>

Supported services: sudo, sddm, hyprlock, gdm-password, lightdm, ly, swaylock, xscreensaver, i3lock, kde, system-local-login, login, polkit-1. For example, to enable it for sudo and screen locking:

python3 proart-face-lock enable-pam sudo hyprlock

5. Check Status

Verify the status of the system integration, camera configuration, and enrolled models:

python3 proart-face-lock status

6. Disable PAM Authentication

Temporarily or permanently disable PAM integrations without uninstalling the package:

python3 proart-face-lock disable-pam <service>

7. Uninstall

Revert all PAM modifications, delete face models, and restore the original configurations:

python3 proart-face-lock uninstall

CLI Reference

Usage: proart-face-lock <command> [arguments]

Commands:
  install                 Install dependencies, set up camera configs, download models.
  uninstall               Safely restore PAM files, remove models, and clean up.
  status                  Show current status of camera, package, models, and PAM files.
  test                    Run a camera test stream to verify facial detection.
  add <user>              Enroll a new face model for the specified user.
  list <user>             List all enrolled face models for the specified user.
  remove <user> <id>      Remove a specific face model by its ID.
  enable-pam <services>   Inject face lock into PAM files (e.g., sudo, sddm, gdm-password).
  disable-pam <services>  Remove face lock from PAM files.
                          Supported: sudo, sddm, hyprlock, gdm-password, lightdm, ly,
                          swaylock, xscreensaver, i3lock, kde, system-local-login, login, polkit-1

Troubleshooting

Camera output is completely black or times out

1. Ensure the camera switch (if your laptop has a physical shutter or privacy switch) is open.
2. The Asus IR camera requires presence/motion to trigger the IR light. Make sure you are sitting directly in front of the camera and move your head slightly.
3. Verify that the correct camera path is configured in /etc/howdy/config.ini. Run python3 proart-face-lock status to check the current device path.

Locked out of authentication

If a PAM configuration error occurs and you are locked out, you can restore all modified PAM configurations by using your active root session to run the rollback script:

python3 proart-face-lock uninstall

Or manually restore the backup files created under /etc/pam.d/*.bak.

Bad or Incorrect Face Scan

If you captured a bad face scan (for example, you were not looking at the screen), you can list and remove the incorrect model before scanning again:

1. List your current enrolled face models to find the ID:

python3 proart-face-lock list <username>

2. Remove the incorrect model using its ID (e.g., 0):

python3 proart-face-lock remove <username> <id>

3. Look directly at the screen and scan your face again:

python3 proart-face-lock add <username>

License

This project is licensed under the MIT License. See the LICENSE file for details.