Thinker 鼾声检测示例
====================

功能说明
--------

本示例在 ARCS AP Core 上运行 Thinker 鼾声二分类模型，读取一个预量化的
``int8 [1, 1, 64, 64]`` 测试张量，输出 ``no_snoring`` 或 ``snoring``。
示例直接链接 Thinker 与 Luna，不依赖网络或 Host 侧 Python 环境。

硬件连接
--------

无需外部连接，Thinker、Luna、PSRAM 和外部 NOR Flash 均为开发板资源。默认
测试数据已经完成音频特征提取和量化，本示例不包含麦克风采集或音频预处理。

示例步骤
--------

1. 从外部 Flash 将 ``snoring_net_64x64_quant_arcs.bin`` 复制到 PSRAM。
2. 初始化 Luna、Thinker、DMA copy 和模型运行内存计划。
3. 从外部 Flash 读取 ``input_thinker.bin``，设置 ``int8 [1, 1, 64, 64]`` 输入张量。
4. 调用 ``tForward()`` 执行推理，并从 ``int8 [1, 2]`` 输出中选择最高分标签。
5. 输出两个类别的量化分数、推理耗时和最终检测结果。

资源布局
--------

.. list-table::
   :header-rows: 1

   * - 资源
     - Flash 偏移
     - 默认 XIP 地址
     - 大小
   * - ``lnn_thinker_snoring_net.bin``
     - ``0x000000``
     - ``0x30000000``
     - 不超过 1 MiB
   * - ``snoring_net_64x64_quant_arcs.bin``
     - ``0x100000``
     - ``0x30100000``
     - ``0xD48C0``
   * - ``input_thinker.bin``
     - ``0x200000``
     - ``0x30200000``
     - ``0x1000``

编译
----

.. include:: /sample_build.rst

烧录
----

构建时 CMake 会将模型和测试输入复制到 ``build/``，使用以下命令一次烧录三个镜像：

.. code-block:: bash

   ./tools/burn/cskburn -C arcs -s /dev/ttyACM0 -b 3000000 \
     0x0 build/lnn_thinker_snoring_net.bin \
     0x100000 build/snoring_net_64x64_quant_arcs.bin \
     0x200000 build/input_thinker.bin

烧录完成后设备自动复位；日志串口波特率为 921600。

预期输出
--------

.. code-block:: text

   [I][snoring_net] Thinker version: 3.0.10
   [I][snoring_net] memory plan: entries=... psram=... share=369152
   [I][snoring_net] model ready: inputs=1 outputs=1
   [I][snoring_net] scores: no_snoring=127 snoring=-128
   [I][thinker_snoring] snoring result: label=no_snoring score=127

核心 API
--------

.. list-table::
   :header-rows: 1

   * - API
     - 说明
   * - ``tGetMemoryPlan()``
     - 获取模型运行所需的 PSRAM 和 SHARE_MEM 内存计划。
   * - ``tModelInit()``
     - 从 PSRAM 中的模型资源创建 Thinker 模型。
   * - ``tCreateExecutor()``
     - 创建模型推理执行器。
   * - ``tGetInputInfo()``
     - 获取并校验输入张量类型和形状。
   * - ``tSetInput()``
     - 设置预量化的鼾声特征张量。
   * - ``tForward()``
     - 执行一次鼾声分类推理。
   * - ``tGetOutput()``
     - 获取两个类别的量化输出分数。

配置说明
--------

.. code-block:: kconfig

   CONFIG_THINKER_SNORING_NET_MODEL_ADDR=0x30100000
   CONFIG_THINKER_SNORING_NET_MODEL_SIZE=0xD48C0
   CONFIG_THINKER_SNORING_NET_INPUT_ADDR=0x30200000
   CONFIG_THINKER_SNORING_NET_INPUT_SIZE=0x1000
   CONFIG_THINKER_SNORING_NET_PSRAM_POOL_SIZE=0x10000
   CONFIG_THINKER_SNORING_NET_SHARE_POOL_SIZE=0x5A200

注意事项
--------

1. **输入格式**：模型只接受预量化 ``int8 [1, 1, 64, 64]`` 张量，不能直接输入 PCM 或 WAV 数据。
2. **类别顺序**：输出索引 0 为 ``no_snoring``，索引 1 为 ``snoring``。
3. **资源配套**：模型与测试输入必须来自同一量化流程，替换资源后应重新确认输入 scale 和预期输出。
4. **Flash 布局**：应用、模型和输入分别烧录，修改地址时必须同步更新 ``prj.conf`` 和烧录命令。
5. **共享内存**：模型需要 369152 字节 APRAM，减小 ``CONFIG_THINKER_SNORING_NET_SHARE_POOL_SIZE`` 会导致初始化失败。
6. **DMA channel**：示例固定使用算法 DMA channel，和其他业务组合时需要重新评估 DMA 占用。