# tom1030507/ncu_iot_roboticpetdog architecture

> Architecture diagram of the GitHub repository tom1030507/ncu_iot_roboticpetdog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tom1030507/ncu_iot_roboticpetdog
- Repository: https://github.com/tom1030507/ncu_iot_roboticpetdog

## Overview

##### Project Type and Purpose
- This is an embedded IoT/robotics project built around an ESP32 microcontroller.
- Purpose: a pet-dog simulator that authenticates an owner via RFID, tracks a BLE-enabled ball, reads environmental data, and displays “moods” on an OLED.

##### File Structure
- Single source file: robotic_pet_dog.ino – all application logic resides here.
- No separate “frontend”/“backend”: it’s a monolithic embedded application.
- The README details hardware modules and Arduino libraries, indicating tight hardware-software coupling.

##### Main Components
a. ESP32 Microcontroller (central processing unit)
b. Peripherals wired to ESP32:
- MFRC522 RFID Reader (owner authentication)
- DHT22 Temperature/Humidity Sensor (environmental sensing)
- Seeed OLED Display (UI / mood/chat display)
- Motor Driver Circuit + DC Motors (movement / fetch behavior)
c. External BLE Beacon (inside the ball)
d. Owner’s RFID Card (external input token)
e. Power Supply (battery or USB)
f. Arduino Runtime / Task Loop (software layer)

##### Relationships & Interactions
- RFID Reader ←→ ESP32: SPI interface for UID reads; toggles active/inactive state.
- DHT22 ←→ ESP32: single-wire digital sensor input; periodic reads update mood logic.
- OLED ←→ ESP32: I²C/SPI bus; displays status, temperature, humidity, and chat messages.
- Motor Driver ←→ ESP32: GPIO/PWM outputs control speed/direction based on BLE RSSI feedback.
- ESP32 ↔ BLE Beacon: Bluetooth Low Energy scanning; RSSI measurement guides locomotion.
- User’s RFID Card → RFID Reader: proximity triggers authentication event.
- Power → All hardware modules.

##### Architectural Patterns / Design Principles
- Event-Driven Loop: The Arduino `loop()` polls sensors, checks RFID/ BLE events, updates actuators/display.
- Reactive Behavior: State machine driving “Idle,” “Active,” “Finding Ball,” “Found Ball” modes.
- Layered Abstraction:
- Hardware Abstraction (libraries: MFRC522, DHT, SeeedOLED, BLEDevice)
- Application Logic (state machine, decision rules)
- Presentation (OLED messages)

##### Elements to Include for Clarity
- Blue for sensing (DHT22, RFID)
- Green for actuation (Motor Driver, Motors)
- Orange for UI (OLED)
- Purple for wireless comms (BLE Beacon)
- Rounded rectangles for modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    RFIDCard["Owner's RFID Card"]:::external
    BLEBeacon["BLE Beacon (in Ball)"]:::wireless
    Power["Power Supply"]:::power

    %% ESP32 Central Unit
    subgraph "ESP32 Microcontroller"
        direction TB
        RFIDMod["RFID Authentication Module\nMFRC522 RFID – SPI"]:::sensing
        BLEMod["BLE Scanner / Fetch Logic\nBLEDevice"]:::wireless
        SensorMod["Sensor Reader\nDHT22 Temp/Humidity"]:::sensing
        DisplayMod["Display Manager\nSeeed OLED – I2C/SPI"]:::ui
        MotorMod["Motor Controller\nMotor Driver GPIO/PWM"]:::actuation
        Runtime["Arduino Runtime\nsetup()/loop()"]:::core
    end

    %% Data & Power Flows
    RFIDCard -->|"1: UID via SPI"| RFIDMod
    RFIDMod -->|"Auth event"| Runtime
    BLEBeacon <-->|"BLE scan & RSSI"| BLEMod
    BLEMod -->|"RSSI feedback"| Runtime
    Runtime -->|"read every 2s"| SensorMod
    SensorMod -->|"temp/humidity data"| Runtime
    Runtime -->|"update display"| DisplayMod
    Runtime -->|"control motors"| MotorMod
    Power -.-> RFIDMod
    Power -.-> BLEMod
    Power -.-> SensorMod
    Power -.-> DisplayMod
    Power -.-> MotorMod
    Power -.-> Runtime

    %% Click Events
    click RFIDMod "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click BLEMod "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click SensorMod "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click DisplayMod "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click MotorMod "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click Runtime "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click RFIDCard "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click BLEBeacon "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click Runtime "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/robotic_pet_dog.ino"
    click README.md "https://github.com/tom1030507/ncu_iot_roboticpetdog/blob/main/README.md"
    click LICENSE "https://github.com/tom1030507/ncu_iot_roboticpetdog/tree/main/LICENSE"

    %% Styles
    classDef sensing fill:#cce5ff,stroke:#3399ff,color:#004085
    classDef actuation fill:#d4edda,stroke:#28a745,color:#155724
    classDef ui fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef wireless fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef core fill:#f8f9fa,stroke:#6c757d,color:#212529
    classDef external fill:#f0f0f0,stroke:#666666,color:#333333
    classDef power fill:#ffe6e6,stroke:#ff6666,color:#990000
```
