3. 产品使用

3.1 接口介绍和示例

3.1.1 接口定义

1. TYPE-C（外接USB输入）
2. 预留USB转串口输入
3. TP（电容触摸屏接口，6P/0.5mm)
4. 7.0寸屏接口（兼容50PIN和60PIN的屏）
5. 预留电阻式触摸屏接口（4P/1.0)
6. 预留电容触摸屏接口
7. 预留屏背光插件接口
8. 外接IO口
9. 预留喇叭接口
10. FLASH/8P外接插口
11. TF 卡座
12. 主控复位按钮
13. 预留UART口
14. 预留USB口
15. 预留UART口

3.1.2 示例

上位机 GT-HMI Designer 可下载示例，你可以下载相应的示例

3.2 开发环境搭建

3.2.1 开发搭建

3.2.2 资料下载

• GT-HMI-Builder

  git clone https://gitee.com/genitop/GT-HMI-Builder.git
  

• GT-HMI-Engine

  测试使用 commit 96f9974853afa49952bff69451afe94ebe33a265

  git clone https://gitee.com/genitop/GT-HMI-Engine.git
  

• Luban-lite SDK

  测试使用 commit 48769ed416a0918fa5afc3c9a66d9518532033f9

  git clone https://gitee.com/artinchip/luban-lite.git
  

3.2.3 工程创建

注意：7 寸屏demo 和 10寸屏demo 只有 packages\third-party\gt_hmi\demo 中的内容不一样，其他的都可以通过 me 进行配置

3.2.3.1 7 寸屏demo

• 将 GT-HMI-Builder 中 \GT-HMI-Builder\GT-HMI Module\GTC-480800TFT70GP-AC 7 寸屏内容拷贝到 Luban-lite SDK

  • 将 Target中的内容拷贝到 Luban-lite SDK 对应的路径中
  • 将 packages 中的内容拷贝到 Luban-lite SDK 对应的路径中

3.2.3.2 10.1寸屏demo

• 将 GT-HMI-Builder 中 \GT-HMI-Builder\GT-HMI Module\GTC-1024600TFT101GP-AC 10.1寸屏内容拷贝到 Luban-lite SDK

  • 将 Target中的内容拷贝到 Luban-lite SDK 对应的路径中
  • 将 packages 中的内容拷贝到 Luban-lite SDK 对应的路径中

3.2.3.3 GT-HMI-Engine

将 GT-HMI-Engine拷贝到 Luban-lite SDK \packages\third-party\gt_hmi 目录下

3.2.3.4 修改Kconfig文件

在 packages\third-party\Kconfig 文件最后加入

3.2.3.5 使用脚本实现以上步骤

#!/usr/bin/env bash
# setup_sdk.sh
#
# 用法（在目标工作目录中运行）：
#   bash setup_sdk.sh 7c      # 仅配置 7 寸屏 demo
#   bash setup_sdk.sh 101c    # 仅配置 10.1 寸屏 demo
#   bash setup_sdk.sh all     # 配置两种 demo（默认）
#
# 脚本与工程路径无关，clone 和拷贝均基于脚本运行时的当前工作目录

set -e

SCREEN="${1:-all}"
WORK_DIR="$(pwd)"

# -----------------------------------------------------------------------
# 目标路径（相对于脚本运行时的工作目录）
# -----------------------------------------------------------------------
PATH_7C="${WORK_DIR}/GT-HMI-Builder/GT-HMI Module/GTC-480800TFT70GP-AC"
PATH_101C="${WORK_DIR}/GT-HMI-Builder/GT-HMI Module/GTC-1024600TFT101GP-AC"
LUBAN_DIR="${WORK_DIR}/luban-lite"
ENGINE_SRC="${WORK_DIR}/GT-HMI-Engine"

# -----------------------------------------------------------------------
# 辅助函数
# -----------------------------------------------------------------------
copy_to() {
    local src="$1"
    local dst="$2"
    mkdir -p "$dst"
    if [ -d "$src" ]; then
        cp -r "$src/." "$dst/"
    else
        cp "$src" "$dst/"
    fi
}

# -----------------------------------------------------------------------
# 第一步：资料下载（git clone）
# -----------------------------------------------------------------------
echo "========================================"
echo " Step 1: 资料下载 (git clone)"
echo "========================================"

if [ ! -d "${WORK_DIR}/GT-HMI-Builder/.git" ]; then
    echo "[clone] GT-HMI-Builder ..."
    git clone https://gitee.com/genitop/GT-HMI-Builder.git "${WORK_DIR}/GT-HMI-Builder"
else
    echo "[skip]  GT-HMI-Builder 已存在，跳过 clone"
