{"id":20802330,"url":"https://github.com/astarte-platform/astarte-device-sdk-esp32","last_synced_at":"2025-05-07T00:46:27.610Z","repository":{"id":36783492,"uuid":"153440727","full_name":"astarte-platform/astarte-device-sdk-esp32","owner":"astarte-platform","description":"Astarte device SDK for ESP32 devices, based on esp-idf","archived":false,"fork":false,"pushed_at":"2025-04-14T12:25:19.000Z","size":972,"stargazers_count":13,"open_issues_count":20,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-22T08:56:11.389Z","etag":null,"topics":["esp32","hacktoberfest","iot-device"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astarte-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-17T10:46:39.000Z","updated_at":"2025-02-20T10:32:48.000Z","dependencies_parsed_at":"2023-11-09T12:38:04.221Z","dependency_job_id":"c66e88be-23d7-430f-9d0c-deac1cfdd1d9","html_url":"https://github.com/astarte-platform/astarte-device-sdk-esp32","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/astarte-platform%2Fastarte-device-sdk-esp32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astarte-platform%2Fastarte-device-sdk-esp32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astarte-platform%2Fastarte-device-sdk-esp32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astarte-platform%2Fastarte-device-sdk-esp32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astarte-platform","download_url":"https://codeload.github.com/astarte-platform/astarte-device-sdk-esp32/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252793567,"owners_count":21805054,"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":["esp32","hacktoberfest","iot-device"],"created_at":"2024-11-17T18:30:27.219Z","updated_at":"2025-05-07T00:46:27.598Z","avatar_url":"https://github.com/astarte-platform.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!---\n  Copyright 2018-2023 SECO Mind Srl\n\n  SPDX-License-Identifier: LGPL-2.1-or-later OR Apache-2.0\n--\u003e\n\n# Astarte ESP32 SDK\n\nAstarte ESP32 SDK lets you connect your ESP32 device to\n[Astarte](https://github.com/astarte-platform/astarte).\n\nThe SDK simplifies all the low-level operations like credentials generation, pairing and so on, and\nexposes a high-level API to publish data from your device.\n\nCheck out the examples on the right pane of the\n[astarte-device-sdk-esp32](https://components.espressif.com/components/astarte-platform/astarte-device-sdk-esp32)\ncomponent page or on the\n[GitHub repository](https://github.com/astarte-platform/astarte-device-sdk-esp32/tree/master/examples/README.md)\n.\n\n## Documentation\n\nThe generated Doxygen documentation is available in the [Astarte Documentation\nwebsite](https://docs.astarte-platform.org/device-sdks/esp32/latest/api).\n\n## `esp-idf` version compatibility\n\nThe SDK is tested against these versions of `esp-idf`:\n- `v5.x`\n\nPrevious versions of `esp-idf` are not guaranteed to work. If you find a problem using a later\nversion of `esp-idf`, please [open an\nissue](https://github.com/astarte-platform/astarte-device-sdk-esp32/issues).\n\n## Component Free RTOS APIs usage\n\nThe Astarte ESP32 Device interacts internally with the Free RTOS APIs. As such some factors\nshould be taken into account when integrating this component into a larger system.\n\nThe following **tasks** are spawned directly by the Astarte ESP32 Device:\n- `credentials_init_task`: Initializes the credentials for the MQTT communication.\nThis task is created when calling the `astarte_credentials_init()` function.\nThis should be done before initializing the Astarte ESP32 Device.\nIt will use `16384` words from the stack and will be deleted before exiting the\n`astarte_credentials_init()` function.\n- `astarte_device_reinit_task`: Reinitializes the device in case of a TLS error coming from an\nexpired certificate. This task is created upon device initialization and runs constantly for the\nlife of the device. It will use `6000` words from the stack.\n\nAll of the tasks are spawned with the lowest priority and rely on the time-slicing functionality\nof freertos to run concurrently with the main task.\n\n## Notes on non-volatile memory (NVM)\n\nThe device's Astarte credentials are always stored in the NVM. This means that credentials will\nbe preserved in between reboots.\n\nTwo storage methods can be used for the credentials. A FAT32 file system or the standard\nnon-volatile storage (NVS) library provided by the ESP32. The FAT32 is the default storage choice.\nIf you want to use NVS storage, add the\n`astarte_credentials_use_nvs_storage` function before initializing `astarte_credentials`.\n```C\nastarte_credentials_use_nvs_storage(NVS_PARTITION);\n```\n\nHowever, note that even when FAT32 is used, the device credential secret is always stored using\nthe NVS library. This will require devices configured as using FAT32 to have two partitions,\none using as name the macro `NVS_DEFAULT_PART_NAME` (NVS) and one named `astarte` (FAT32).\n\nFurthermore, if you whish to use flash encryption for your device the only supported option is\nNVS.\n\n### Re-flashing devices\n\nAs a side effect of NVM usage, credentials will be preserved also between device flashes using\n`idf.py`.\n\n**N.B.** The device will first check if valid credentials are stored in the NVM, and only in case\nof a negative result will use the `Astarte SDK` component configuration to obtain fresh credentials.\n\nMost of the time during development the device credentials remain unchanged between firmware\nflashes and the old ones stored in the NVM can be reused.\nHowever, when changing elements of the `Astarte SDK` component configuration the old credentials\nshould be discarded by erasing the NMV.\nThis can be done using the following command:\n| idf.py (ESP-IDF v5.x) | idf.py (ESP-IDF v4.x) |\n| ------------- | ------------ |\n| `idf.py -p \u003cDEVICE_PORT\u003e erase-flash` | `idf.py -p \u003cDEVICE_PORT\u003e erase_flash` |\n\n## Notes on ignoring TLS certificates\n\n**N.B. Do not ignore TLS certificates errors in production!**\n\nIgnoring TLS certificates errors can be useful when trying out the device libraries in a prototyping\ncontext.\nFor example when using a local Astarte instance with self signed certificates.\n\nTo disable the TLS certificates checks in the device libraries add the following to your\n`sdkconfig.defaults` file:\n```\n#\n# ESP-TLS\n#\nCONFIG_ESP_TLS_INSECURE=y\nCONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY=y\n# end of ESP-TLS\n\n#\n# Certificate Bundle\n#\nCONFIG_MBEDTLS_CERTIFICATE_BUNDLE=n\n# end of Certificate Bundle\n```\n\nIf you are not using an `sdkconfig.defaults` file, run `idf.py menuconfig` and set the three options\nlisted above manually. The insecure and skip certificate options can be found in the ESP-TLS\ncomponent. While the bundle option can be found in the mbedTLS component.\n\n## Notes on custom certificate bundle\n\nThe Astarte ESP32 Device uses the\n[ESP x509 Certificate Bundle](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_crt_bundle.html)\nto verify the Astarte instance certificates.\n\nIf your Astarte instance uses a custom CA you can disable the default certificate bundle and add\nyour own certificates.\nThis can be done directly in `esp-idf` using the `menuconfig` command, or adding a\n`sdkconfig.defaults` file to your project.\n\nBelow an example configuration is presented. It adds a locally stored custom certificate.\n```\n#\n# Certificate Bundle\n#\nCONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y\n# CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL is not set\n# CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN is not set\nCONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_NONE=y\nCONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE=y\nCONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH=\"/path/to/certificate/file/astarte_instance.pem\"\n# end of Certificate Bundle\n```\n\n## Notes on BSON (de)serialization\n\nThe data exchange with an Astarte instance is encoded in the\n[BSON format](https://bsonspec.org/spec.html).\nThis library provides utility functions for serializing and deserializing BSONs. Handling BSON\ndirectly is only required when dealing with interfaces with object aggregation. Sending and\nreceiving on individually aggregated interfaces can be done using standard C types and structures.\n\nNote that not all the element types defined by the BSON 1.1 specification are supported by Astarte.\nThe subset of the supported element types can be found in the\n[Astarte MQTT v1](https://docs.astarte-platform.org/latest/080-mqtt-v1-protocol.html) protocol\nspecification.\n\n### The serialization utility\n\nSerializing data to a BSON format should be used during transmission of aggregates to Astarte.\nThe serialization utility is exposed by the `astarte_bson_serializer.h` header.\n\nA BSON object can be created using the `astarte_bson_serializer_new` function. Which will return an\nempty BSON document that can be filled by appending new elements using one of the\n`astarte_bson_serializer_append_*` functions. Once all the required elements have been added to the\ndocument it must be terminated using the `astarte_bson_serializer_append_end_of_document` function.\nThe serialized document can then be extracted using the `astarte_bson_serializer_get_document`\nfunction. This function will return a buffer that will live for as long as the BSON object.\n\nSince the memory for the BSON document is dynamically allocated it should be freed once the document\nis no longer required. This can be done with the `astarte_bson_serializer_get_document` function.\n\nA simple usage example is reported here.\n```C\n#include \"astarte_bson_serializer.h\"\n\nastarte_bson_serializer_handle_t bson = astarte_bson_serializer_new();\nastarte_bson_serializer_append_double(bson, \"co2\", 4.0);\nastarte_bson_serializer_append_int64(bson, \"temperature\", 42);\nastarte_bson_serializer_append_string(bson, \"identifier\", \"si383o33dm2\");\nastarte_bson_serializer_append_end_of_document(bson);\n\nint serialized_doc_size;\nconst void *serialized_doc = astarte_bson_serializer_get_document(bson, \u0026serialized_doc_size);\n\n// Use the returned serialized document before destroy call\n// For example send the buffer to Astarte by calling astarte_device_stream_aggregate()\n\nastarte_bson_serializer_destroy(bson);\n```\n\n### The deserialization utility\n\nDeserializing data from the BSON format is required when receiving aggregates from Astarte.\nThe deserialization utility is exposed by the `astarte_bson_deserializer.h` header.\n\nA BSON object can be initialized from a buffer containing serialized data using the function\n`astarte_bson_deserializer_init_doc`. This will return a document object of type\n`astarte_bson_document_t`, which provides information regarding the document such as its\ntotal size.\n\nAccessing the list of elements in the BSON document can be performed\nin two ways. By looping over all the elements using the `astarte_bson_deserializer_first_element`\nand `astarte_bson_deserializer_next_element` functions or, when the required element name is known,\nby lookup using the function `astarte_bson_deserializer_element_lookup`. Both functions return an\nelement object of the type `astarte_bson_element_t`, which provides information regarding the\nelement such as its type and name.\n\nTo extract the data contained in a single element one of the\n`astarte_bson_deserializer_element_to_*` functions should be used.\n\nA common use case of the deserializer is in the Astarte `data_event_callback`.\nThis function exposes the received data though the member `bson_element` of the parameter struct\n`event`. The `bson_element` variable is a BSON element object of the type `astarte_bson_element_t`.\n\nThe BSON deserializer utility will not perform dynamic allocation of memory but will use directly\nthe buffer passed during initialization. Make sure the buffer remains valid throughout the\ndeserialization process.\n\nTwo deserialization examples are reported here.\nThe first one is a very simple deserialization example for a BSON containing a single element of\ndouble type.\n```C\n#include \"astarte_bson_deserializer.h\"\n\nastarte_bson_document_t doc = astarte_bson_deserializer_init_doc(input_buffer);\n\nastarte_bson_element_t element;\nastarte_err_t astarte_err = astarte_bson_deserializer_element_lookup(doc, \"name\", \u0026element);\nif ((astarte_err != ASTARTE_OK) || (element.type != BSON_TYPE_DOUBLE)) {\n    abort();\n}\ndouble element_value = astarte_bson_deserializer_element_to_double(element);\n```\n\nThe second is a more complex example of a document containing an array of elements of type\ndouble and a single boolean element.\n```C\n#include \"astarte_bson_deserializer.h\"\n\nastarte_err_t astarte_err;\n\n// Initializing the document from a raw buffer\nastarte_bson_document_t doc = astarte_bson_deserializer_init_doc(input_buffer);\n\n// Extracting the element with name `boolean` using lookup\nastarte_bson_element_t element_bool;\nastarte_err = astarte_bson_deserializer_element_lookup(doc, \"boolean\", \u0026element_bool);\nif ((astarte_err != ASTARTE_OK) || (element_bool.type != BSON_TYPE_BOOLEAN)) {\n    abort();\n}\nbool value_bool = astarte_bson_deserializer_element_to_bool(element_bool);\n\n// Extracting the element with name `array` using lookup\nastarte_bson_element_t element_arr;\nastarte_err = astarte_bson_deserializer_element_lookup(doc, \"array\", \u0026element_arr);\nif ((astarte_err != ASTARTE_OK) || (element_arr.type != BSON_TYPE_ARRAY)) {\n    abort();\n}\n// Arrays are just special documents in the BSON specification\nastarte_bson_document_t arr_doc = astarte_bson_deserializer_element_to_document(element_arr);\n\n// Extract the first element\nastarte_bson_element_t element_arr_0;\nastarte_err = astarte_bson_deserializer_first_element(arr_doc, \u0026element_arr_0);\nif ((astarte_err != ASTARTE_OK) || (element_arr_0.type != BSON_TYPE_DOUBLE)) {\n    abort();\n}\ndouble element_arr_0_value = astarte_bson_deserializer_element_to_double(element_arr_0);\n\n// Extract each of the successive elements\nastarte_bson_element_t element_arr_prev = element_arr_0;\nastarte_bson_element_t element_arr_next;\nwhile (1) {\n    astarte_err = astarte_bson_deserializer_next_element(\n                        arr_doc, element_arr_prev, \u0026element_arr_next);\n    if (astarte_err == ASTARTE_ERR_NOT_FOUND) {\n        break;\n    }\n    if ((astarte_err != ASTARTE_OK) || (element_arr_next.type != BSON_TYPE_DOUBLE)) {\n        abort();\n    }\n\n    double element_arr_X_value = astarte_bson_deserializer_element_to_double(element_arr_next);\n\n    element_arr_prev = element_arr_next;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastarte-platform%2Fastarte-device-sdk-esp32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastarte-platform%2Fastarte-device-sdk-esp32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastarte-platform%2Fastarte-device-sdk-esp32/lists"}