{"id":29311599,"url":"https://github.com/anvaymayekar/iot-pager","last_synced_at":"2026-04-11T04:33:25.635Z","repository":{"id":303089994,"uuid":"1014374274","full_name":"anvaymayekar/iot-pager","owner":"anvaymayekar","description":"A rudimentary \u0026 secure MQTT-based pager system using ESP32 and Python. Messages sent from a Python CLI are received by ESP32 with OLED display, buzzer alert, and persistent flash storage. Powered by HiveMQ Cloud with TLS encryption and real-time status monitoring.","archived":false,"fork":false,"pushed_at":"2025-07-05T16:24:25.000Z","size":1178,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-05T16:53:05.969Z","etag":null,"topics":["arduino-ide","c","cloud","cpp","esp32","hivemq","mqtt","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anvaymayekar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-07-05T15:43:27.000Z","updated_at":"2025-07-05T16:24:28.000Z","dependencies_parsed_at":"2025-07-05T17:04:40.045Z","dependency_job_id":null,"html_url":"https://github.com/anvaymayekar/iot-pager","commit_stats":null,"previous_names":["anvaymayekar/iot-pager"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anvaymayekar/iot-pager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaymayekar%2Fiot-pager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaymayekar%2Fiot-pager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaymayekar%2Fiot-pager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaymayekar%2Fiot-pager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anvaymayekar","download_url":"https://codeload.github.com/anvaymayekar/iot-pager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaymayekar%2Fiot-pager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31669116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["arduino-ide","c","cloud","cpp","esp32","hivemq","mqtt","python"],"created_at":"2025-07-07T08:15:24.884Z","updated_at":"2026-04-11T04:33:25.627Z","avatar_url":"https://github.com/anvaymayekar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📟 IoT Pager: ESP32 \u0026 Python-Based Secure MQTT Pager\n\n\u003cbr\u003e\n\nA rudimentary ESP32-based pager system using **HiveMQ Cloud** for real-time message delivery. One ESP32 acts as a **subscriber**, receiving messages over MQTT and triggering a **buzzer + OLED notification**. A companion **Python script** acts as the **publisher**, enabling interactive message transmission with live feedback and heartbeat monitoring.\n\n\u003e 🔧 Developed during the **AICTE SAKEC IDEALAB Summer Intership Program 2025** as a side project, it demonstrates secure MQTT messaging, ESP32 flash memory usage, and robust cross-platform communication using TLS and state-aware embedded logic.\n\n---\n\n## 📌 Note\n\n\u003e ⚠️ Credentials shown here are **for demonstration only** — for production use, store sensitive data in a header/environment file.\n\u003e\n\u003e 💾 ESP32 uses `Preferences.h` (flash memory) to **persist the last received message**, even across reboots.\n\u003e\n\u003e 🔐 All MQTT traffic is sent via **TLS-secured MQTTS (port 8883)** using **HiveMQ Cloud**.\n\u003e\n\u003e ⚙️ The system includes built-in **WiFi checks**, **MQTT reconnection logic**, and **invalid message format handling** for reliability.\n\n---\n\n## 📦 Dependencies\n\n### ✅ ESP32 (Arduino) Libraries\n\nInstall via **Arduino Library Manager**:\n\n```\n- Adafruit SSD1306          → OLED driver\n- Adafruit GFX              → Graphics primitives\n- PubSubClient              → MQTT client\n- Preferences (built-in)    → ESP32 flash storage (NVS)\n- WiFi.h / WiFiClientSecure → TLS communication\n- Wire.h (built-in)         → I2C communication\n```\n\n\u003e 💾 **`Preferences.h`** is used to **save and restore the last message and timestamp** received. This ensures the pager **retains state** across resets or power cycles, maintaining the most recent context.\n\n---\n\n## 🧠 System Reliability \u0026 Safety\n\nThe project includes multiple built-in **fault tolerance mechanisms**:\n\n✅ **WiFi Auto-Reconnect**\n\n* The ESP32 continuously monitors WiFi status and attempts automatic reconnection.\n* If disconnected, the OLED shows `\"Wifi disconnected!\"` and retries silently.\n\n✅ **MQTT Broker Reconnection**\n\n* If the MQTT connection drops, the ESP32 tries reconnecting to HiveMQ in a loop.\n* It displays the current retry status on the OLED and Serial Monitor.\n\n✅ **Message Format Validation**\n\n* Incoming messages must be at least 21 characters (timestamp + message).\n* Invalid messages are **discarded safely** and logged as ignored.\n\n✅ **Heartbeat Mechanism**\n\n* ESP32 sends `status/esp32 = online` every 10 seconds (retained message).\n* Python script monitors this to detect if ESP32 goes offline.\n\n✅ **Flash Memory Restoration**\n\n* Upon boot, the ESP32 retrieves stored message and timestamp from NVS.\n* This avoids \"blank screens\" and keeps the user aware of the last message.\n\n✅ **Visual + Audible Alerts**\n\n* On message arrival, the **OLED displays content** and **buzzer beeps** for instant acknowledgment.\n\n---\n\n## 🛠️ Tools \u0026 Technologies\n\n![ESP32](https://img.shields.io/badge/ESP32-MCU-323232.svg?style=for-the-badge\\\u0026logo=espressif\\\u0026logoColor=white)\n![Arduino IDE](https://img.shields.io/badge/Arduino_IDE-Programming-00979D.svg?style=for-the-badge\\\u0026logo=arduino\\\u0026logoColor=white)\n![C++](https://img.shields.io/badge/C++-Firmware-00599C?style=for-the-badge\\\u0026logo=cplusplus\\\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-Scripting-3776AB.svg?style=for-the-badge\\\u0026logo=python\\\u0026logoColor=white)\n![MQTT](https://img.shields.io/badge/MQTT-Protocol-FF6600.svg?style=for-the-badge)\n![HiveMQ Cloud](https://img.shields.io/badge/HiveMQ_Cloud-Broker-FFCB05.svg?style=for-the-badge\\\u0026logo=hive\\\u0026logoColor=black)\n![Adafruit SSD1306](https://img.shields.io/badge/Adafruit_SSD1306-Display-blue?style=for-the-badge\\\u0026logo=adafruit\\\u0026logoColor=white)\n![PubSubClient](https://img.shields.io/badge/PubSubClient-MQTT_Lib-orange?style=for-the-badge)\n![WiFi](https://img.shields.io/badge/WiFi-Connectivity-29ABE2?style=for-the-badge\\\u0026logo=wifi\\\u0026logoColor=white)\n\n---\n\n## 📁 File Structure\n\n```\niot-pager/\n├── ESP32_MQTT_SUBSCRIBER/\n│   └── ESP32_MQTT_SUBSCRIBER.ino     // 🔻 Subscriber code for ESP32\n├── mqtt_publisher.py                 // 🖥️ Python MQTT Publisher Script\n├── images/                           // 🖼️ Output snippets\n└── README.md                         // 📘 This file\n```\n\n---\n\n## 🧠 System Overview\n\n### 🔻 ESP32 Subscriber Node\n\n* Connects to WiFi and subscribes to `telemetrix/stream` topic via HiveMQ Cloud\n* Displays incoming message on 128x64 OLED with timestamp\n* Triggers **buzzer (GPIO 4)** and **onboard LED (GPIO 2)** on new message\n* Persists last message using ESP32's internal flash via `Preferences`\n* Sends periodic heartbeat (`status/esp32`) to broker every 10 seconds\n\n---\n\n### 🖥️ Python Publisher\n\n* Publishes messages to the same MQTT topic with real-time timestamp\n* Monitors ESP32 heartbeat and prints warnings when offline\n* Beautifully logs all states (TX, Sync, Confirm, Lost, etc.) with ANSI colors\n* Interactive CLI — type your message and hit enter!\n* TLS-secured connection via port `8883` (MQTTS)\n\n---\n\n## ⚙️ Hardware Requirements\n\n🔌 **1× ESP32 Dev Board**\n\n🖥️ **1× OLED Display (128x64 I2C, SSD1306)**\n\n🔔 **1× Buzzer connected to GPIO 4**\n\n💡 **Internal LED (GPIO 2)**\n\n📶 **WiFi Access (2.4 GHz only)**\n\n---\n\n## 🧾 ESP32 Configuration\n\n| Component    | Pin Used                   |\n| ------------ | -------------------------- |\n| OLED (I2C)   | SDA: GPIO 21, SCL: GPIO 22 |\n| Buzzer       | GPIO 4                     |\n| Internal LED | GPIO 2                     |\n| Baud Rate    | 115200                     |\n\n---\n\n## ☁️ HiveMQ Cloud Setup\n\n1. 👉 Visit [HiveMQ Cloud Console](https://console.hivemq.cloud)\n2. 🆕 Create a **Free Cluster**\n3. 🔐 Go to **Access Management → Credentials** and generate:\n\n   * MQTT Username\n   * MQTT Password\n4. 🔄 Go to **Topics** and ensure `telemetrix/stream` and `status/esp32` are allowed\n5. 🔗 Use the following settings in your code:\n\n   * Broker: `your-cluster-url.hivemq.cloud`\n   * Port: `8883`\n   * TLS: ✅ Enabled (with `client.setInsecure()` on ESP)\n6. 🎯 Replace placeholders in `.ino` and `.py` with your actual credentials\n\n---\n\n## 🧪 Running the System\n\n### ESP32 (Subscriber)\n\n1. Open `ESP32_MQTT_SUBSCRIBER.ino` in Arduino IDE\n2. Install dependencies from Library Manager:\n\n   ```plaintext\n   - Adafruit SSD1306\n   - Adafruit GFX\n   - WiFi\n   - PubSubClient\n   ```\n3. Replace WiFi + MQTT credentials at the top\n4. Select **ESP32 Dev Module**, choose COM port, and upload\n5. Open Serial Monitor @ 115200 baud\n\n### Python (Publisher)\n\n\u003e Requires Python ≥ 3.7\n\n1. Install dependencies:\n\n   ```bash\n   pip install paho-mqtt\n   ```\n2. Run the script:\n\n   ```bash\n   python mqtt_publisher.py\n   ```\n3. Type any message and press Enter — ESP32 will buzz and show it on OLED.\n\n---\n\n### Terminal Logs (Python Publisher)\n\n```\n[SYNC] Connected to broker at c2d6...hivemq.cloud\n[READY] ESP32 interface ready — enter message or type 'exit' to terminate.\n\n\u003e\u003e Hello IoT!\n[TXLOG] [05 Jul 25 19:45:21] Message published successfully!\n[CNFRM] MQTT message acknowledged by broker.\n...\n```\n\n### Serial Monitor (ESP32)\n\n```\nConnected to Wifi!\nWiFi SSID\n192.168.1.67\n\n05 Jul 25 19:45:21\nHello IoT!\n```\n\n---\n\n## 🔐 Security Note\n\nCredentials shown are **test/demo** only.\nFor production deployments:\n\n* Store credentials in `secrets.h` or `.env` file\n* Avoid hardcoding sensitive keys in public repositories\n\n---\n\n## ⚖️ License\n\nThis project is licensed under the [MIT License](https://opensource.org/licenses/MIT).\nFeel free to modify and share with attribution.\n\n---\n\n## 👨‍💻 Author\n\n\u003e **Anvay Mayekar**\n\u003e 🎓B.Tech in Electronics \u0026 Computer Science — SAKEC\n\u003e\n\u003e[![GitHub](https://img.shields.io/badge/GitHub-181717.svg?style=for-the-badge\\\u0026logo=GitHub\\\u0026logoColor=white)](https://github.com/anvaymayekar)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2.svg?style=for-the-badge\\\u0026logo=LinkedIn\\\u0026logoColor=white)](https://linkedin.com/in/anvaymayekar)\n[![Instagram](https://img.shields.io/badge/Instagram-%23E4405F.svg?style=for-the-badge\\\u0026logo=Instagram\\\u0026logoColor=white)](https://instagram.com/anvaymayekar)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanvaymayekar%2Fiot-pager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanvaymayekar%2Fiot-pager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanvaymayekar%2Fiot-pager/lists"}