fi

if [ ! -d "${WORK_DIR}/GT-HMI-Engine/.git" ]; then
    echo "[clone] GT-HMI-Engine ..."
    git clone https://gitee.com/genitop/GT-HMI-Engine.git "${WORK_DIR}/GT-HMI-Engine"
else
    echo "[skip]  GT-HMI-Engine 已存在，跳过 clone"
fi

if [ ! -d "${WORK_DIR}/luban-lite/.git" ]; then
    echo "[clone] luban-lite SDK ..."
    git clone https://gitee.com/artinchip/luban-lite.git "${WORK_DIR}/luban-lite"
else
    echo "[skip]  luban-lite 已存在，跳过 clone"
fi

# -----------------------------------------------------------------------
# 第二步：工程创建 —— GT-HMI-Engine -> luban-lite
# -----------------------------------------------------------------------
echo ""
echo "========================================"
echo " Step 2: 拷贝 GT-HMI-Engine 到 luban-lite"
echo "========================================"

ENGINE_DST="${LUBAN_DIR}/packages/third-party/gt_hmi/GT-HMI-Engine"
if [ -d "$ENGINE_SRC" ]; then
    echo "[copy]  GT-HMI-Engine -> packages/third-party/gt_hmi/GT-HMI-Engine"
    mkdir -p "$ENGINE_DST"
    cp -r "${ENGINE_SRC}/." "$ENGINE_DST/"
else
    echo "[warn]  GT-HMI-Engine 目录不存在，跳过"
fi

# -----------------------------------------------------------------------
# 第三步：从 GT-HMI-Builder 拷贝 target / packages 到 luban-lite
# -----------------------------------------------------------------------
echo ""
echo "========================================"
echo " Step 3: 从 GT-HMI-Builder 拷贝模块文件"
echo "========================================"

setup_7c() {
    echo "--- 7 寸屏 demo ---"
    local src="${PATH_7C}"

    if [ ! -d "$src" ]; then
        echo "[warn]  7 寸屏路径不存在: $src"
        return
    fi

    if [ -d "${src}/target" ]; then
        echo "[copy]  target (7c) ..."
        copy_to "${src}/target" "${LUBAN_DIR}/target"
    fi

    if [ -d "${src}/packages" ]; then
        echo "[copy]  packages (7c) ..."
        copy_to "${src}/packages" "${LUBAN_DIR}/packages"
    fi
}

setup_101c() {
    echo "--- 10.1 寸屏 demo ---"
    local src="${PATH_101C}"

    if [ ! -d "$src" ]; then
        echo "[warn]  10.1 寸屏路径不存在: $src"
        return
    fi

    if [ -d "${src}/target" ]; then
        echo "[copy]  target (101c) ..."
        copy_to "${src}/target" "${LUBAN_DIR}/target"
    fi

    if [ -d "${src}/packages" ]; then
        echo "[copy]  packages (101c) ..."
        copy_to "${src}/packages" "${LUBAN_DIR}/packages"
    fi
}

case "$SCREEN" in
    7c)   setup_7c ;;
    101c) setup_101c ;;
    all)  setup_7c; setup_101c ;;
    *)
        echo "用法: bash setup_sdk.sh [7c|101c|all]"
        exit 1
        ;;
esac

echo ""
echo "Done. 接下来请在 OneStep 环境中执行："
echo "  cd luban-lite"
echo "  list          # 列出可用的 defconfig 方案，确认已拷贝的方案名称"
echo "  lunch <编号>   # 选择 defconfig 方案"
echo "  me            # 通过 menuconfig 进行配置"
echo "  m             # 编译"

• 脚本使用方式

  将 setup_sdk.sh 拷贝到需要建立的工程目录下，或者新建文件

sh setup_sdk.sh 7c      # 仅 7 寸屏
sh setup_sdk.sh 101c    # 仅 10.1 寸屏
sh setup_sdk.sh all     # 两者都配置（默认）

3.2.4 Luban-lite SDK 使用（Windows）

参考资料：https://aicdoc.artinchip.com/topics/product/d21x-quick-start-chapter-soc-quickstart-d21x.html

1、打开 luban-lite 文件夹下的 win_env.bat 文件

2、输入 list 列出可用方案

3、输入 lunch <编号> 选择方案

4、输入 me 通过 menuconfig 进行配置

5、输入 m 进行编译

• 常用命令

3.2.5 GT-HMI-Engine 配置说明

GT-HMI Engine 的配置通过 Luban-lite SDK 的 menuconfig（me 命令）完成，配置文件位于 packages/third-party/gt_hmi/Kconfig。

