帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>通用功能（设备端）>快速接入

快速接入

最近更新时间：2026-07-30 12:00:37

我的收藏

本页目录：

本文将介绍如何快速接入腾讯云物联网设备端 SDK，跑通登录功能。

前提条件

开通服务

在使用 IoT 设备端 SDK 前，您需要前往控制台，创建产品并在产品下创建设备。具体步骤参见 开通服务。
开通服务后，请记录以下设备三元组信息，在后续 登录 步骤中会用到：
ProductId（产品 ID）
DeviceName（设备名称）
DeviceSecret（设备密钥）
注意：
设备三元组是设备登录平台的唯一身份凭证，请妥善保管 DeviceSecret，避免硬编码提交到公共代码仓库。

环境准备

请根据您实际对接的设备芯片平台，准备对应的编译环境。本文以 Linux 本机环境为例演示接入流程，帮助您快速跑通登录功能；正式对接您的设备时，替换为目标芯片平台的交叉编译工具链即可，示例代码无需改动。
Linux 本机（快速体验）
嵌入式设备（交叉编译）
环境项
要求
操作系统
x86_64 Linux（Ubuntu 18.04+ / CentOS 7+ 等主流发行版）。
编译工具
CMake 3.10 及以上、GCC / Clang（支持 C99）。
系统依赖库
pthread、m（数学库）、dl、z（zlib）。
环境项
要求
交叉编译工具链
与目标芯片架构匹配的 GCC / Clang 交叉工具链（如 arm-linux-gnueabihf-gcc、aarch64-none-linux-gnu-gcc 等），具体工具链由芯片厂商 SDK 或 FAE 提供。
编译工具
CMake 3.21 及以上（交叉编译需要通过 -DCMAKE_TOOLCHAIN_FILE 指定工具链配置文件）。
sysroot
部分工具链已自带默认 sysroot，无需单独指定；如需自定义，请参考芯片厂商 SDK 文档。
系统依赖库
与目标架构匹配的 pthread、m、dl、z 等库版本，通常随交叉工具链一并提供。
说明：
不同芯片平台的交叉编译工具链配置差异较大，具体的工具链路径、-DCMAKE_TOOLCHAIN_FILE 配置方式请参考对应芯片平台 SDK 包内的 README 说明。

获取 SDK

前往 SDK & Demo 页面下载 SDK 包并解压。解压后得到以下内容：
tc_iot_sdk/
├── include/              # 全量 public API 头文件（tc_iot.h 等）
└── lib/
    └── libtc_iot_sdk.a    # SDK 静态库

创建项目

1. 新建项目目录，并将上一步下载解压得到的 tc_iot_sdk/ 目录拷贝到项目根目录下。
mkdir -p my_iot_project && cd my_iot_project
cp -r /path/to/tc_iot_sdk .
2. 项目目录结构如下：
my_iot_project/
├── CMakeLists.txt
├── main.c
└── tc_iot_sdk/
    ├── include/
    └── lib/libtc_iot_sdk.a

集成并引入 SDK

步骤 1：配置 CMakeLists.txt

在项目根目录创建 CMakeLists.txt，添加头文件搜索路径与静态库链接：
cmake_minimum_required(VERSION 3.10)
project(iot_quickstart_demo C)

set(CMAKE_C_STANDARD 99)

set(SDK_DIR ${CMAKE_CURRENT_SOURCE_DIR}/tc_iot_sdk)

add_executable(iot_quickstart_demo main.c)

target_include_directories(iot_quickstart_demo PRIVATE
    ${SDK_DIR}/include)

target_link_libraries(iot_quickstart_demo PRIVATE
    -Wl,--start-group ${SDK_DIR}/lib/libtc_iot_sdk.a -Wl,--end-group
    pthread m dl z)

步骤 2：引入头文件

在 main.c 中引入设备端登录相关头文件：
#include "tc_iot.h"      // 初始化 / 登录 / 登出

接入步骤

本节介绍如何调用 SDK 完成登录。

步骤 1：初始化 SDK

调用 tc_iot_init 完成 SDK 全局初始化：
#include <string.h>
#include "tc_iot.h"

tc_iot_config_s config;
memset(&config, 0, sizeof(config));
config.storage_path = "./";
config.log_level = TC_IOT_LOG_LEVEL_INFO;
config.on_log = NULL;
config.on_device_event = NULL;

tc_iot_error_e rc = tc_iot_init(&config);
if (rc != TC_IOT_ERR_SUCCESS) {
    printf("tc_iot_init failed: %d\\n", rc);
    return -1;
}

步骤 2：登录

