2. Project Overview - Kevin-Gu-2022/salus-lilac GitHub Wiki

Project Overview

Project Description

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.

System Overview

Base Node (B-L475E-IOT01A)

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.

Mobile Node (M5 Stack Core2)

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.

Sensor Node: Ultrasonic and Magnetometer (B-L4S5I-IOT01A Discovery Kit)

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.

Camera Node (nRF52840 DK with Arducam) - NOT IMPLEMENTED DUE TO TECHNICAL ISSUES

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.

Actuator: Servo Motor

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.

Web Dashboard (TagoIO)

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.

Hardware Architecture Block Diagram

image

Software Flow Charts

Base Node Event Detection/Classification

image

PC Dashboard Message

image

Sensor Integration

1. Ultrasonic Distance Sensor (HC-SR04)

  • 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)

2. Magnetometer Sensor (LIS3MDL on B-L475E-IOT01A)

  • 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

3. PMOD Keypad (Digilent 4x4 Matrix Keypad)

  • 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]
      

4. Camera Node (nRF52840 DK with Arducam) - NOT IMPLEMENTED DUE TO TECHNICAL ISSUES

  • 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

Wireless Network Communications

In total, there will be 3 nodes communicating wirelessly through BLE. In all instances, the message format will be JSON.

Bluetooth Low Energy

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

  • 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": "-.---"}
    • Base Node → Sensors Node:
      • Payload: {"base_time": <current_time>}

HTTP

  • 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>}

Data Transfer

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": ...}
Loading

Algorithm Schemes

Blockchain Integration in Smart Entry System

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.

1. Blockchain Structure

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.

2. Event Logging Workflow

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.

3. Blockchain Persistence and Validation

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.

4. Event Types and Integration Points

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.

5. Security and Performance Considerations

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.

DIKW Pyramid Abstraction

DIKW Hierarchy

Scenario: Smart Entry System in Home/Office/Warehouse

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.

1. DATA – Raw signals collected from the system

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.

2. INFORMATION – Structured data with contextual meaning

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.

3. KNOWLEDGE – Interpreted patterns and causal relationships

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.

4. WISDOM – Strategic response, decision-making and system autonomy

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.

⚠️ **GitHub.com Fallback** ⚠️