{"id":14963094,"url":"https://github.com/espressif/esp-qcloud","last_synced_at":"2025-10-19T08:31:49.272Z","repository":{"id":36556082,"uuid":"145512395","full_name":"espressif/esp-qcloud","owner":"espressif","description":"基于 ESP-IDF 原生开发接入腾讯 IoT Explorer，支持 ESP32/ESP32S2，快速实现腾讯连连控制。","archived":false,"fork":false,"pushed_at":"2024-01-23T04:44:49.000Z","size":11048,"stargazers_count":73,"open_issues_count":19,"forks_count":36,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-01-31T17:17:35.346Z","etag":null,"topics":["cloud"],"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/espressif.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-08-21T05:43:11.000Z","updated_at":"2025-01-26T07:59:24.000Z","dependencies_parsed_at":"2024-01-23T05:48:25.260Z","dependency_job_id":null,"html_url":"https://github.com/espressif/esp-qcloud","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fesp-qcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fesp-qcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fesp-qcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fesp-qcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/espressif","download_url":"https://codeload.github.com/espressif/esp-qcloud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237092680,"owners_count":19254251,"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":["cloud"],"created_at":"2024-09-24T13:31:00.680Z","updated_at":"2025-10-19T08:31:47.977Z","avatar_url":"https://github.com/espressif.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32 设备对接腾讯云指南\n\n## 目录\n\n0. [介绍](#Introduction)\n1. [硬件准备](#hardwareprepare)  \n2. [IDF环境搭建](#compileprepare)  \n3. [构建\u0026烧录\u0026运行工程](#makefile)  \n4. [调试工具](#debugtool)\n5. [相关资源](#faq)\n\n## \u003cspan id = \"Introduction\"\u003e0. 介绍\u003c/span\u003e\n\n`esp-qcloud` 是由 [乐鑫官方](https://www.espressif.com) 推出接入 [腾讯物联网开发平台 (IoT Explorer)](https://console.cloud.tencent.com/iotexplorer) 的开发套件 。该套件依据 `IoT Explorer` 通信协议而设计，相对于 [腾讯云物联 IoT C-SDK](https://github.com/tencentyun/qcloud-iot-sdk-embedded-c)，该套件将云平台配置、配网操作封装成接口，简化了整体流程，只需完成简单的调用，即可完成配网、连云操作。同时，该套件提供了丰富的调试工具、示例代码、量产工具供你快速完成产品开发。\n\n当前 IDF 支持情况如下表：\n\n|                       | ESP-IDF \u003cbr\u003e Release/v3.3 | ESP-IDF \u003cbr\u003e Release/v4.0| ESP-IDF \u003cbr\u003e Release/v4.1| ESP-IDF \u003cbr\u003e Release/v4.2| ESP-IDF \u003cbr\u003e Release/v4.3| ESP-IDF \u003cbr\u003e Release/v4.4 | ESP-IDF \u003cbr\u003e Master |\n|:----------- |:---------------------: | :---------------------:| :---------------------:|:---------------------: | :---------------------:| :---------------------:| :---------------------:|\n| esp-qcloud \u003cbr\u003e Master  |  ❌ | ❌ |  ❌ | ✔ | ✔ | ✔ | ✔ |\n\n- **配网方式**\n\n  - [x] softap\n  - [x] airkiss\n  - [x] esp-touch v1\n  - [x] ble\n  - [x] provisioning softap\n  - [ ] esp-touch v2\n\n- **认证方式**\n\n  - [x] 密钥认证\n  - [x] 证书认证\n  - [ ] 动态注册\n\n- **业务功能**\n\n  - [x] 状态上报与下发\n  - [x] OTA升级\n  - [x] 事件上报\n  - [ ] 网关\n\n- **调试功能**\n\n  - [x] 日志上报云平台\n  - [x] 日志本地存储\n  - [x] 串口调试\n\n- **生产工具**\n\n  - [x] 单一/批量 bin 生成\n  - [ ] 加密\n\n## \u003cspan id = \"hardwareprepare\"\u003e1.硬件准备\u003c/span\u003e\n\n- **模组**  \n\n  - ESP32\n  - ESP32-S2\n  - ESP32-C3\n  - ESP32-S3\n\n## \u003cspan id = \"compileprepare\"\u003e2. IDF 环境搭建\u003c/span\u003e\n\n- 可以参考 [ESP-IDF编程指南-快速入门](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#get-started-setup-toolchain) 快速完成工具链与环境的搭建\n- 构建工程之前需将 `ESP-IDF` 切换到合适版本。当前支持的 IDF 版本请[查阅此处](#Introduction)。\n\n    ```shell\n    cd  $IDF_PATH \n\n    git checkout release/v4.3 \n\n    git submodule update --init --recursive\n    ```\n\n## \u003cspan id = \"makefile\"\u003e3. 构建\u0026烧录\u0026运行工程\u003c/span\u003e\n\n0. **提取项目文件**\n\n    你可以直接在 `examples` 目录下提取文件，也可以通过将 `esp-qcloud` 作为 `git` 子模块进行开发。\n\n    1. 直接提取开发\n\n        ```shell\n        #Copy example\n        cp -r ./examples/led_light ./examples/my_project\n        \n        #Delete unnecessary files\n        cd ./examples/my_project\n        idf.py fullclean\n        ```\n\n    2. 通过 `git` 管理开发\n\n        将 `esp-qcloud` 作为 `git` 子模块进行开发，无需在此项目中复制或编辑任何文件，可更方便的维护和更新本项目。\n\n        ```shell\n        #Copy example\n        cp -r ./examples/led_light ~/my_project\n        cd ~/my_project\n\n        #Register submodule\n        git init\n        mkdir -p components\n\n        #Choice 1\n        git submodule add https://github.com/espressif/esp-qcloud.git components/qcloud\n        #Choice 2\n        git submodule add https://gitee.com/espressifsystems/esp-qcloud.git components/qcloud\n\n        #Delete unnecessary files\n        idf.py fullclean\n        ```\n\n1. **配置芯片**\n\n    不同的芯片会加载不同的 `sdkconfig` 默认文件，位于 [config](./config/sdkconfig_defaults) 目录下。默认的 `sdkconfig` 文件会加载 `4MB` 的 `分区表 (partitions)` 。如果芯片 `flash` \u003cb\u003e小于\u003c/b\u003e `4MB` ，需要将其更改为 `2MB` 的分区表。下述几个命令将帮助你快速配置芯片。\n\n    - **查看当前芯片信息**\n\n        ```shell\n        $IDF_PATH/components/esptool_py/esptool/esptool.py flash_id\n        ```\n\n    - **设置编译时目标芯片**\n\n        ```shell\n        #choose esp32\n        idf.py set-target esp32 \n\n        #choose esp32s2\n        idf.py set-target esp32s2\n\n        #choose esp32c3\n        idf.py set-target esp32c3\n        ```\n\n    - **更改 `Partition`**\n\n        1. **进入 `menuconfig` 配置界面**\n\n            ```shell\n            idf.py menuconfig\n            ```\n\n        2. **选择 `Partition Table`**\n\n            ```shell\n            Partition Table (Custom partition table CSV)  ---\u003e\n            (${QCLOUD_PATH}/config/partition_table/partitions_4MB.csv) Custom partition CSV file\n            (0xc000) Offset of partition table\n            [*] Generate an MD5 checksum for the partition table\n            ```\n\n            - `Custom partition CSV file` 中即可编辑 `CSV` 文件。\n\n2. **烧录认证信息[可选]**\n\n   当使用云平台时，你需要在 [IoT Explorer](https://console.cloud.tencent.com/iotexplorer) 获取认证信息，认证信息通常为 `产品 ID (PRODUCT_ID)` 、 `设备名称 (DEVICE_NAME)`、 `设备密钥 (DEVICE_SECRET)`，可参考 [智能灯文档](./examples/led_light/README.md) 中 `烧录认证信息` 或 [IoT Explorer 官方文档](https://cloud.tencent.com/document/product/1081/34739) 进行平台参数设置、获取。获取到认证信息时，可以选择下述任意一种方式烧录。\n\n   - **通过 `menuconfig` 配置**\n\n        1. **进入 `menuconfig` 配置界面**\n\n            ```shell\n            idf.py menuconfig\n            ```\n\n        2. **选择 `ESP QCloud Config` 选项**\n\n            ```shell\n            [ ] ESP QCloud Mass Manufacture\n            (PRODUCT_ID) Product ID\n            (DEVICE_NAME) Device Name\n            (DEVICE_SECRET) Device Secret\n            ESP QCloud OTA Config  ---\u003e\n            ESP QCloud utils  ---\u003e\n            ESP QCloud Log Config  ---\u003e\n            UART for console input (UART0)  ---\u003e\n            ```\n\n            - \u003cb\u003e不开启\u003c/b\u003e `ESP QCloud Mass Manufacture` 选项。\n\n        3. **填入你的信息**\n\n            填写 `产品 ID (PRODUCT_ID)`、 `设备名称 (DEVICE_NAME)`、 `设备密钥 (DEVICE_SECRET)`。\n\n    - **通过量产工具配置**\n\n        请参考量产工具目录下的 [文档](./config/mass_mfg/README.md) ，另外需要 \u003cb\u003e开启\u003c/b\u003e `ESP QCloud Mass Manufacture` 选项。\n\n3. **构建项目**\n\n    当完成配置，下述命令将帮助快速构建。\n\n    - **构建工程**\n\n    ```shell\n    idf.py build\n    ```\n\n    - **清理工程**\n\n    ```shell\n    idf.py fullclean\n    ```\n\n    - **性能选择**\n\n        通过在编译时传递 `PERF` 定义来决定开启的性能。未指定参数时将使用 `defaults` 配置，关于性能的说明，请参考 [性能说明文档](./docs/ESP32PerformanceOptions.md)。\n\n    ```shell\n    #high performance\n    idf.py menuconfig -D PERF=\"hight_perf\"\n\n    #low performance\n    idf.py menuconfig -D PERF=\"low_perf\"\n    ```\n\n3. **运行项目**\n\n    - **下载、运行工程**\n\n    ```shell\n    idf.py flash monitor\n    ```\n\n    - **擦除 Flash**\n\n    ```shell\n    idf.py erase_flash\n    ```\n\n## \u003cspan id = \"debugtool\"\u003e4. 调试工具\u003c/span\u003e\n\n- **串口调试**\n\n    串口调试允许通过串口查看当前设备信息，开启方法如下：\n\n    1. **进入 `menuconfig` 配置界面**\n\n        ```shell\n        idf.py menuconfig\n        ```\n\n    2. **选择 `ESP QCloud Example Configuration`**\n\n        ```shell\n        Light development board selection   ---\u003e\n        Light provisioning network selection  ---\u003e\n        (5) More than this number of continuous uninterrupted restarts triggers a reset of the device\n        [*] The device will be in debug mode\n        ```\n\n        - \u003cb\u003e开启\u003c/b\u003e `The device will be in debug mode` 选项。\n\n    3. **查看调试信息**\n\n        - 下述为 `led_light` 中的打印信息。\n\n        ```\n        I (31091) esp_qcloud_utils: System information sta_mac: 24:6f:28:80:3f:14, channel: [10/2], rssi: -40, free_heap: 181128, minimum_heap: 161540\n        ```\n\n        - 通过 `shell` 输入指令可查看相关信息，例如执行 `heap` 指令，将打印系统运行状态，更多指令可通过 `help` 查询。\n\n        ```shell\n        esp32\u003e heap\n        I (15360) esp_qcloud_mem: (714) \u003cesp_qcloud_log: 159\u003e ptr: 0x3ffbd1c4, size: 16\n        I (15361) esp_qcloud_mem: (716) \u003cesp_qcloud_log_flash: 157\u003e ptr: 0x3ffbdecc, size: 24\n        I (15372) esp_qcloud_mem: (1093) \u003cesp_qcloud_device: 85\u003e ptr: 0x3ffbe8e4, size: 20\n        I (15383) esp_qcloud_mem: (1093) \u003cesp_qcloud_device: 218\u003e ptr: 0x3ffc0d3c, size: 20\n        I (15384) esp_qcloud_mem: (1093) \u003cesp_qcloud_device: 218\u003e ptr: 0x3ffc0d68, size: 20\n        I (15395) esp_qcloud_mem: (1094) \u003cesp_qcloud_device: 218\u003e ptr: 0x3ffc0d80, size: 20\n        I (15406) esp_qcloud_mem: (1094) \u003cesp_qcloud_device: 218\u003e ptr: 0x3ffc0da8, size: 20\n        I (15417) esp_qcloud_mem: (3608) \u003cesp_qcloud_iothub: 213\u003e ptr: 0x3ffca3d4, size: 128\n        I (15418) esp_qcloud_mem: Memory record, num: 8, size: 268\n        I (15429) esp_qcloud_mem: Free heap, current: 181096, minimum: 161540\n        I (15441) esp_qcloud_mem: ---------------- The State Of Tasks ----------------\n        I (15441) esp_qcloud_mem: - HWM   : usage high water mark (Byte)\n        I (15452) esp_qcloud_mem: - Status: blocked ('B'), ready ('R'), deleted ('D') or suspended ('S')\n\n        I (15463) esp_qcloud_mem: TaskName              Status  Prio    HWM     TaskNum CoreID  RunTimeCounter  Percentage\n        I (15464) esp_qcloud_mem: console_handle        R       1       1952    8       -1      26908           \u003c1\n        I (15475) esp_qcloud_mem: IDLE0                 R       0       1008    4       0       13232798        89\n        I (15486) esp_qcloud_mem: mqtt_task             B       5       3472    12      -1      978102          6\n        I (15487) esp_qcloud_mem: Tmr Svc               B       1       792     5       0       1851            \u003c1\n        I (15498) esp_qcloud_mem: qcloud_log_send       B       4       2580    7       0       3451            \u003c1\n        I (15509) esp_qcloud_mem: tiT                   B       18      2112    9       -1      26425           \u003c1\n        I (15510) esp_qcloud_mem: esp_timer             B       22      3348    1       0       38541           \u003c1\n        I (15521) esp_qcloud_mem: wifi                  B       23      3944    11      0       234073          1\n        I (15532) esp_qcloud_mem: sys_evt               B       20      596     10      0       2884            \u003c1\n        ```\n\n- **保存调试日志**\n\n    该功能可将日志保存在 `Flash`。你需要构造 `esp_qcloud_log_config_t` 结构体，通过 `esp_qcloud_log_init()` 设置日志等级。\n\n    ```c\n    esp_qcloud_log_config_t log_config = {\n    .log_level_flash = ESP_LOG_INFO,\n    };\n    ```\n\n## \u003cspan id = \"faq\"\u003e5. 相关资源\u003c/span\u003e\n\n- 文档中心\n\n  - [ESP-IDF 编程指南（ESP32）](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/)\n  - [ESP-IDF 编程指南（ESP32S2）](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32s2/index.html)\n  - [腾讯云物联网开发平台文档（IoT Explorer）](https://cloud.tencent.com/document/product/1081)\n\n- 源码仓库\n\n  - [Espressif Systems - github](https://github.com/espressif)\n  - [Espressif Systems - gitee](https://gitee.com/EspressifSystems)\n\n- 相关视频\n\n  - [乐鑫物联网学院](https://space.bilibili.com/538078399)\n  - [腾讯云大学](https://cloud.tencent.com/edu/learning)\n  - [开发参考视频](https://www.bilibili.com/video/BV1Hi4y157mG?from=search\u0026seid=16774267987685056247)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespressif%2Fesp-qcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fespressif%2Fesp-qcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespressif%2Fesp-qcloud/lists"}