2. Project Overview - Kevin-Gu-2022/salus-lilac GitHub Wiki
The Smart Entry System is a secure and intelligent access control solution designed to enhance safety and convenience across a range of settings – including homes, offices, warehouses, and other secured environments. The system combines embedded sensor nodes, Bluetooth-based user authentication and sensor communication, and blockchain-backed event logging to create a tamper-resistant and verifiable method of entry.
Traditional access systems rely on physical keys or shared passcodes, which are prone to being lost, stolen, duplicated, or misused. They also typically lack a reliable and immutable record of access events. In increasingly connected environments, there is a growing demand for flexible, user-specific, and auditable access mechanisms.
This project introduces a keyless, sensor-driven entry system that detects and authenticates visitors in real time, and logs all interactions immutably on the blockchain. The base node stores a personalised configuration for each authorised user, including a unique Bluetooth MAC address, an alias, and individual passcode. This provides fine-grained control over who can enter, offering a more secure and flexible alternative to systems that rely on a single shared passcode – which can be easily leaked, reused without oversight, or exploited if not regularly updated. If access needs to be revoked, the base node can remove the user’s credentials immediately, ensuring that outdated or misused credentials no longer pose a security risk.
The base node is the central control unit of the system and is responsible for managing user access. It stores the configuration for each authorised user, including their unique Bluetooth MAC address, an alias, and passcode. The base node handles the authentication process by detecting the mobile device’s Bluetooth connection after a sensor event, and verifies the passcode associated with the device's unique MAC address. Only devices with a registered MAC address are allowed to attempt authentication. Once the connection is authorised, the base node verifies the passcode entered using the keypad, and grants or denies access accordingly. It also communicates with the sensors node (ultrasonic and magnetometer) also via Bluetooth to monitor visitor presence and detect tampering or unauthorised access attempts. Upon successful authentication, the base node triggers the servo motor to simulate door unlocking and logs all interactions immutably on the blockchain. The base node also has the ability to update or remove user credentials in real time, ensuring the system remains secure. 3 maximum password attempts have been set, and failure to provide the correct password will temporarily lock out the attempting user. User configuration, sensor thresholds and the blockchain will persist in the file system to prevent reconfiguration on start-up.
The mobile node is a portable device that interacts with the base node via Bluetooth for authentication. Upon successful Bluetooth connection, the mobile node provides visual feedback on the user's current passcode state, displaying the number of attempts remaining, the passcode digits as they are being entered and the success, incorrect or failed events. When the mobile node is not connected to the base node, the screen remains blank.
The sensors node contains an ultrasonic distance sensor and a magnetometer. This node is responsible for monitoring the environment around the entry point. The ultrasonic sensor detects the presence of visitors by measuring proximity, while the magnetometer monitors for signs of physical tampering of the door, such as forced entry or attempts to manipulate the system enclosure.
Sensor data is sent via Bluetooth, providing real-time data used to assess visitor presence and detect suspicious activity. When a visitor is detected, the sensor data triggers the base node to initiate the password entry process. In the case of tampering, an alert is raised, and both scenarios result in events being logged immutably to the local blockchain, creating a verifiable and tamper-resistant audit trail.
Due to technical issues, the camera node was not included for the final demonstration. However, the following description will outline its implementation if configured. The camera node captures images of visitors during interaction with the base node. Upon each access attempt - whether successful or failed - the base node sends a Bluetooth signal to the camera node to trigger image capture. These images are forwarded to the web dashboard to provide visual verification and strengthen the audit trail. The camera operates independently of user input, ensuring consistent event logging without requiring manual triggers.
The system includes a servo motor to provide physical feedback during access events. The servo motor controls the entrance opening mechanism, unlocking it upon successful authentication. Control signals are sent from the base node via PWM, ensuring coordinated and immediate response to access events.
The dashboard is the user interface that provides a comprehensive view of the system's status and event history. It displays the current blockchain in real time, logging all interactions including tampering, presence, success and failure. The door locked and unlocked states will also be displayed. This allows administrators to review immutable records of every event, and ensuring full transparency and providing a secure, auditable trail of all access activity.
- Purpose: Detects the presence of a person near the entry point by measuring echo time of ultrasonic waves.
- Data Type: Distance in centimeters (float)
-
Integration:
- Mounted above or beside the entrance door.
- Connected to the base node via two GPIO pins:
-
TRIG
: Sends a 10 µs pulse -
ECHO
: Measures time of return signal
-
- Sampling frequency: ~40 Hz
- Distance is computed as:
distance (cm) = (high level time×velocity of sound (340M/S) / 2
- Triggers authentication when the measured distance is below a configured threshold (e.g < 4m)
- Purpose: Detects abnormal changes in the magnetic field indicating enclosure tampering or magnetic interference.
- Data Type: 3-axis magnetic field vector (X, Y, Z) in microtesla (µT)
-
Integration:
- Onboard to the STMicroelectronics B-L475E-IOT01A Discovery Board
- Communicates over I2C with the STM32 microcontroller
- Accessed via Zephyr's sensor API
- Sampled periodically (e.g. 5–10 Hz)
- Threshold-based anomaly detection for:
- Enclosure tampering
- Magnetic lock manipulation
- Strong electromagnetic interference
- Purpose: Enables manual PIN or command input from users for authentication or menu navigation at the entry point.
- Data Type: Discrete button presses corresponding to digits 0–9 and A–F
-
Integration:
- Connected to the base node via 8 GPIO pins (4 rows, 4 columns)
- Uses a row-column matrix scanning method:
- Each row is driven low one at a time; columns are read to detect key presses
- Accessed via Zephyr's GPIO API
- C - Clear passcode
- D - Delete digit
- E - Enter passcode
- Key layout:
[1] [2] [3] [A] [4] [5] [6] [B] [7] [8] [9] [C] [0] [F] [E] [D]
- Purpose: Captures images for visual verification, auditing and traceability in response to any potential access-related event.
- Data Type: JPEG image (binary or base64-encoded)
-
Integration:
- Triggered by the base node under the following conditions:
- A visitor is detected by the ultrasonic sensor (proximity threshold met)
- An access attempt is in progress (authorised or unauthorised)
- An invalid passcode is entered
- A Bluetooth MAC mismatch or unauthorised user is detected
- A tampering event is inferred from the magnetometer sensor
- Publishes the captured JPEG image to the web dashboard
- Supports optional features:
- Timestamp overlays on images
- Basic image compression and filtering
- Facial detection or recognition (optional advanced extension)
- Logging image metadata (user ID, timestamp, event type) alongside blockchain entries
- Triggered by the base node under the following conditions:
In total, there will be 3 nodes communicating wirelessly through BLE. In all instances, the message format will be JSON.
A custom GATT service will be implemented between the base and mobile nodes, and base and sensors node upon connection. The service will have RX and TX characteristics, emulating a UART interface. Through this, JSON can be used to communicate bidirectionally.
-
Mobile Node: Communicates via BLE with the base node when it comes near. The magnetometer and ultrasonic sensors will trigger the base node to initiate a connection.
- Base Node → Mobile Node:
- Payload:
{"passcode": "-:----"}
- first digit represents the number of attempts, last 4 digits represent the current passcode
- Payload:
- Base Node → Mobile Node:
-
Sensors Node: Communicates via BLE with the base node when it comes near. The magnetometer and ultrasonic sensors will trigger the base node to initiate a connection.
- Sensors Node → Base Node:
- Magnetometer Payload:
{"x": "-.---", "y": "-.---", "z": "-.---"}
- Ultrasonic Payload:
{"dist": "-.---"}
- Magnetometer Payload:
- Base Node → Sensors Node:
- Payload:
{"base_time": <current_time>}
- Payload:
- Sensors Node → Base Node:
-
Web Dashboard: The base node will communicate using RTT to the PC, which will send event data via JSON in a
HTTP POST
request to the TagoIO dashboard.- Payload:
{"timestamp": <Timestamp>, "event": <EventType>, "mag_meas": <Magnetometer Data>, "ultra_meas": <Ultrasonic Data>, "user": <User Alias>, "mac": <MAC address>}
- Payload:
The following table summarises the approximate data transfer rates.
Link | Payload Size | Frequency | Data Rate (Est.) | Load |
---|---|---|---|---|
Sensor → BLE | ~50 bytes | Low | < 100 B/s | Very low |
Camera | 10–50 KB | Event-driven | ~4.2 KB/s (peak) | Moderate |
BLE UART | ~50–100 bytes | Per authentication | < 200 B/event | Very low |
UART → HTTP POST | ~10–50 KB | Per event | ~4–8 KB/s (peak) | Moderate |
These are all entirely achievable under the current wireless communication architecture.
The message protocol diagram below summarises the above information.
sequenceDiagram
participant Magnetometer as Magnetometer (B-L4S5I-IOT01A)
participant Ultrasonic as Ultrasonic Sensor (nRF52840 DK)
participant BaseNode as Base Node (nRF52840 DK)
participant ESP32CAM as Camera Node (ESP32-CAM)
participant MobileNode as Mobile Node (M5 Stack Core2)
participant PC
participant WebDashboard as Web Dashboard (TagoIO)
%% Sensor → BaseNode via BLE
Magnetometer->>+BLE: BLE GATT RX (UART-style) <br>{"status": "detected", "timestamp": ...}
Ultrasonic->>+BLE: BLE GATT TX (UART-style) <br>{"status": "detected", "timestamp": ...}
%% BaseNode → Camera via BLE _NOT IMPLEMENTED DUE TO TECHNICAL ISSUES_
BaseNode->>+BLE: BLE GATT TX (UART-style) <br>{"timestamp": ...}
Arducam->>+BLE: BLE GATT TX (UART-style)<br>{"timestamp": ..., "image": ...}
%% BLE Auth: Mobile ↔ BaseNode
MobileNode->>+BaseNode: BLE GATT RX (UART-style)<br>{"mac": ..., "passcode": ...}
BaseNode-->>-MobileNode: BLE GATT TX<br>{"status": "success|failure", "attempts_left": ...}
%% Dashboard Communication (wired UART + HTTP, for context)
BaseNode->>+PC: UART Transfer (JSON)
PC->>+WebDashboard: HTTP POST<br>{"timestamp": ..., "event": ..., "user": ..., "image": ...}
The blockchain module functions as a tamper-proof, append-only log for all critical security-related events in the Smart Entry System. It runs locally on the base node, maintaining cryptographic integrity of event data such as access attempts, sensor anomalies, and administrative changes. This ensures accountability and traceability for each significant system interaction.
Each block records essential metadata, including a timestamp, event type, user alias, Bluetooth MAC address, and cryptographic hashes. The prev_hash
links each block to the preceding one, while curr_hash
is derived from the block's contents using SHA-256. This design ensures that any tampering is immediately detectable.
Block Format (JSON):
{
"timestamp": "2025-05-15T18:05:12Z",
"event": "SUCCESS",
"mag_meas": "0.650",
"ultra_meas": "3.450",
"user": "Matt",
"MAC": "AA:BB:CC:DD:EE:FF",
"prev_hash": "c4518fa29df...",
"curr_hash": "d92a7d348b1..."
}
This structure is uniform across all event types and serves as the canonical format for every blockchain entry.
The base node autonomously determines which events are eligible for blockchain logging. These include:
- Passcode authentication results (success/failure)
- BLE MAC address authentication outcomes
- Tamper or movement events from the magnetometer
- Visitor proximity detection via the ultrasonic sensor
- Administrative operations such as adding or revoking users
When an event occurs, the system constructs a new block by filling in the relevant data fields. The block’s hash (curr_hash
) is computed from its contents excluding the hash field itself. This hash is then stored in the block and used as the prev_hash
for the next entry, maintaining chain continuity.
The blockchain is stored as an array of JSON objects on the base node's flash memory. The system performs periodic validation by traversing the chain and verifying that each prev_hash
corresponds to the curr_hash
of the preceding block. This ensures historical consistency and detects any unauthorized modifications.
Validation can be performed on system startup, at defined intervals, or manually from the admin dashboard. Logs and validation reports may also be exported for offline audits.
Blockchain entries are triggered by various subsystems. Each event is logged with sufficient metadata to correlate it with other components, such as sensor thresholds or user credentials.
Event Types:
-
"SUCCESS"
– BLE MAC and passcode matched successfully -
"FAIL"
– Failed authentication attempt -
"TAMPERING"
– Magnetometer values exceeded threshold -
"PRESENCE"
– Presence detected via ultrasonic sensor
These events are encoded in the event
field of the blockchain block, with associated metadata (e.g., MAC address, username) included for cross-referencing.
The blockchain is kept local to ensure fast write performance and eliminate dependency on external networks. SHA-256 is used for cryptographic hashing, providing resistance to collision and preimage attacks. To avoid excessive growth, block logs can be periodically archived or pruned based on configurable thresholds, while retaining integrity through root hash snapshots.
The use of blockchain in this context offers a lightweight yet robust mechanism to secure logs against tampering. It supports both real-time alerts and forensic analysis by ensuring that all critical interactions within the Smart Entry System are permanently recorded in a verifiable format.
A secure and intelligent entry system uses sensors, Bluetooth, passcode authentication and blockchain logging to manage access for authorised users like employees or residents. The system monitors presence, authenticates users, captures images, logs events and responds autonomously to ensure both security and traceability.
These are unprocessed values directly acquired from sensors, devices and user interactions.
- Bluetooth MAC addresses detected by the base node from the mobile node (authorised user)
- User configuration records on the base node: MAC address, alias, passcode, and access status
- Distance measurements from the ultrasonic sensor
- Magnetic field strength value from the magnetometer sensor
- Captured JPEG image bytes from the camera node (ESP32-CAM)
- Servo PWM values and lock/unlock direction
- Keystrokes (passcode digits) from the mobile node (M5Stack Core2 keypad interface)
- Bluetooth connection status flags (connected/disconnected) between base and mobile nodes
- Number of failed authentication attempts tracked
- Speaker activation data: tone ID and playback duration
- Raw blockchain transaction data (event hash, timestamp)
- Servo motor and speaker actuation signals
- Admin user records: user ID, registered MAC address and assigned role
Abstraction: Isolated facts with no inherent context — just raw input streams.
This is raw data that has been processed, labeled and timestamped to describe meaningful events and interactions within the system.
- “Visitor presence detected at 18:05:12” — triggered by ultrasonic sensor crossing proximity threshold
- “Bluetooth connection established with authorised device AA:BB:CC:DD:EE:FF” — confirmed MAC match from authorised list
- “Passcode entry failed: Attempt 2 of 3” — incorrect input received from mobile node keypad
- “Access granted: Servo motor activated to unlock door for user ‘Matt’ at 18:05:12” — verified MAC address + correct user passcode
- “Magnetometer anomaly detected at 18:05:15” — potential tampering (magnetic interference above threshold)
- “Blockchain log entry created: access=granted | user=Matt | time=18:05:12 | image_hash=abc123” — permanent and immutable log stored
- “Mobile node connected successfully over Bluetooth and began passcode transmission” — authenticated transport channel established
- “Admin user 'Matt' updated user list at 18:10:05” — configuration event logged to blockchain with timestamp
Abstraction: Data has been structured into discrete, meaningful events that the system can use for decision-making, traceability and real-time monitoring.
At this level, the system understands why things are happening, combining multiple pieces of information to derive operational logic.
- Correlating each detected Bluetooth MAC address with a stored user profile and assigned access permissions
- Recognising consecutive failed passcode attempts as a probable intrusion
- Identifying tampering from sustained magnetic field anomalies in the absence of any Bluetooth connection or passcode input
- Correlating ultrasonic presence detection + authorised Bluetooth connection + valid passcode input = valid access event
- Associating camera image hashes with specific access attempts for traceability
- Detecting anomalies: e.g. image capture without a matching MAC address or keypad input, suggesting unauthorised presence
- Linking speaker tone feedback to authentication outcomes to reinforce user interaction behavior
- Matching admin configuration changes (e.g. user list updates) with timestamps and logged blockchain transactions
Abstraction: Information is now interpreted with meaning, linked across time and components to generate operational insights.
This is the highest layer, where the system or administrator makes proactive, intelligent decisions based on interpreted knowledge, enabling adaptive behavior, policy enforcement and long-term system improvement.
- Automatically revoke or suspend access privileges for users exhibiting suspicious behavior, such as repeated failed authentications combined with tampering indicators
- Send immediate alert to admin dashboard with captured image and user/device data
- Dynamically enforce access windows by restricting entry to known usage patterns (e.g. authorised time-of-day ranges per user)
- Update blockchain with both event outcome and evidence (sensor values + images) for audit integrity
- Trigger system lockdown mode upon confirmed tampering (e.g. sustained magnetometer anomaly), blocking all access attempts until manually reset
- Recommend passcode reset policy based on historical credential exposure
- Use behavioral metrics to identify insider threats or misuse (e.g. valid access attempts outside normal time)
- Trigger extended image capture or re-capture when entry patterns deviate from normal authentication behavior
- Dynamically adjust sensor thresholds based on environmental feedback, time of day or sensor calibration drift
- Generate periodic system health and security summaries to notify administrators of anomalies or policy violations
Abstraction: Knowledge is now applied to automate decisions, enforce security policies, and adapt system behavior — adding real-world value.