Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dsyx/docs.silabs.com_zh/llms.txt

Use this file to discover all available pages before exploring further.

基于 Silicon Labs Connect 的应用程序不仅包含 Connect Stack,还包含 Connect Application Framework。该框架位于 Connect Stack 之上,使用经过 Silicon Labs 开发和测试的最佳实践状态机代码作为基础,与平台其他元素交互并提供应用层功能。框架通过协议栈处理程序接口向开发者公开更抽象的、特定于应用程序的接口,开发者可在其上添加自定义代码。

Connect Stack 与 Application Framework

与 GSDK v3.0 引入的平台架构保持一致,Connect Stack 和 Application Framework 均通过**组件(Component)**来提供可选的功能块。每个组件以独立预编译库或一组源代码的形式提供,通过 Project Configurator 安装/卸载,只需包含目标应用必需的功能。
初次使用 Connect 的开发者建议先阅读 QSG168: Proprietary Flex SDK v3.x Quick Start Guide。从 Connect v2.x 迁移至 v3.x 的开发者应参考 AN1254: Transitioning from the v2.x to the v3.x Proprietary Flex SDK

组件系统(Components)

GSDK v3.x 引入**组件库(Component Library)**机制,通过 Simplicity Studio 5(SSv5)的 Project Configurator > SOFTWARE COMPONENTS 选项卡进行管理,Connect 组件位于顶层”Connect”分组下。

MAC 和网络层组件

Stack Common

提供 Connect Stack 通用功能:15.4-like MAC 层、事件系统、动态内存分配和基础设施。还提供分配所有 sizable RAM 数据结构的栈配置文件。必须安装在所有 Connect 应用程序中。

Parent Support

提供父级特性:间接通信(与 Sleepy Device 通信)、子表(Coordinator 最大 64 项,Range Extender 最大 32 项)和路由表支持。应安装在 Coordinator 和 Range Extender 上;End Device 和 Direct/MAC Device 不应安装以节省资源。

AES Security

使节点能够使用 IEEE 802.15.4 mode-5-like 或 mode-5 MAC 加密/认证(通过 Mbed TLS)交换安全消息。利用 EFR32 设备上硬件加速的 AES 支持。仅在应用将使用 AES 安全性时安装。

Frequency Hopping

允许节点以伪随机方式快速切换信道进行通信,减少信道干扰并符合法规要求。详见 UG435.03: Architecture of the Silicon Labs Connect Stack v3.x

MAC Queue

提供动态内存分配,允许多个消息按提交顺序和/或优先级入队并尽快发送。未安装此组件时,Connect Stack 一次只能处理一个消息传输请求。

Application Framework 组件

服务端/客户端服务,允许客户端节点向服务端节点提交消息并从服务端检索消息。作为应用层协议(与 MAC 层的间接队列不同),Mailbox 支持更长的超时时间(默认 1 小时,可设置为数天),而间接队列的超时为 8-30 秒之间。MAC Mode 不支持此组件。
  • Mailbox Client:提交消息和检查收件箱
  • Mailbox Server:存储并转发消息
声明所有必需的应用程序框架全局变量,初始化 Connect Stack,并根据需要将协议栈回调分派给应用程序组件。所有 Connect 应用程序均应安装此组件。
管理 End Device 的定期轮询:
  • Long Poll(长轮询):普通 End Device 与父级保持的 keep-alive 机制,默认模式
  • Short Poll(短轮询):Sleepy End Device 轮询父设备获取传入数据包
// 切换轮询模式
emberAfPluginPollEnableShortPolling(true);  // 切换到短轮询
emberAfPluginPollEnableShortPolling(false); // 切换回长轮询
为 Connect Stack API 提供 IPC(进程间通信)。安装后协议栈在 Micrium OS 任务中运行,应用框架在独立任务中运行,通过 IPC 互相调用。详见 UG435.05: Using Micrium OS (RTOS) with Silicon Labs Connect v3.x
提供串行调试能力(从应用程序进行 printf-style 打印)的 API。
跟踪成功/失败的传输和接收数据包计数,提供协议栈数据包计数器功能。

Bootloader 相关组件

MAC Mode 不支持 OTA Bootloader 组件。
组件说明
OTA Bootloader Interface提供与 Gecko Bootloader 交互的 API(如切换到 bootloader 模式,读写 Flash)
OTA Broadcast Bootloader Server广播 OTA 服务端,向多个客户端分发映像
OTA Broadcast Bootloader Client广播 OTA 客户端,同时与多个客户端接收同一映像
OTA Unicast Bootloader Server单播 OTA 服务端,针对单个客户端
OTA Unicast Bootloader Client单播 OTA 客户端,从服务端接收映像
OTA Bootloader Test Common通用测试代码,包含外部 Flash CLI 命令
OTA Broadcast Bootloader Test广播专属测试功能与 CLI
OTA Unicast Bootloader Test单播专属测试功能与 CLI

