MaixFace

Author / Organization: LUNGMEN ELECTRONICS
Website: https://www.lung.men
License: GPL v3
© 2025 LUNGMEN ELECTRONICS

---

🧠 Overview

MaixFace is an AI-based face recognition access control system built on Maixduino.
It supports persistent face feature storage, remote face enrollment, automatic sleep/wake based on face presence, and HTTP event triggering for IoT automation (e.g., opening doors).

The project aims to provide a modular, open-source framework for embedded AI vision control systems. It is compatible with various microcontrollers and servers, including ESP32, PCs, and cloud endpoints.

This project is an improved version of Sipeed’s official face recognition program, with added features such as offline face data storage (requires an SD card). For the original project, please refer to MaixHub.

---

✨ Features

• Face recognition with feature data stored persistently (non-volatile memory)
• Remote face enrollment via network interface
• Auto screen off after 10 seconds of no face detected
• Instant wake-up when a face appears
• Sends HTTP data packets to a server upon recognition (to trigger actions like door opening)
• Configurable server endpoint and network parameters
• Extensible design — compatible with ESP32, PC servers, or other microcontrollers
• Built using MaixPy IDE / Python, with optional server-side code in Arduino (ESP32)

---

⚙️ Hardware & Software Requirements

• Hardware:

  • Maixduino (K210 AI chip)
  • Camera module (e.g., OV2640)
  • Optional ESP32 or other microcontroller for network/server communication
  • Optional display and SD card module

• Software:

  • MaixPy IDE
  • Python 3.x (for code editing or serial tools)
  • Arduino IDE (for ESP32 or other server-side MCU)
  • Optional local or remote HTTP server

---

🚀 Installation

1. Clone or download this repository:

   git clone https://github.com/LUNGMEN-GOV/MaixFace.git

2. Open MaixPy IDE, connect your Maixduino, and open the main script:

   • main.py — Main logic and initialization
   • face_storage.py — Face data handling
   • models/ — Pretrained AI models (Face Detection, Landmark, and Feature Extraction)

3. Upload all scripts and model files to your Maixduino board.

4. (Optional) Set up an ESP32 or PC server to receive HTTP trigger packets for access control or automation.The example program for the ESP32 server used for remote face enrollment has been uploaded(in the Example folder), so as to test whether remote face enrollment works properly, and you can integrate it with your existing server.

---

🧩 Usage

1. Run the program using MaixPy IDE:

   • Click the Run button to upload and execute main.py on the Maixduino.

2. Modify and customize configuration parameters inside the script:

   • Network settings (Wi-Fi SSID, password)
   • Server information (IP, port, endpoint)
   • Sleep timeout and wake sensitivity

3. Enroll faces remotely through the provided HTTP interface or press the BOOT button if you don't want to establish a web server.

4. Operation logic:

   • When a recognized face is detected → sends an HTTP request (e.g., to open a door).
   • When no face is detected for 10 seconds → display automatically turns off.
   • When a face reappears → system wakes up instantly.

5. Monitor logs in MaixPy IDE to verify detection and communication.

The Debugging Interface of MaixPy IDE, frameBuffer is more blurred than the actual image

---

🌐 HTTP Trigger Setup

You can use an ESP32, PC, or cloud server as your HTTP receiver.
Please note that if your server is not on the same LAN, you may need to configure intranet penetration / port forwarding for proper access.

MaixFace sends POST/GET requests containing JSON-formatted recognition data, for example:

{
  "face_id": "user_001",
  "timestamp": "2025-11-07T10:24:15",
  "event": "recognized"
}

The server can handle this request to trigger specific actions — such as unlocking a door, logging entry time, or sending a notification.

---

🔮 Future Features

• Save and replay camera data to SD card (video recording function)
• Web-based management interface for face enrollment and monitoring
• MQTT/REST API integration for advanced IoT workflows
• Cross-platform dashboard for remote system management

---

📜 License

This project is licensed under the GNU General Public License v3.0 (GPLv3).
You are free to use, modify, and distribute this software under the same license terms.
Please keep all attributions to LUNGMEN ELECTRONICS when redistributing or modifying this work.

---

📞 Contact

The above text is generated by AI and may contain inaccuracies.
If you have any questions, please contact us using the information below.

LUNGMEN ELECTRONICS
Website: https://www.lung.men
Email: [email protected]

© 2025 LUNGMEN ELECTRONICS