{"id":34903968,"url":"https://github.com/andersontrkz/safety-iot","last_synced_at":"2026-04-07T22:31:03.381Z","repository":{"id":329326851,"uuid":"1119101856","full_name":"andersontrkz/safety-iot","owner":"andersontrkz","description":"Safely is a IoT smart safe system that integrates an ESP32 with an Android application, communicating through MQTT protocol.","archived":false,"fork":false,"pushed_at":"2025-12-19T20:43:01.000Z","size":12053,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-29T15:33:56.437Z","etag":null,"topics":["android","c","cpp","esp32","jetpack-compose","mqtt","platformio","wokwi"],"latest_commit_sha":null,"homepage":"https://wokwi.com/projects/450795723160817665","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andersontrkz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-18T18:40:55.000Z","updated_at":"2025-12-19T20:56:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andersontrkz/safety-iot","commit_stats":null,"previous_names":["andersontrkz/safety-iot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/andersontrkz/safety-iot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersontrkz%2Fsafety-iot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersontrkz%2Fsafety-iot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersontrkz%2Fsafety-iot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersontrkz%2Fsafety-iot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andersontrkz","download_url":"https://codeload.github.com/andersontrkz/safety-iot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersontrkz%2Fsafety-iot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31532139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","c","cpp","esp32","jetpack-compose","mqtt","platformio","wokwi"],"created_at":"2025-12-26T09:38:31.108Z","updated_at":"2026-04-07T22:31:03.369Z","avatar_url":"https://github.com/andersontrkz.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Safety IoT - Smart Safe System\n\nSafely is a complete IoT smart safe system that integrates an ESP32 (simulated using Wokwi or PlatformIO) with an Android application, communicating through MQTT for real-time monitoring and status synchronization.\n\n\n## Table of Contents\n- [Overview](#overview)\n- [System Architecture](#system-architecture)\n- [Repository Structure](#repository-structure)\n- [Getting Started](#getting-started)\n  - [ESP32 Firmware](#firmware-esp32)\n  - [Android App](#app-android)\n- [Hardware Components](#hardware-components)\n- [Features](#features)\n- [Functional Flows](#functional-flows)\n  - [Firmware (ESP32)](#esp32-firmware)\n  - [App (Android)](#android-app)\n- [Communication Protocol](#communication)\n- [Security Considerations](#security)\n- [Technologies](#technologies)\n- [Development Workflow](#development-workflow)\n- [Troubleshooting](#troubleshooting)\n- [Future Improvements](#future-improvements)\n- [License](#license)\n\n---\n\n## Overview\n\n**Safety IoT** is a secure smart safe system integrating:\n\n- **ESP32-based IoT device firmware** (PlatformIO/Wokwi)\n- **Android mobile app** (Jetpack Compose)\n\nThe system allows **real-time monitoring**, secure local access with code entry, and simulation using Wokwi.\n\n---\n\n## System Architecture\n\n```bash\n+------------+              +-----------+\n|            |              |           |\n|   ESP32    |     MQTT     |  ANDROID  |\n|  FIRMWARE  | \u003c----------\u003e |    APP    |\n|            |              |           |\n+------------+              +-----------+\n```\n\n\n**Components**:\n\n- **ESP32 Firmware**: C++ | PlatformIO | Wokwi\n- **Android App**: Kotlin | Jetpack Compose | Paho MQTT\n- **MQTT Broker**: Public HiveMQ broker for messaging\n\n---\n\n\n## Repository Structure\n````\nsafety/\n│\n├── mobile/\n│ └── android/ ← Android app submodule\n│\n├── firmware/\n│ └── esp32/ ← ESP32 firmware submodule\n│\n├── .gitmodules ← Git submodules configuration\n└── README.md\n````\n\n\u003e Uses **Git Submodules** for modular separation of Android app and ESP32 firmware.\n\n-----\n\n\n## Getting Started\n\n### Remote\n\n#### Firmware ESP32\n\n1. Open the [project simulation link](https://wokwi.com/projects/450795723160817665) in Wokwi.\n\n2. Run simulation in Wokwi.\n\n![Wokwi Simulation](./docs/assets/11-wokwi-simulation.gif)\n\n3. Configure WiFi config if needed.\n\n4. Configure MQTT config if needed.\n\n5. Monitor serial logs for system feedback.\n\n\n### Local\n\nClone repository including submodules:\n\n```bash\ngit clone --recurse-submodules git@github.com:andersontrkz/safety.git\ncd safety\n```\n\n#### Firmware ESP32\n\n        1. Open firmware/esp32 in VS Code.\n\n        2. Use PlatformIO and Wokwi tools.\n\n        3. Build \u0026 upload to ESP32.\n\n        4. Configure WiFi config if needed.\n\n        5. Configure MQTT config if needed.\n\n        6. Monitor serial logs for system feedback.\n\n\n#### App Android\n\n        7. Open mobile/android in Android Studio.\n\n        8. Build and run on emulator or physical device.\n\n        9. Configure MQTT config if needed.\n\n        10. The app automatically connects to the MQTT broker and displays safe status.\n\n\n## Hardware Components\n\n```bash\n+----------+         +---------------+\n|  Keypad  | ------\u003e |               |\n+----------+         |               |\n+----------+         |               |\n|   LCD    | \u003c------ |               |\n+----------+         |               |\n+----------+         |               |\n|   Servo  | \u003c------ |     ESP32     |\n+----------+         |               |\n+----------+         |               |\n|   LEDs   | \u003c------ |               |\n+----------+         |               |\n+----------+         |               |\n|  Buzzer  | \u003c------ |               |\n+----------+         +---------------+\n\n```\n\n|     Component     |        Pin        |\n| ----------------- | ----------------- |\n| Keypad (R1..R4)   | 13 - 12 - 14 - 27 |\n| Keypad (C1..C4)   | 26 - 25 - 33 - 32 |\n| LCD (I2C)         | 22 - 21           |\n| Servo Motor       | 18                |\n| LED (RED)         | 4                 |\n| LED (GREEN)       | 16                |\n| Buzzer            | 17                |\n| ESP32             | MCU               |\n\n\n## Features\n\n### ESP32 Firmware\n- Keypad input handling for code entry\n- Servo-controlled lock mechanism\n- LED \u0026 buzzer hardware feedback\n- LCD messages for user interaction\n- Code setup and verification logic\n- Supports mute/unmute and lock actions\n- WiFi connectivity management\n- MQTT messaging (`safer/status`)\n\n### Android App\n- Displays safe status (locked/unlocked)\n- Shows last access events\n- Built with Jetpack Compose\n- Real-time updates via MQTT (`safer/status`)\n\n\n## Functional Flows\n\n### ESP32 Flows\n\nAll flows below were recorded from the ESP32 simulation, sending events via MQTT.\n\n#### System Startup\n\n![System Startup](./docs/assets/01-esp32-start.gif)\n*ESP32 boot sequence with LCD animation, buzzer and LEDs feedback, and system initialization.*\n\n#### Set Security Code\n\n![Set Security Code](./docs/assets/02-esp32-set-code.gif)\n*User defines a new 4-digit code using the keypad and confirms it.*\n\n#### Unlock Safe\n\n![Unlock Safe](./docs/assets/03-esp32-unlock-safe.gif)\n*Correct code entered → safe unlocks, servo opens, status published via MQTT.*\n\n#### Lock Safe\n\n![Lock Safe](./docs/assets/04-esp32-lock-safe.gif)\n*Safe is locked again locally and status is updated remotely.*\n\n#### Mute / Unmute Buzzer\n\n![Mute / Unmute Buzzer](./docs/assets/05-esp32-mute-unmute.gif)\n*User toggles sound alerts while the keypad is used.*\n\n#### Reset Code\n\n![Reset Code](./docs/assets/06-esp32-reset-code.gif)\n*Existing code is cleared and the system returns to setup mode.*\n\n#### Access Denied\n\n![Access Denied](./docs/assets/07-esp32-access-denied.gif)\n*Incorrect code entered → error feedback via LCD, LEDs, and buzzer.*\n\n#### Code Mismatch\n\n![Code Mismatch](./docs/assets/08-esp32-code-mismatch.gif)\n*Code confirmation fails → configuration rejected.*\n\n\n### Android Flows\n\nAll flows below were recorded from the Android simulation, receiving events via MQTT.\n\n|                            Safe Locked                            |                             Safe Unlocked                             |\n|-------------------------------------------------------------------|-----------------------------------------------------------------------|\n|     ![Safe Unlocked](./docs/assets/10-android-lock-status.gif)    |      ![Safe Unlocked](./docs/assets/09-android-unlock-status.gif)     |\n| *Android app shows **`LOCKED`** status until it receives **`UNLOCKED`** status and then logs the event to history.* | *Android app receives status updates and toggles between **`UNLOCKED`**  ↔ **`LOCKED`**, logging all events.* |\n\n\n## Communication\n\n- MQTT Topic: ``safer/status``\n- Payload: ``LOCKED`` or ``UNLOCKED``\n\n*App subscribes to this topic in real-time.*\n\n\n## Security\n\n- Safe code\n    - Storage class in-memory\n    - Fixed 4-digit code\n\n\n## Technologies\n\nThis project combines embedded systems, IoT communication, and modern Android development, using industry-relevant tools and frameworks.\n\n### ESP32\n\nThe ESP32 is low-power microcontroller with integrated Wi-Fi and Bluetooth, widely used in IoT applications.\n\n[📚 Official ESP32 Documentation](https://www.espressif.com/en/products/socs/esp32)\n\n\n### Wokwi\n\nWokwi is an online microcontroller simulator that allows realistic simulation of ESP32 projects without physical hardware.\n\n[📚 Official Wokwi Documentation](https://docs.wokwi.com/)\n\n\n### PlatformIO\n\nPlatformIO is a professional embedded development ecosystem built on top of VS Code.\n\n[📚 Official PlatformIO Documentation](https://docs.platformio.org/)\n\n\n### MQTT\n\nMQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for IoT systems.\n\n[📚 Official MQTT Documentation](https://mqtt.org/)\n\n\n### HiveMQ\n\nHiveMQ is a public broker that provides a reliable public MQTT broker suitable for testing and learning.\n\n[📚 Official HiveMQ Documentation](https://www.hivemq.com/public-mqtt-broker/)\n\n\n### Android\n\nThe Android application acts as a remote monitoring interface for the smart safe.\n\n[📚 Official Android Documentation](https://developer.android.com/)\n\n\n### Jetpack Compose\n\nJetpack Compose is Android’s modern, declarative UI toolkit.\n\n[📚 Official Jetpack Compose Documentation](https://developer.android.com/jetpack/compose)\n\n\n## Development Workflow\n\n### ESP32 Firmware changes:\n\n#### ESP32 changes:\n```bash\ngit add .\ngit commit -m \"Feature XYZ\"\ngit push origin feature/xyz\n```\n\n#### Update ESP32 submodule in main repo:\n```bash\ncd ../../\ngit add firmware/esp32\n\ngit commit -m \"feat(esp32): update module\"\ngit push\n```\n\n\n### Android app changes:\n\n#### Android changes:\n```bash\ncd mobile/android\n\ngit commit -m \"feat(android): update module\"\ngit push\n```\n\n#### Update Android submodule in main repo:\n```bash\ncd ../../\ngit add mobile/android\n\ngit commit -m \"feat(android): update module\"\ngit push\n```\n\n\n## Troubleshooting\n\n- WiFi issues\n    - Check WiFiConfig.h \n    - Check serial monitor\n\n- MQTT connection failed\n    - Check verify broker \n    - Check network\n\n- LCD not displaying\n    - Check verify broker \n    - Check network\n\n- LCD not displaying:\n    - Check SDA pin\n    - Check SCL pin\n\n- Keypad unresponsive:\n    - Check keypad setup\n\n\n## Future Improvements\n\n- Encrypted MQTT communication (TLS)\n\n- App-based unlock with OTP authentication\n\n- Multi-user access logging\n\n- Low-power / battery monitoring\n\n- Safe availability feedback\n\n- ROM-based memory implementation\n\n\n## License\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersontrkz%2Fsafety-iot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandersontrkz%2Fsafety-iot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersontrkz%2Fsafety-iot/lists"}