调用 tc_iot_login 使用设备三元组完成登录鉴权，登录结果通过回调异步返回：
参数
类型
说明
product_id
const char *
产品 ID。
device_id
const char *
设备名称。
device_secret
const char *
设备密钥。
region
const char *
接入地域，如 ap-guangzhou。
static void on_login(tc_iot_error_e error_code, const char *error_message) {
    if (error_code == TC_IOT_ERR_SUCCESS) {
        printf("[demo] login success\\n");
    } else {
        printf("[demo] login failed: %d, msg=%s\\n", error_code,
               error_message ? error_message : "");
    }
}

tc_iot_device_info_s device_info;
device_info.product_id = "YOUR_PRODUCT_ID";
device_info.device_id = "YOUR_DEVICE_NAME";
device_info.device_secret = "YOUR_DEVICE_SECRET";
device_info.region = "ap-guangzhou";

rc = tc_iot_login(&device_info, on_login);
if (rc != TC_IOT_ERR_SUCCESS) {
    printf("tc_iot_login call failed: %d\\n", rc);
}

完整示例代码

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include "tc_iot.h"

static volatile int s_login_done = 0;
static tc_iot_error_e s_login_rc = TC_IOT_ERR_SUCCESS;

static void on_login(tc_iot_error_e error_code, const char *error_message) {
    s_login_rc = error_code;
    s_login_done = 1;
    if (error_code != TC_IOT_ERR_SUCCESS) {
        printf("[demo] login failed: %d, msg=%s\\n", error_code,
               error_message ? error_message : "");
    } else {
        printf("[demo] login success\\n");
    }
}

int main(int argc, char **argv) {
    if (argc < 7) {
        printf("Usage: %s -p <product_id> -d <device_id> -s <device_secret>\\n", argv[0]);
        return 0;
    }

    const char *product_id = NULL;
    const char *device_id = NULL;
    const char *device_secret = NULL;
    for (int i = 1; i < argc; i++) {
        if (strcmp(argv[i], "-p") == 0 && i + 1 < argc) {
            product_id = argv[++i];
        } else if (strcmp(argv[i], "-d") == 0 && i + 1 < argc) {
            device_id = argv[++i];
        } else if (strcmp(argv[i], "-s") == 0 && i + 1 < argc) {
            device_secret = argv[++i];
        }
    }
    if (!product_id || !device_id || !device_secret) {
        printf("device info error\\n");
        return 1;
    }

    // 1. 初始化 SDK
    tc_iot_config_s config;
    memset(&config, 0, sizeof(config));
    config.storage_path = "./";
    config.log_level = TC_IOT_LOG_LEVEL_INFO;

    tc_iot_error_e rc = tc_iot_init(&config);
    if (rc != TC_IOT_ERR_SUCCESS) {
        printf("tc_iot_init failed: %d\\n", rc);
        return 1;
    }

    // 2. 登录
    tc_iot_device_info_s device_info;
    device_info.product_id = product_id;
    device_info.device_id = device_id;
    device_info.device_secret = device_secret;
    device_info.region = "ap-guangzhou";

    rc = tc_iot_login(&device_info, on_login);
    if (rc != TC_IOT_ERR_SUCCESS) {
        printf("tc_iot_login call failed: %d\\n", rc);
        tc_iot_deinit();
        return 1;
    }

    int waited_ms = 0;
    while (!s_login_done && waited_ms < 5000) {
        usleep(100 * 1000);
        waited_ms += 100;
    }
    if (!s_login_done || s_login_rc != TC_IOT_ERR_SUCCESS) {
        printf("login timeout or failed\\n");
        tc_iot_deinit();
        return 1;
    }

    // 3. 释放资源
    tc_iot_logout();
    tc_iot_deinit();
    printf("[demo] main exit\\n");
    return 0;
}

编译并运行

1. 在项目根目录执行 CMake 编译。
cmake -B build
cmake --build build -j
2. 运行可执行文件，传入设备三元组。
./build/iot_quickstart_demo -p YOUR_PRODUCT_ID -d YOUR_DEVICE_NAME -s 'YOUR_DEVICE_SECRET'
3. 观察日志输出，出现以下内容代表登录成功。

您可以进入 物联网开发平台控制台，在实例下的设备详情页面查看设备状态。


常见问题

现象
排查建议
tc_iot_login 长时间无回调 / 超时
检查设备三元组是否正确、网络是否可达、本机系统时间是否准确。
编译报错找不到头文件
确认 CMakeLists.txt 中 target_include_directories 正确指向 tc_iot_sdk/include。
链接报错找不到符号
确认链接顺序使用了 -Wl,--start-group ... -Wl,--end-group 包裹静态库，且补齐了 pthread m dl z 系统库。

联系我们

如果您在接入或使用过程中有任何疑问或者建议，欢迎 联系我们 提交反馈。
中国站