{"id":15287639,"url":"https://github.com/plapointe6/espmqttclient","last_synced_at":"2025-04-04T07:07:15.407Z","repository":{"id":40660050,"uuid":"159059828","full_name":"plapointe6/EspMQTTClient","owner":"plapointe6","description":"Wifi and MQTT handling for ESP8266 and ESP32","archived":false,"fork":false,"pushed_at":"2024-07-07T18:16:54.000Z","size":153,"stargazers_count":475,"open_issues_count":36,"forks_count":140,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-04T07:07:09.369Z","etag":null,"topics":["arduino","arduino-library","esp32","esp32-arduino","esp8266","esp8266-arduino","iot","mqtt","wifi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plapointe6.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}},"created_at":"2018-11-25T18:03:54.000Z","updated_at":"2025-04-01T12:34:56.000Z","dependencies_parsed_at":"2023-02-12T12:46:03.777Z","dependency_job_id":"83d1a765-7b52-442a-a936-d2f90fc5f676","html_url":"https://github.com/plapointe6/EspMQTTClient","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plapointe6%2FEspMQTTClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plapointe6%2FEspMQTTClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plapointe6%2FEspMQTTClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plapointe6%2FEspMQTTClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plapointe6","download_url":"https://codeload.github.com/plapointe6/EspMQTTClient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135144,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","arduino-library","esp32","esp32-arduino","esp8266","esp8266-arduino","iot","mqtt","wifi"],"created_at":"2024-09-30T15:33:43.969Z","updated_at":"2025-04-04T07:07:15.390Z","avatar_url":"https://github.com/plapointe6.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MQTT and Wifi handling for ESP8266 and ESP32\n\nThis library is intended to encapsulate the handling of WiFi and MQTT connections of an ESP8266/ESP32.\nYou just need to provide your credentials and it will manage the following things:\n- Connecting to a WiFi network.\n- Connecting to a MQTT broker.\n- Automatically detecting connection lost either from the WiFi client or the MQTT broker and it will retry a connection automatically.\n- Subscribing/unsubscribing to/from MQTT topics by a friendly callback system.\n- Supports wildcards (`+`, `#`) in subscriptions\n- Provide a callback handling to advise once everything is connected (Wifi and MQTT).\n- Provide a function to enable printing of useful debug information related to MQTT and Wifi connections.\n- Provide some other useful utilities for MQTT and Wifi management.\n- Provide a function to enable an HTTP Update server secured by a password to allow remote update.\n- Provide a function to enable OTA secured by a password to allow remote update.\n\n## Dependency\n\nThe MQTT communication depends on the [PubSubClient Library](https://github.com/knolleary/pubsubclient).\n\n## Example\n\n```c++\n#include \"EspMQTTClient.h\"\n\nEspMQTTClient client(\n  \"WifiSSID\",\n  \"WifiPassword\",\n  \"192.168.1.100\",  // MQTT Broker server ip\n  \"MQTTUsername\",   // Can be omitted if not needed\n  \"MQTTPassword\",   // Can be omitted if not needed\n  \"TestClient\"      // Client name that uniquely identify your device\n);\n\nvoid setup() {}\n\nvoid onConnectionEstablished() {\n\n  client.subscribe(\"mytopic/test\", [] (const String \u0026payload)  {\n    Serial.println(payload);\n  });\n\n  client.publish(\"mytopic/test\", \"This is a message\");\n}\n\nvoid loop() {\n  client.loop();\n}\n```\n\nSee `SimpleMQTTClient.ino` for the complete example.\n\n\n## Documentation\n\n### Construction\n\nFor Wifi and MQTT connection handling (Recommended):\n```c++\n  EspMQTTClient(\n    const char* wifiSsid,\n    const char* wifiPassword,\n    const char* mqttServerIp,\n    const char* mqttUsername,  // Omit this parameter to disable MQTT authentification\n    const char* mqttPassword,  // Omit this parameter to disable MQTT authentification\n    const char* mqttClientName = \"ESP8266\",\n    const uint16_t mqttServerPort = 1883);\n```\n\nMQTT connection handling only:\n```c++\n  EspMQTTClient(\n    const char* mqttServerIp,\n    const uint16_t mqttServerPort,  // It is mandatory here to allow these constructors to be distinct from those with the Wifi handling parameters\n    const char* mqttUsername,    // Omit this parameter to disable MQTT authentification\n    const char* mqttPassword,    // Omit this parameter to disable MQTT authentification\n    const char* mqttClientName = \"ESP8266\");\n```\n\n### Functions\n\nIMPORTANT: Must be called at each loop() of your sketch\n```c++\nvoid loop();\n```\n\nBasic functions for MQTT communications.\n```c++\nbool publish(const String \u0026topic, const String \u0026payload, bool retain = false);\nbool subscribe(const String \u0026topic, MessageReceivedCallback messageReceivedCallback, uint8_t qos = 0);\nbool unsubscribe(const String \u0026topic);\n```\n\nChange the maximum packet size that can be sent over MQTT. The default is 128 bytes.\n```c++\nbool setMaxPacketSize(const uint16_t size);\n```\n\nChange the keep alive interval (15 seconds by default)\n```c++\nvoid setKeepAlive(uint16_t keepAliveSeconds);\n```\n\nEnable debugging messages that will output to serial.\n```c++\nvoid enableDebuggingMessages(const bool enabled = true);\n```\n\nEnable the web updater. This will host a simple form that will allow firmware upgrade (using, e.g., the `.bin` file produced by \"Export Compiled Binary\" in the Arduino IDE's \"Sketch\" menu). Must be set before the first loop() call.\n```c++\nvoid enableHTTPWebUpdater(const char* username, const char* password, const char* address = \"/\");\n\n// this one will set user and password equal to those set for the MQTT connection.\nvoid enableHTTPWebUpdater(const char* address = \"/\");\n```\n\nEnable last will message. Must be set before the first loop() call.\n```c++\nvoid enableLastWillMessage(const char* topic, const char* message, const bool retain = false);\n```\n\nTell the broker to establish a persistent connection. Disabled by default. Must be called before the first loop() execution\n```c++\nvoid enableMQTTPersistence();\n```\n\nChange the delay between each MQTT reconnection attempt. Default is 15 seconds.\n```c++\nvoid setMqttReconnectionAttemptDelay(const unsigned int milliseconds);\n```\n\nChange the delay between each Wifi reconnection attempt. Default is 60 seconds.\n```c++\nvoid setWifiReconnectionAttemptDelay(const unsigned int milliseconds);\n```\n\nConnection status\n```c++\nbool isConnected(); // Return true if everything is connected.\nbool isWifiConnected(); // Return true if WiFi is connected.\nbool isMqttConnected(); // Return true if MQTT is connected.\nbool getConnectionEstablishedCount() // Return the number of time onConnectionEstablished has been called since the beginning.\n```\n\nAs ESP8266 does not like to be interrupted too long with the `delay()` function, this function will allow a delayed execution of a function without interrupting the sketch.\n```c++\nvoid executeDelayed(const long delay, DelayedExecutionCallback callback);\n```\n\nSome useful getters\n```c++\nconst char* getMqttClientName();\nconst char* getMqttServerIp();\nconst uint16_t getMqttServerPort();\n```\n\n### Connection established callback\n\nTo allow this library to work, you need to implement the `onConnectionEstablished()` function in your sketch.\n\n```c++\nvoid onConnectionEstablished()\n{\n  // Here you are sure that everything is connected.\n}\n```\n\nIn some special cases, like if you want to handle more than one MQTT connection in the same sketch, you can override this callback to another one for the second MQTT client using this function:\n```c++\nvoid setOnConnectionEstablishedCallback(ConnectionEstablishedCallback callback);\n```\nSee example `twoMQTTClientHandling.ino` for more details.\n\n\n### Subscribing to topics\n\nThe function `subscribe` allows subscribing a specific topic.\n\nFor example, if you want to subscribe to topic `test/mytopic`, you can do this:\n```c++\nvoid onTestMessageReceived(const String\u0026 message) {\n  Serial.print(\"message received from test/mytopic: \" + message);\n}\n\nclient.subscribe(\"test/mytopic\", onTestMessageReceived);\n```\n\nYou can also use lambdas to shorten the code like this:\n```c++\nclient.subscribe(\"test/mytopic\", [](const String\u0026 message) {\n  Serial.print(\"message received from test/mytopic: \" + message;\n});\n```\n\n#### Wildcards\n\nThis library also handle MQTT topic wildcards. Most of the time, you will want to see what was the original topic when the callback is called. Here is how to do that.\n\nExample: Subscribe to `wildcardtest/#` and display received topic and message to Serial\n```c++\nvoid onMessageReceived(const String\u0026 topic, const String\u0026 message) {\n  Serial.println(topic + \": \" + message);\n}\n\nclient.subscribe(\"wildcardtest/#\", onMessageReceived);\n```\n\nThe same thing with lambdas:\n```c++\n  client.subscribe(\"wildcardtest/#\", [](const String\u0026 topic, const String\u0026 message) {\n    Serial.println(topic + \": \" + message);\n  });\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplapointe6%2Fespmqttclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplapointe6%2Fespmqttclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplapointe6%2Fespmqttclient/lists"}