非易失性存储(NVM)依赖

Connect 应用程序需要模拟非易失性存储支持(强烈推荐 NVM3):
方案Flash 需求Token 空间
SimEEv18 kB Flash2 kB Token 空间
SimEEv236 kB Flash8 kB Token 空间
NVM3(推荐)至少三个 Flash 页(可配置)可配置
Connect Stack 本身占用 47 字节 Token 空间。Coordinator/Range Extender 因 Parent Support 组件最多额外需要 704 字节(每个子级 11 字节,最多 64 个子级)。

回调机制(Callbacks)

每个组件在 Application Framework 上注册一个或多个回调,由应用程序实现(覆盖默认的弱定义存根)。回调是开发者在 Silicon Labs 框架之上添加自定义代码的位置。 GSDK v3 项目的主要入口点:
// app_init.c — 协议栈初始化结束时调用
void emberAfInitCallback(void) {
    // 应用程序初始化代码
}

// app_process.c — 从主循环周期性调用
void emberAfTickCallback(void) {
    // 应用程序主循环操作
}
协议栈回调通过 Application Framework 路由和分发,以下为消息接收回调的分发示例:
// gecko_sdk/protocol/flex/app-framework-common/app_framework_stack-cb.c
void emberIncomingMessageHandler(EmberIncomingMessage *message)
{
    emberAfIncomingMessage(message);           // 分发给组件使用
    emberAfIncomingMessageCallback(message);   // 分发给应用程序处理
}

实现组件回调示例

以安装 Mailbox Client 组件为例,Project Configurator 会提供以下回调原型供参考:
// 复制到 app_process.c 并实现业务逻辑
void emberAfPluginMailboxClientMessageSubmitCallback(
    EmberAfMailboxStatus status,
    EmberNodeId mailboxServer,
    EmberNodeId messageDestination,
    uint8_t tag)
{
    // 消息已提交至服务端的处理逻辑
}

void emberAfPluginMailboxClientMessageDeliveredCallback(
    EmberAfMailboxStatus status,
    EmberNodeId mailboxServer,
    EmberNodeId messageDestination,
    uint8_t tag)
{
    // 消息已投递的处理逻辑
}

void emberAfPluginMailboxClientCheckInboxCallback(
    EmberAfMailboxStatus status,
    EmberNodeId mailboxServer,
    EmberNodeId messageSource,
    uint8_t *message,
    uint16_t messageLength,
    uint8_t tag)
{
    // 检查收件箱的处理逻辑
}

事件框架(Events)

Connect Application Framework 提供了一个简单的事件调度程序,可将其视为回调机制的扩展,用于设置延迟或立即执行的事件,无需直接操作定时器。事件调度程序无法禁用,因为 Connect Stack 自身也使用此机制调度协议栈事件(如定期信标传输)。
Silicon Labs 强烈建议在 Connect 中使用事件而非定时器(除非需要严格的调度精度)。Connect 最多支持 256 个事件(受 EmberTaskId 类型限制),每个事件只需在 RAM 中分配一个 6 字节的 EmberEventControl

创建事件

// 在 app_process.c 中声明事件控制对象和回调
EmberEventControl myControl;

void myHandler(void) {
    // 事件处理逻辑
}
在运行时使用 emberAfAllocateEvent() 创建事件(包含在 Application Framework Common 组件中)。

调度事件

1

立即调度

// 尽快调度事件执行
emberEventControlSetActive(myControl);
2

延迟调度

// 延迟指定毫秒后调度
emberEventControlSetDelayMS(myControl, 1000); // 1 秒后执行
3

停用事件

// 停用事件,直到再次调度
emberEventControlSetInactive(myControl);

典型事件处理程序模式

void myHandler(void) {
    // 首先将事件设为非活动,防止重复触发
    emberEventControlSetInactive(myControl);

    EmberStatus status = someTaskToPerform();
    if (status != EMBER_SUCCESS) {
        // 任务失败,1 秒后重试
        emberEventControlSetDelayMS(myControl, 1000);
    }
}
事件回调函数一旦开始运行,将持续执行直到 return,不会emberEventControlSetDelayMS 中途停止(这与 RTOS 任务的行为不同)。回调函数应快速完成并合理管理下次调度。
完整事件 API 文档参见 docs.silabs.com/connect-stack/latest/group-event

Build docs developers (and LLMs) love