{"id":22283088,"url":"https://github.com/bitcodr/esp8266-mqtt","last_synced_at":"2026-04-13T16:31:22.432Z","repository":{"id":124047973,"uuid":"289303281","full_name":"bitcodr/esp8266-mqtt","owner":"bitcodr","description":"A simple IoT project that controls an ESP8266's onboard LED via MQTT messages.","archived":false,"fork":false,"pushed_at":"2025-11-14T12:31:15.000Z","size":19,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-14T14:28:32.716Z","etag":null,"topics":["c","cpp","esp8266","esp8266-arduino","esp8266mqtt","mqtt","mqtt-broker"],"latest_commit_sha":null,"homepage":"","language":"C++","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/bitcodr.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":"2020-08-21T15:29:12.000Z","updated_at":"2025-11-14T12:34:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"4580f483-42dd-4d6e-aa6a-9e67735b8bd5","html_url":"https://github.com/bitcodr/esp8266-mqtt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bitcodr/esp8266-mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcodr%2Fesp8266-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcodr%2Fesp8266-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcodr%2Fesp8266-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcodr%2Fesp8266-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitcodr","download_url":"https://codeload.github.com/bitcodr/esp8266-mqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcodr%2Fesp8266-mqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31761724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: 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":["c","cpp","esp8266","esp8266-arduino","esp8266mqtt","mqtt","mqtt-broker"],"created_at":"2024-12-03T16:38:36.464Z","updated_at":"2026-04-13T16:31:22.425Z","avatar_url":"https://github.com/bitcodr.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP8266 MQTT LED Controller\n\nA simple IoT project that controls an ESP8266's onboard LED via MQTT messages. This project demonstrates how to connect an ESP8266 to WiFi, communicate with an MQTT broker, and control hardware based on received messages.\n\n## Features\n\n- WiFi connectivity with automatic reconnection\n- MQTT client with automatic broker reconnection\n- LED control via MQTT messages\n- Multiple command support (on, off, toggle, status)\n- Device status reporting (IP address, MAC address)\n- Serial debug output for monitoring\n\n## Hardware Requirements\n\n- ESP8266 board (ESP-12E or compatible)\n- USB cable for programming and power\n- Built-in LED (GPIO2)\n\n## Software Requirements\n\n- [PlatformIO](https://platformio.org/) or [Arduino IDE](https://www.arduino.cc/en/software)\n- PubSubClient library (automatically installed by PlatformIO)\n\n## Installation\n\n### Using PlatformIO (Recommended)\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/yourusername/esp8266-mqtt.git\n   cd esp8266-mqtt\n   ```\n\n2. Open the project in PlatformIO (VS Code with PlatformIO extension)\n\n3. Install dependencies:\n   ```bash\n   pio lib install\n   ```\n\n### Using Arduino IDE\n\n1. Install the Arduino IDE\n2. Install the ESP8266 board support:\n   - File → Preferences → Additional Board Manager URLs\n   - Add: `http://arduino.esp8266.com/stable/package_esp8266com_index.json`\n3. Install PubSubClient library:\n   - Sketch → Include Library → Manage Libraries\n   - Search for \"PubSubClient\" and install\n\n## Configuration\n\nBefore uploading the code, you need to configure your WiFi and MQTT settings in `src/main.cpp`:\n\n```cpp\n// WiFi Configuration\nconst char *ssid = \"YOUR_WIFI_SSID\";           // Replace with your WiFi name\nconst char *password = \"YOUR_WIFI_PASSWORD\";   // Replace with your WiFi password\n\n// MQTT Configuration\nconst char *serverHostname = \"broker.hivemq.com\";  // Replace with your MQTT broker\nconst unsigned int serverPort = 1883;               // MQTT port (default: 1883)\nconst char *topic = \"esp8266/led\";                  // MQTT topic for LED control\n```\n\n### Free MQTT Brokers for Testing\n\n- `broker.hivemq.com` (public, no authentication)\n- `test.mosquitto.org` (public, no authentication)\n- `broker.emqx.io` (public, no authentication)\n\nFor production use, consider setting up your own MQTT broker using [Mosquitto](https://mosquitto.org/) or [HiveMQ](https://www.hivemq.com/).\n\n## Building and Uploading\n\n### PlatformIO\n\n1. Connect your ESP8266 board via USB\n2. Build and upload:\n   ```bash\n   pio run --target upload\n   ```\n3. Monitor serial output:\n   ```bash\n   pio device monitor\n   ```\n\n### Arduino IDE\n\n1. Select your board: Tools → Board → ESP8266 Boards → Generic ESP8266 Module (or your specific board)\n2. Select the correct port: Tools → Port\n3. Click Upload button\n4. Open Serial Monitor (115200 baud)\n\n## Usage\n\n### MQTT Commands\n\nOnce the device is connected to WiFi and the MQTT broker, you can send the following commands to the configured topic:\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `on` or `1` | Turn LED on | `mosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"on\"` |\n| `off` or `0` | Turn LED off | `mosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"off\"` |\n| `toggle` | Toggle LED state | `mosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"toggle\"` |\n| `status` | Request device status | `mosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"status\"` |\n\n### Testing with Mosquitto Client\n\nInstall mosquitto-clients:\n```bash\n# Ubuntu/Debian\nsudo apt-get install mosquitto-clients\n\n# macOS\nbrew install mosquitto\n```\n\nSubscribe to the topic to see responses:\n```bash\nmosquitto_sub -h broker.hivemq.com -t esp8266/led\n```\n\nPublish commands (in another terminal):\n```bash\n# Turn LED on\nmosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"on\"\n\n# Turn LED off\nmosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"off\"\n\n# Toggle LED\nmosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"toggle\"\n\n# Get device status\nmosquitto_pub -h broker.hivemq.com -t esp8266/led -m \"status\"\n```\n\n### Testing with MQTT Explorer\n\n[MQTT Explorer](http://mqtt-explorer.com/) is a great GUI tool for testing MQTT communications:\n\n1. Download and install MQTT Explorer\n2. Connect to your broker (e.g., broker.hivemq.com)\n3. Navigate to your topic (e.g., esp8266/led)\n4. Publish messages and see responses in real-time\n\n## Serial Monitor Output\n\nThe device provides detailed debug information via serial output at 9600 baud:\n\n```\n========================================\nESP8266 MQTT LED Controller\n========================================\n\nConnecting to WiFi: YourWiFiName\n.....\nWiFi connected! IP address: 192.168.1.100\nMAC address: AA:BB:CC:DD:EE:FF\nMQTT connecting as client ESP8266-A3F2...\nMQTT connected successfully!\nSubscribed to topic: esp8266/led\nSetup complete!\nMessage received on topic 'esp8266/led': on\nLED turned ON\n```\n\n## Troubleshooting\n\n### WiFi Connection Issues\n\n- Verify SSID and password are correct\n- Check that your WiFi network is 2.4GHz (ESP8266 doesn't support 5GHz)\n- Ensure the ESP8266 is within range of your router\n\n### MQTT Connection Issues\n\n- Verify the MQTT broker hostname is correct\n- Check if the broker requires authentication (update code accordingly)\n- Test broker connectivity from your computer first\n- Some public brokers may be temporarily unavailable - try another one\n\n### LED Not Responding\n\n- Verify the correct GPIO pin is used (GPIO2 for most ESP8266 boards)\n- Check serial monitor to confirm messages are being received\n- Note that LED logic is inverted (LOW = ON, HIGH = OFF)\n\n### Serial Monitor Shows Garbage\n\n- Ensure baud rate is set to 9600\n- Some boards may show boot messages at different baud rates - this is normal\n\n## Project Structure\n\n```\nesp8266-mqtt/\n├── src/\n│   └── main.cpp          # Main application code\n├── include/              # Header files (if any)\n├── lib/                  # Custom libraries (if any)\n├── test/                 # Test files (if any)\n├── platformio.ini        # PlatformIO configuration\n├── Readme.md            # This file\n└── .gitignore           # Git ignore rules\n```\n\n## Code Overview\n\n### Main Components\n\n- **connectWifi()**: Establishes WiFi connection\n- **connectMQTT()**: Connects to MQTT broker and subscribes to topic\n- **callback()**: Handles incoming MQTT messages and controls LED\n- **setLedState()**: Controls the LED state\n- **setup()**: Initializes hardware and connections\n- **loop()**: Maintains MQTT connection and processes messages\n\n### Supported Commands\n\nThe callback function supports multiple commands with case-insensitive matching:\n- LED control: `on`, `off`, `1`, `0`, `toggle`\n- Status reporting: `status`\n- Error handling for unknown commands\n\n## Extending the Project\n\n### Add More Sensors/Actuators\n\n1. Define new GPIO pins in the configuration section\n2. Initialize them in `setup()`\n3. Add command handling in `callback()`\n\nExample - Add a temperature sensor:\n```cpp\n#include \u003cDHT.h\u003e\n\n#define DHTPIN 4\n#define DHTTYPE DHT11\n\nDHT dht(DHTPIN, DHTTYPE);\n\n// In callback function:\nelse if (msg == \"temperature\")\n{\n  float temp = dht.readTemperature();\n  String response = \"Temperature: \" + String(temp) + \"C\";\n  client.publish(topic, response.c_str());\n}\n```\n\n### Add Authentication\n\nIf your MQTT broker requires authentication, modify the `connectMQTT()` function:\n\n```cpp\nconst char* mqtt_user = \"your_username\";\nconst char* mqtt_password = \"your_password\";\n\n// In connectMQTT():\nif (client.connect(clientId.c_str(), mqtt_user, mqtt_password))\n{\n  // ... rest of the code\n}\n```\n\n### Use Separate Topics\n\nFor better organization, use separate topics for commands and status:\n\n```cpp\nconst char *command_topic = \"esp8266/led/command\";\nconst char *status_topic = \"esp8266/led/status\";\n\n// Subscribe to command topic\nclient.subscribe(command_topic);\n\n// Publish status to status topic\nclient.publish(status_topic, \"LED: ON\");\n```\n\n## Security Considerations\n\n- **Never commit WiFi passwords** to public repositories\n- Use environment variables or separate config files for credentials\n- Consider using MQTT over TLS (port 8883) for production\n- Implement authentication for your MQTT broker\n- Use unique, strong passwords\n- Consider using certificate-based authentication for production deployments\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is open source and available under the MIT License.\n\n## Resources\n\n- [ESP8266 Arduino Core Documentation](https://arduino-esp8266.readthedocs.io/)\n- [PubSubClient Library](https://pubsubclient.knolleary.net/)\n- [MQTT Protocol](https://mqtt.org/)\n- [PlatformIO Documentation](https://docs.platformio.org/)\n- [HiveMQ MQTT Essentials](https://www.hivemq.com/mqtt-essentials/)\n\n## Author\n\nAmir Roshanaei - [bitcodr](https://github.com/bitcodr)\n\n## Acknowledgments\n\n- Nick O'Leary for the PubSubClient library\n- ESP8266 Arduino core team\n- MQTT community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcodr%2Fesp8266-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcodr%2Fesp8266-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcodr%2Fesp8266-mqtt/lists"}