{"id":16218676,"url":"https://github.com/loginov-rocks/awsiotwificlient","last_synced_at":"2025-10-14T04:50:52.587Z","repository":{"id":135933433,"uuid":"588429691","full_name":"loginov-rocks/AwsIotWiFiClient","owner":"loginov-rocks","description":"Library to easily and securely connect NodeMCU (ESP8266) to AWS IoT","archived":false,"fork":false,"pushed_at":"2024-08-16T19:42:22.000Z","size":23391,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T13:11:13.459Z","etag":null,"topics":["arduino","arduino-library","aws","esp8266","iot","nodemcu","platformio","wifi-client"],"latest_commit_sha":null,"homepage":"https://registry.platformio.org/libraries/loginov-rocks/AwsIotWiFiClient","language":"C++","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/loginov-rocks.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":"2023-01-13T05:02:29.000Z","updated_at":"2025-03-24T01:02:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"18187c7f-7166-4059-a342-51547a7cd8cc","html_url":"https://github.com/loginov-rocks/AwsIotWiFiClient","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FAwsIotWiFiClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FAwsIotWiFiClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FAwsIotWiFiClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FAwsIotWiFiClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loginov-rocks","download_url":"https://codeload.github.com/loginov-rocks/AwsIotWiFiClient/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248237688,"owners_count":21070303,"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","aws","esp8266","iot","nodemcu","platformio","wifi-client"],"created_at":"2024-10-10T11:50:16.110Z","updated_at":"2025-10-14T04:50:47.565Z","avatar_url":"https://github.com/loginov-rocks.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AwsIotWiFiClient\n\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/loginov-rocks/library/AwsIotWiFiClient.svg)](https://registry.platformio.org/libraries/loginov-rocks/AwsIotWiFiClient)\n[![Arduino Lint](https://github.com/loginov-rocks/AwsIotWiFiClient/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/loginov-rocks/AwsIotWiFiClient/actions/workflows/arduino-lint.yml)\n[![PlatformIO Build](https://github.com/loginov-rocks/AwsIotWiFiClient/actions/workflows/platformio-build.yml/badge.svg)](https://github.com/loginov-rocks/AwsIotWiFiClient/actions/workflows/platformio-build.yml)\n\nConnect NodeMCU (ESP8266) to AWS IoT: [Medium](https://loginov-rocks.medium.com/connect-nodemcu-esp8266-to-aws-iot-b75d2470b40b)\n\nThe **AwsIotWiFiClient** library is designed to facilitate the connection of ESP8266 devices to AWS IoT Core. This\nlibrary provides an abstraction layer that simplifies the process of establishing secure SSL/TLS communication and MQTT\nmessaging between the ESP8266 microcontroller and AWS IoT services.\n\n### Key Features\n\n1. **Secure Communication:** uses\n   [WiFiClientSecure](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecureBearSSL.h)\n   to manage certificates and private keys, ensuring secure communication with AWS IoT Core. Unlike other libraries\n   that require creating policies and making direct calls, **AwsIotWiFiClient** establishes secure communication using\n   device certificates, which is the native approach for AWS IoT.\n2. **MQTT Messaging:** incorporates the [PubSubClient](https://registry.platformio.org/libraries/knolleary/PubSubClient)\n   library to support MQTT messaging, allowing devices to publish and subscribe to topics on AWS IoT Core.\n3. **Easy Configuration:** provides a straightforward API for setting up certificates, endpoints, client IDs, and topic\n   filters.\n4. **Callback Mechanism:** supports callback function to handle incoming MQTT messages, enabling real-time data\n   processing and event handling.\n5. **Debugging:** offers debug output to assist in troubleshooting and verifying the connection and communication\n   processes.\n\n### Usage Scenario\n\nThe **AwsIotWiFiClient** library is ideal for projects that involve ESP8266 devices needing to communicate with AWS IoT\nCore. Typical applications include sensor data collection, remote monitoring, and control systems where reliable and\nsecure data exchange is critical.\n\nBy abstracting the complexity of secure communication and MQTT messaging, the **AwsIotWiFiClient** library allows\ndevelopers to focus on implementing the business logic of their IoT applications.\n\n## Quick Start\n\n```cpp\n#include \"AwsIotWiFiClient.h\"\n#include \"ESP8266WiFi.h\"\n\n#include \"pgmspace.h\"\n\n// Device certificate\n// Copy and paste contents from *-certificate.pem.crt\nstatic const char deviceCertificate[] PROGMEM = R\"KEY(\n-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n)KEY\";\n\n// Key files / Private key file\n// Copy and paste contents from *-private.pem.key\nstatic const char privateKeyFile[] PROGMEM = R\"KEY(\n-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----\n)KEY\";\n\n// RSA 2048 bit key: Amazon Root CA 1\n// Copy and paste contents from AmazonRootCA1.cer\nstatic const char rootCaCertificate[] PROGMEM = R\"EOF(\n-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n)EOF\";\n\nAwsIotWiFiClient awsIotWiFiClient;\n\nBearSSL::X509List trustAnchorCertificate(rootCaCertificate);\nBearSSL::X509List clientCertificate(deviceCertificate);\nBearSSL::PrivateKey clientPrivateKey(privateKeyFile);\n\nvoid receiveMessage(char *topic, byte *payload, unsigned int length)\n{\n  Serial.print(\"Message received: \");\n  Serial.write(payload, length);\n  Serial.println();\n}\n\nvoid setup()\n{\n  // Connect to Wi-Fi first!\n  // ...\n\n  // Set up AWS IoT Wi-Fi Client:\n  awsIotWiFiClient\n      // Enable debug output:\n      .setDebugOutput(true)\n      // Certificates to establish secure communication (defined above):\n      .setCertificates(\u0026trustAnchorCertificate, \u0026clientCertificate, \u0026clientPrivateKey)\n      // Device Data Endpoint from IoT Core -\u003e Settings:\n      .setEndpoint(\"endpoint.iot.us-east-1.amazonaws.com\")\n      // Callback function that will be triggered when incoming messages are received (defined above):\n      .setReceiveMessageCallback(receiveMessage)\n      // MQTT client ID aka thing name:\n      .setClientId(\"client\")\n      // MQTT topic filter to subscribe to incoming messages:\n      .setSubscribeTopicFilter(\"topic\")\n      // Connect to the AWS IoT service:\n      .connect();\n}\n\nvoid loop()\n{\n  // ...\n\n  // Publish message \"Hello, world!\" to the \"topic\" topic:\n  awsIotWiFiClient.publishMessage(\"topic\", \"Hello, world!\");\n  awsIotWiFiClient.loop();\n}\n```\n\n## AWS Infrastructure\n\n![Infrastructure View](https://raw.githubusercontent.com/loginov-rocks/AwsIotWiFiClient/main/docs/aws/Infrastructure%20View.png)\n\nThere are several additional AWS components shown on the right, beyond the AWS IoT Core, but they are just an example\nof how you can further extend the solution, while we are going to focus on the central and left parts:\n\n* AWS IoT Core configuration;\n* Microcontroller (MCU) connection over MQTT to AWS IoT Core;\n* Device certificate and policy that will grant necessary permissions to establish a connection, publish, and receive\n  messages from AWS IoT Core.\n\nMQTT has gained popularity within the hobbyist community for DIY IoT projects due to its simplicity and efficiency. AWS\nIoT leverages MQTT as a standard to enable seamless, real-time data exchange between IoT devices and the cloud, making\nit ideal for connecting constrained devices like the NodeMCU.\n\nDevice certificate ensures that the communication between your microcontroller and AWS is encrypted and secure, but\nalso authenticates your device with AWS IoT, confirming its identity — this guarantees that only trusted devices can\nconnect to your AWS infrastructure, maintaining the integrity of your system.\n\n* [CloudFormation](https://github.com/loginov-rocks/AwsIotWiFiClient/blob/main/docs/aws/cloudformation.json)\n* [Policy](https://github.com/loginov-rocks/AwsIotWiFiClient/blob/main/docs/aws/policy.json)\n\n## API\n\n### `AwsIotWiFiClient`\n\nAWS IoT Wi-Fi Client class is the core component of the library, encapsulating all the functionalities needed to\nconnect an ESP8266 microcontroller to AWS IoT Core. It manages the setup of secure SSL/TLS communication using\n[WiFiClientSecure](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecureBearSSL.h)\nand facilitates MQTT messaging via [PubSubClient](https://registry.platformio.org/libraries/knolleary/PubSubClient).\n\nThe class provides methods to configure device-specific credentials, establish connections, and subscribe to and\npublish MQTT messages. Additionally, it includes a callback mechanism to process incoming messages.\n\n**Kind**: class\n\n\u003c!-- no toc --\u003e\n* [AwsIotWiFiClient](#awsiotwificlient-1)\n  * [setCertificates(\u0026trustAnchorCertificate, \u0026clientCertificate, \u0026clientPrivateKey)](#setcertificatestrustanchorcertificate-clientcertificate-clientprivatekey)\n  * [setEndpoint(endpoint)](#setendpointendpoint)\n  * [setReceiveMessageCallback(callback)](#setreceivemessagecallbackcallback)\n  * [setClientId(clientId)](#setclientidclientid)\n  * [setSubscribeTopicFilter(subscribeTopicFilter)](#setsubscribetopicfiltersubscribetopicfilter)\n  * [setDebugOutput(debugOutput)](#setdebugoutputdebugoutput)\n  * [connect()](#connect)\n  * [loop()](#loop)\n  * [publishMessage(topicName, message) ⇒ boolean](#publishmessagetopicname-message--boolean)\n\n---\n\n#### `setCertificates(\u0026trustAnchorCertificate, \u0026clientCertificate, \u0026clientPrivateKey)`\n\nSet certificates to establish secure communication.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter               | Type          | Description                             |\n| ----------------------- | ------------- | --------------------------------------- |\n| \u0026trustAnchorCertificate | `X509List*`   | Pointer to the trust anchor certificate |\n| \u0026clientCertificate      | `X509List*`   | Pointer to the client certificate       |\n| \u0026clientPrivateKey       | `PrivateKey*` | Pointer to the client private key       |\n\n---\n\n#### `setEndpoint(endpoint)`\n\nSet Device Data Endpoint from IoT Core -\u003e Settings.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter | Type    | Description          |\n| --------- | ------- | -------------------- |\n| endpoint  | `char*` | Device Data Endpoint |\n\n---\n\n#### `setReceiveMessageCallback(callback)`\n\nSet the callback function that will be triggered when incoming messages are received.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter | Type                                                   | Description                                           |\n| --------- | ------------------------------------------------------ | ----------------------------------------------------- |\n| callback  | `std::function\u003cvoid(char *, uint8_t *, unsigned int)\u003e` | Function to call when an incoming message is received |\n\nExample:\n\n```cpp\nvoid callback(char *topic, byte *payload, unsigned int length)\n{\n  Serial.print(\"Message received: \");\n  Serial.write(payload, length);\n  Serial.println();\n}\n```\n\n---\n\n#### `setClientId(clientId)`\n\nSet the MQTT client ID aka thing name.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter | Type    | Description    |\n| --------- | ------- | -------------- |\n| clientId  | `char*` | MQTT client ID |\n\n---\n\n#### `setSubscribeTopicFilter(subscribeTopicFilter)`\n\nSet the MQTT topic filter to subscribe to incoming messages.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter            | Type    | Description       |\n| -------------------- | ------- | ----------------- |\n| subscribeTopicFilter | `char*` | MQTT topic filter |\n\n---\n\n#### `setDebugOutput(debugOutput)`\n\nEnable or disable debug output. Disabled by default.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n| Parameter   | Type      | Description                                       |\n| ----------- | --------- | ------------------------------------------------- |\n| debugOutput | `boolean` | `true` to enable, `false` to disable debug output |\n\n---\n\n#### `connect()`\n\nConnect to the AWS IoT service.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n---\n\n#### `loop()`\n\nKeep the MQTT connection alive and process incoming messages. This should be called regularly in the main loop.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n---\n\n#### `publishMessage(topicName, message)` ⇒ `boolean`\n\nPublish a message to the specified MQTT topic.\n\n**Kind**: instance method of `AwsIotWiFiClient`\n\n**Returns**: `boolean` - `true` in case of success, or `false` otherwise\n\n| Parameter | Type    | Description                  |\n| --------- | ------- | ---------------------------- |\n| topicName | `char*` | The MQTT topic to publish to |\n| message   | `char*` | The message payload          |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floginov-rocks%2Fawsiotwificlient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floginov-rocks%2Fawsiotwificlient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floginov-rocks%2Fawsiotwificlient/lists"}