Enter - Smart Locker System

A cloud-connected smart locker/safe system built with Particle IoT devices that provides secure keypad-controlled access with remote management capabilities.

Early Protype Image

Overview

The Enter Smart Locker System is an IoT-based security solution designed for safes, lockers, and secure compartments. It features a 4x4 keypad interface, OLED display for user feedback, and magnetic lock control through a relay system. The device connects to the Particle Cloud for remote password management and usage tracking through a MySQL database backend, with a Retool web interface for comprehensive system administration.

Key Features

• Secure Access Control: 4-digit password protection with dual password system (master + user)
• Visual Feedback: 128x64 OLED display for user interaction and status messages
• Remote Management: Cloud-connected password changes via Particle Cloud functions
• Database Integration: MySQL backend for user management and access logging
• Web Interface: Retool-based frontend for comprehensive system administration
• Hardware Control: Relay shield controls magnetic locks for 5-second access periods
• Multi-Platform Support: Compatible with Particle Argon and Boron devices

Hardware Requirements

Core Components

• Particle Device: Argon (Wi-Fi) or Boron (Cellular) microcontroller
• Keypad: 4x4 matrix keypad (16 buttons: 0-9, A-D, *, #)
• Display: SSD1306 OLED Display (128x64 pixels, I2C interface)
• Relay Control: Particle Relay Shield
• Lock Mechanism: Magnetic lock (controlled via relay)

Pin Configuration

Keypad Matrix:
- Row Pins: D7, D6, D5, D4
- Column Pins: D3, D2, A4, A5

OLED Display:
- Reset Pin: D4
- I2C Address: 0x3C

Relay Signal:
- Control Pin: D8

Wiring Diagram

Particle Device
├── D7-D4 → Keypad Rows (1-4)
├── D3,D2,A4,A5 → Keypad Columns (1-4)
├── D4 → OLED Reset
├── SDA/SCL → OLED I2C
├── D8 → Signal Pin (optional)
└── Relay Shield → Magnetic Lock

Software Architecture

Firmware (src/Enter.ino)

• Password Management: Dual password system with cloud-updatable user passwords
• User Interface: Real-time keypad input with masked display (****)
• Access Control: 5-second relay activation upon successful authentication
• Cloud Integration: Particle function passwordchanger for remote updates

Backend System (backend/)

• Database Schema: User and Compartments tables for multi-unit management
• Real-time Updates: Event stream processing for lock status changes
• Password Synchronization: Automatic password updates to connected devices

Frontend Interface (Retool)

• Web-based Management: Retool application for remote system administration
• User Management: Add/remove users, assign compartments, and manage access
• Real-time Monitoring: View compartment status and access logs
• Password Management: Change device passcodes remotely
• Multi-Device Control: Manage multiple locker units from single interface

Installation & Setup

1. Hardware Assembly

1. Connect the Particle device to the Relay Shield
2. Wire the 4x4 keypad according to pin configuration
3. Connect the OLED display via I2C
4. Connect magnetic lock to relay output
5. Power the system with appropriate voltage for your magnetic lock

2. Firmware Installation

# Clone the repository
git clone <repository-url>
cd "Particle Project"

# Compile and flash to your device
particle compile argon --saveTo firmware.bin
particle flash <device-name> firmware.bin

# Or use Particle CLI
particle compile argon
particle flash <device-name>

3. Database Setup

# Navigate to backend directory
cd backend

# Install Node.js dependencies
npm install particle-api-js mysql2

# Configure your database credentials in config.js
# Update device ID and auth token

# Run the database setup
node mysql.js

4. Retool Frontend Setup

1. Create Retool Account: Sign up at retool.com
2. Database Connection: Connect Retool to your MySQL database
3. Import Application: Create queries and interfaces for:
   • User management (User table)
   • Compartment monitoring (Compartments table)
   • Password management via Particle Cloud API
   • Real-time status updates
4. API Integration: Configure Particle Cloud API calls for device control

5. Configuration

1. Update Device ID: Replace 'e00fce68bb2b299b4e8542bf' in backend/mysql.js with your device ID
2. Set Auth Token: Update the authToken in backend/config.js
3. Database Credentials: Configure MySQL connection details in config.js
4. Default Password: The default master password is "1728" (changeable in code)

Usage

Basic Operation

1. Power On: Device displays "Password:" prompt
2. Enter Code: Use keypad to input 4-digit password
3. Visual Feedback: Display shows asterisks (****) for each digit
4. Access Granted: Correct password unlocks for 5 seconds
5. Access Denied: Incorrect password shows "Incorrect" message

Remote Management

• Change Password: Use Particle Cloud function passwordchanger or Retool interface
• Monitor Access: Database logs all access attempts and lock status
• Web Dashboard: Retool interface provides real-time system overview
• User Administration: Add/remove users and manage compartment assignments
• Multi-Device: Backend supports multiple locker units with centralized control

Password System

• Master Password: Hard-coded backup access (default: "1728")
• User Password: Remotely changeable via cloud function
• Security: Both passwords provide full access to the system

API Reference

Particle Cloud Functions

// Change user password remotely
int passwordchanger(String newpasscode)

Database Schema

-- User management table
CREATE TABLE User (
    username VARCHAR(20),
    login_password VARCHAR(20), 
    device_passcode INT,
    slotId INT,
    in_use BOOL
);

-- Compartment status tracking
CREATE TABLE Compartments (
    device_passcode INT,
    slotId INT, 
    in_use BOOL
);

Dependencies

Particle Libraries

• Keypad_Particle (v1.0.0) - 4x4 keypad interface
• LiquidCrystal_I2C_Spark (v1.1.0) - I2C display support
• Adafruit_SSD1306 (v0.0.2) - OLED display driver
• Adafruit_GFX (v0.0.0) - Graphics library
• RelayShield (v0.0.6) - Relay control

Backend Dependencies

• particle-api-js - Particle Cloud API integration
• mysql2 - MySQL database connector
• node.js - Runtime environment

Frontend Dependencies

• Retool - Web-based application builder for admin interface
• MySQL Connection - Direct database connectivity for real-time data
• Particle Cloud API - Integration for device control and monitoring

Security Considerations

• Password Length: 4-digit passwords provide 10,000 combinations
• Master Override: Hard-coded master password for emergency access
• Access Logging: All attempts logged to database
• Physical Security: Relies on secure mounting of hardware components
• Network Security: Uses Particle Cloud's encrypted communication

Troubleshooting

Common Issues

1. Display Not Working: Check I2C connections and address (0x3C)
2. Keypad Unresponsive: Verify row/column pin connections
3. Relay Not Activating: Check relay shield power and connections
4. Cloud Connection Failed: Verify auth token and device ID
5. Database Errors: Check MySQL credentials and network connectivity

Debug Mode

Enable serial debugging by monitoring the serial output:

particle serial monitor

Development

Building from Source

# Install Particle CLI
npm install -g particle-cli

# Login to Particle account
particle login

# Compile for your target device
particle compile argon