3.2.5.1 配置机制说明

配置传递方式：

• SConscript 直接解析 .config 文件，将 CONFIG_LPKG_GT_HMI_GT_XXX 转换为编译器宏 -DGT_XXX=value
• 这些宏通过 CPPDEFINES 传递给编译器，直接覆盖 gt_conf.h 中的默认值
• 只有带 #ifndef 保护的宏才能被 Kconfig 覆盖（如 GT_SCREEN_WIDTH），无保护的宏（如 GT_TASK_PERIOD_TIME_*）无法在 Kconfig 中配置

配置项命名规则：

• _EN 后缀（如 GT_SCREEN_WIDTH_EN）是控制开关，仅决定是否覆盖，不会传递给编译器
• 实际生效的是 GT_XXX 形式的宏（如 GT_SCREEN_WIDTH=800）

3.2.5.2 进入 GT-HMI 配置菜单

1. 在 OneStep 环境中运行 me 打开 menuconfig
2. 导航至：Third-party packages → GT-HMI: Genitop HMI Engine
3. 勾选 [*] GT-HMI: Genitop HMI Engine 启用引擎

3.2.5.3 Demo 选择

启用 Enable GT-HMI demo 后，可通过 choice 选择预置 demo：

Demo 相关扩展配置：

• Use demo-specific gt_font_config.h - 使用 demo 自定义字体配置
• Use demo-specific gt_gui_driver.h - 使用 demo 自定义驱动配置
• Use demo-specific gt_port_*.h - 使用 demo 自定义移植层文件

3.2.5.4 GT-HMI Engine 配置菜单（gt_conf.h）

3.2.5.4.1 Screen（屏幕配置）

3.2.5.4.2 Refresh（刷新配置）

3.2.5.4.3 Memory（内存配置）

3.2.5.4.4 Virtual file device（Flash 配置）

3.2.5.4.5 Input device（输入设备）

3.2.5.4.6 UI features（界面特性）

3.2.5.4.7 Extra buffers（额外缓冲区）

3.2.5.4.8 Font（字体配置）

3.2.5.4.9 Data source mode（数据源模式）

3.2.5.4.10 Image format（图片格式）

3.2.5.4.11 Serial communication（串口通信）

启用 GT_USE_SERIAL 后自动强制启用：GT_USE_CRC、GT_USE_BIN_CONVERT、GT_USE_FILE_HEADER、GT_INDEV_SIMULATE_POINTER。

3.2.5.4.12 Log（日志）

日志级别选项：

• VERBOSE (1) - 打印所有信息
• DEBUG (2)
• INFO (3)
• WARNING (4)
• ERROR (5) - 仅错误
• CRASH (6) - 仅崩溃

3.2.5.4.13 Utilities（工具）

3.2.5.5 配置注意事项

1. 仅配置带 #ifndef 保护的宏：Kconfig 只能覆盖 gt_conf.h 中带有 #ifndef 保护的配置项，无保护的宏（如 GT_TASK_PERIOD_TIME_*、GT_REFRESH_STYLE 等）无法在 Kconfig 中配置。

2. 宏定义传递机制：

   // gt_conf.h 中的典型模式
   #ifndef GT_SCREEN_WIDTH
       #define GT_SCREEN_WIDTH     800
   #endif
   

   当 Kconfig 启用 GT_SCREEN_WIDTH 并设置为 1024 时，SConscript 会生成 -DGT_SCREEN_WIDTH=1024，在编译时覆盖默认值。

3. GT_MEM_SIZE 特殊处理：该宏配置值单位为 KB，SConscript 会自动转换为字节（value*1024）。

4. 依赖关系：

   • 多点触控 (GT_USE_MULTI_TOUCH) 自动启用触摸队列 (GT_USE_TOUCH_QUEUE)
   • 串口通信 (GT_USE_SERIAL) 自动启用 CRC、BIN_CONVERT、FILE_HEADER、INDEV_SIMULATE_POINTER

3.2.6 Luban-lite SDK 屏幕和 TP 配置说明

屏幕（Display）和触摸板（Touch Panel，简称 TP）的配置通过 me menuconfig 完成，配置项位于 Hardware Drivers 菜单下。

3.2.6.1 屏幕配置（Display）

进入菜单：Hardware Drivers → Display Drivers

3.2.6.1.1 显示接口选择

3.2.6.1.2 RGB 接口配置

进入菜单：Display Drivers → RGB Configuration

3.2.6.1.3 Panel 选择

进入菜单：Display Drivers → Display Panels

Simple Panel（通用 RGB/LVDS 屏）：

• 选择 ArtInChip SIMPLE panel
• 可选标准分辨率：480x272、800x480、1024x600、1920x1080
• 或启用 Custom Display Timing 自定义时序

MIPI-DSI Panel：

• XM91080、ST7797、ST7703、ILI9881C、HX8394
• JD9365、AXS15231B、NV3051、FL7707、FT8201、ST7701S、JD9366TC

MIPI-DBI Panel：

• ILI9488、ILI9486L、ST7789、GC9B72NA（I8080 类型）
• ILI9341、ST77903、ILI9327、CO5300、ST77916、GC9108、ST77912（SPI 类型）

RGB Panel（需 SPI 初始化）：

• ST7701S、ST77916、JD9855、GC9A01A、NT35560、ST77922、ST7102

3.2.6.1.4 Framebuffer 配置

可选格式：ARGB8888、ABGR8888、XRGB8888、RGB888、RGB565、ARGB1555

3.2.6.1.5 背光控制

3.2.6.1.6 屏幕裁剪（Screen Crop）

当有效显示区域小于时序信号时使用：

3.2.6.2 触摸板配置（Touch Panel）

进入菜单：Hardware Drivers → Touch Drivers

3.2.6.2.1 启用触摸驱动

首先启用 Using touch（对应 CONFIG_AIC_USING_TOUCH=y）

然后选择触摸类型：

• Using CTP - 电容触摸屏（Capacitive Touch Panel）
• Using RTP - 电阻触摸屏（Resistive Touch Panel）

3.2.6.2.2 CTP（电容触摸屏）配置

选择 CTP 设备：

CTP 硬件连接配置：

CTP 坐标配置：

CTP 触摸方向调整：

CTP 裁剪与模式：

3.2.6.2.3 RTP（电阻触摸屏）配置

进入菜单：Hardware Drivers → Touch Drivers → Using RTP

3.2.6.3 屏幕与触摸配置示例

以 800x480 7 寸屏为例，典型配置如下：

defconfig 关键配置：

pinmux.c 引脚配置：

// RGB 24bit 引脚（PD.6 ~ PD.27，PC.0 ~ PC.5）
#ifdef AIC_PRGB_24BIT
    {3, PIN_PULL_DIS, 3, "PC.0"}, ... {3, PIN_PULL_DIS, 3, "PC.5"},
    {2, PIN_PULL_DIS, 3, "PD.6"}, ... {2, PIN_PULL_DIS, 3, "PD.27"},
#endif

// 触摸引脚
#ifdef AIC_USING_CTP
    {1, PIN_PULL_DIS, 3, AIC_TOUCH_PANEL_RST_PIN},
    {1, PIN_PULL_DIS, 3, AIC_TOUCH_PANEL_INT_PIN},
#endif

3.2.6.4 常见问题

1. 屏幕无显示

   • 检查 AIC_PRGB_24BIT / AIC_PRGB_16BIT_LD/HD 是否与硬件匹配
   • 确认背光引脚配置正确（GPIO/PWM 方式）
   • 检查 Panel 时序参数是否正确

2. 触摸无响应

   • 确认 I2C 通道和引脚配置正确
   • 检查复位引脚和中断引脚配置
   • 验证触摸坐标范围与屏幕分辨率匹配

3. 触摸位置偏移

   • 调整 AIC_TOUCH_X/Y_COORDINATE_RANGE 与实际触摸板分辨率一致
   • 使用 AIC_TOUCH_X/Y_FLIP 或旋转选项校准方向
   • 检查是否有 AIC_SCREEN_CROP 配置需要同步到触摸裁剪

3.2.7 Demo 配置

以下配置是在没有更改过工程其他配置情况下，每个demo的不同配置。

3.2.7.1 7c_vehicle demo 配置

3.2.7.2 7c_washing demo 配置

3.2.7.3 7c_pos demo 配置

3.2.7.4 101c demo 配置

3.2.8 程序下载（AiBurn）

工具下载：https://aicdoc.artinchip.com/topics/product/download-doc-tool-zip.html

使用介绍：https://aicdoc.artinchip.com/topics/tools/aiburn-ui-design.html

3.2.8.1 下载流程

• 选择 output\d21x_gt-hmi-nor_rt-thread_helloworld\images\d21x_gt_hmi_nor_v1.0.0.img

• 使用type-c线连接串口和USB口，串口配置：波特率-115200，停止位-1，数据位-8，校验位-None

• 按住板子上的复位和boot按键，然后只松开复位按键；或者使用串口发送 aicupg 指令，进入烧录模。AiBurn出现设备已连接

• 点击开始进行烧录

• 正在烧录

• 烧录完成