多模网关

更新时间:2024-02-27 02:33:45下载pdf

涂鸦 多模网关 是一款网关核心开发板,您可以用来熟悉 涂鸦 IoT 开发平台 接入的开发流程,提高后续产品开发效率。同时,也能作为产品预研阶段的快速验证,并快速搭建演示 DEMO。

产品详情

多模网关在硬件上集成了蓝牙模组和 Zigbee 模组,软件上使用 SSD202D TuyaOS 产物包,可零代码实现网关智能化。您无需任何适配,可接入涂鸦生态的所有 Zigbee 子设备和蓝牙子设备。

获取资料

第一步:安装 Tuya Wind IDE

TuyaOS 开发资料统一使用 Tuya Wind IDE 来管理,请按照指南安装 Tuya Wind IDE。

第二步:申请类型开发包

在资源中心上搜索多模网关的类型开发包,选择最新的版本,单击 申请权限。提交申请后,请耐心等待涂鸦审核。

多模网关

  • 开发模式:TuyaOS OS 开发
  • 类型开发包:网关开发/网关设备开发包
  • 开发平台:SoC/SigmaStar/Linux/SSD202D

第三步:下载类型开发包

收到审核通过的邮件后,在 Tuya Wind IDE 的主页单击 新建开发框架,选择 SSD202D 平台,单击 完成 进行下载。

多模网关

  • 开发模式:TuyaOS OS 开发
  • 类型开发包:网关开发/网关设备开发包
  • 开发平台:SoC/SigmaStar/Linux/SSD202D

第四步:申请产品开发包

类型开发包包含了库文件、头文件以及示例。可以申请多模网关的产品开发包,基于产品开发包进行二次开发,快速开发网关产品。

类型开发包下载后,进入 Tuya Wind IDE 的 开发框架 页面申请产品开发包,选择最新的版本,单击 申请权限。提交申请请求后,请耐心等待涂鸦审核。

多模网关

第五步:下载产品开发包

审核通过后,就可以下载产品开发包了。

多模网关

产品开发包会被下载到 TuyaOS/apps 目录下。

多模网关

快速开始

目录结构

  • 开发包整体目录结构如下:

    ├── hardware                  # 硬件手册,存放涂鸦自研硬件资料
    ├── pc
    │    └── tools                # 工具类目录,存放各种开发相关工具
    ├── software
    │    ├── packages             # SDK 压缩包
    │    ├── SDKInformation.json  # SDK 信息文件
    │    └── TuyaOS               # SDK 开发包目录
    │        ├── apps             # 应用示例代码目录,开发者可以根据需求修改
    │        ├── build
    │        ├── build_app.sh     # 编译脚本
    │        ├── CHANGELOG.md
    │        ├── doc              # API 文档
    │        ├── include          # SDK 头文件
    │        ├── libs             # SDK 库文件,开发者可以按需链接
    │        ├── LICENSE          # Tuya MIT License
    │        ├── Makefile
    │        ├── output           # 产物输出目录
    │        ├── README.md
    │        ├── scripts
    │        └── vendor           # 工具链,编译时会自动把工具链下载到该目录下
    └── tuya.json
    
  • TuyaOS > apps > demo 目录结构:

    ├── application_components       # 网关开源组件
    ├── application_drivers          # 网关开源驱动
    ├── app.mk
    ├── audio                        # 音频源码文件
    ├── build                        # 网关工程需要包含的资源
    ├── build.conf
    ├── build.sh                     # 编译脚本
    ├── doc                          # 说明文档
    ├── include                      # 源码头文件
    ├── key                          # 按键源码文件
    ├── led                          # LED 源码文件
    ├── Makefile                     # 编译 Makefile
    ├── package.json
    ├── README.md                    # README
    └── src                          # 源码文件
    
  • TuyaOS > apps > demo > build 目录结构:

    ├── board
    │    ├── audio_file              # 语音资源
    │    ├── keyname.txt             # 固件名称记录,用于模组产测,修改固件 key 名称后需要及时修改此文件记录内容。固件名称不是项目名称
    │    ├── startup.sh              # 启动脚本,系统启动后会先执行此脚本,一般不要修改
    │    └── unpack                  # 解压升级包程序
    ├── image
    │    ├── app_upgrade.sh          # 当 OTA 时会调用此脚本
    │    ├── async_run.sh
    │    ├── config.json             # 网关信息配置
    │    ├── json_parser.sh
    │    ├── prod_upgrade.sh         # 当使用批量升级工具升级时会调用此脚本
    │    ├── show_net_stat.sh        # 打印显示一些网络状态
    │    ├── start_record.sh
    │    ├── tuya_start.sh           # 开始运行网关工程
    │    ├── tuya_user1
    │    │    ├── app_detect.sh        # 监控程序是否运行
    │    │    ├── app_stop.sh          # 网关程序停止
    │    │    ├── config.json          # 网关信息配置
    │    │    ├── debugtool            # 对 Zigbee 的调试工具,可以获取如 Zigbee 网络信息
    │    │    ├── log_detect.sh        # 日志监控脚本,对日志进行归档打包
    │    │    ├── process_monitor.sh      # 软件看门狗监控程序
    │    │    └── tuya_start_children.sh  # 主程序启动
    │    ├── udhcpc.script           # 有线 dhcp 脚本
    │    ├── udhcpd.conf             # 有线 dhcp 配置
    │    └── wlan0_udhcpc.script     # 对 wlan0 的 dhcp 配置
    ├── image_create.sh              # QIO 和 OTA 打包脚本,将会调用 BSP 打包工具
    ├── pack.sh                      # 工程打包脚本
    ├── rcp_image
    │    └── si_rcp_uart_mg21_OTA_1.4.3.bin   # RCP OTA 固件
    └── third_image                   # 第三方开源包
    

以下为重要脚本中一些比较关键配置的详细说明:

  • app_upgrade.shprod_upgrade.sh

    字段
    说明
    ncp_ver65_flag=“/tmp/ncp_ver65_1_1_9_flag” 应该根据 NCP(Network Co-Processor)芯片使用版本进行修改,和 ncp_image 文件夹内 NCP 版本匹配,比如 NCP 版本变更为 12.34.56,则字段需要修改为 "/tmp/ncp_ver65_12_34_56_flag"。Host 会在 /tmp 目录下根据 NCP 版本自动生成 ncp_ver65_x_x_x_flag 文件,当脚本无法匹配到 ncp_ver65_flag 字段时,会执行 NCP 升级。
    ug_tool=/bin/unpack 解包程序,默认不验签,-s 验签(搭配 BSP 编译参数 BUILD_ARG 使用)
  • tuya_start.sh

    字段
    说明
    TY_ENV_USER_TMP_DIR=“/tmp” 临时目录,按照实际修改
    DEFULT_APP_RUN_DIR=“/tmp/tuya/” 运行目录,按照实际修改
  • tuya_start_children.sh

    字段
    说明
    TY_ENV_USER_LOG_DIR=“/tuya/data/log_dir” 日志存储文件夹,按照实际修改
    TY_ENV_USER_STORAGE_DIR=“/tuya/data/user_data” 用户信息存储文件夹,按照实际修改
    TY_ENV_USER_TMP_DIR=“/tmp” 临时目录,按照实际修改,应该和 tuya_start.sh 中的保持一致
    TY_ENV_USER_BIN_DIR=“/tmp/tuya” 运行目录,按照实际修改,应该和 tuya_start.sh 中的保持一致
  • process_monitor.sh

    字段
    说明
    PRO_MONITOR_MAX_NUM=6 软件看门狗失败阈值,当达到此值后执行重启应用程序,每次间隔 20 秒
  • image_create.sh

    字段
    说明
    BUILD_ARG= BSP 编译参数,默认为空不加签,-a 云服务加签,-al 本地自定义加签(详见 BSP doc)

配置

在编译固件之前,您需要修改一下配置,把 PID 修改成在 涂鸦 IoT 开发平台 创建的网关产品 PID。

配置文件位于 TuyaOS > apps > demo > build > image > tuya_user1 > config.json

多模网关

配置文件 config.json 详细解析如下:

基本格式

 {
     "pid": <xxx>,
     "uuid": <...>,
     "authkey_key": <...>,
     "ap_ssid": <... optional>,
     "ap_password": <... optional>,
     "log_level": <level>,
     "storage_path": <...>,
     "start_mode": <xxxx>,
     "tuya": {
         "zigbee": {
                       "storage_path": <xxx, string>,
                       "cache_path": <xxx, string>,
                       "dev_name": <xxx, string>,
                       "cts": <xxx, number>,
                       "thread_mode": <xxx, number>
         },
         "bt": {
                   "enable_hb": <xxx, number>,
                   "scan_timeout": <xxx, number>,
                   "mode": <xxx, number>
         }
     },
     "user": {
         [ { "tp": <DEV_ATTACH_MOD_X, number>, "sw_ver": <version, string> }, ... ]
     },
 }

字段解析

  • 公共配置部分:

    字段
    必须 说明
    PID SDK 运行在非 OEM 模式,PID 字段指定此设备 PID,本 Demo 的 PID 为: jaxsdzxvod99ueen
    uuid 唯一识别码,优先从 NVRAM 读取,不存在时使用此处。关于 NVRAM 操作参考 备份授权信息
    authkey_key 授权识别码,优先从 NVRAM 读取,不存在时使用此处。关于 NVRAM 操作参考 备份授权信息
    ap_ssid 热点配网 SSID,未指定则使用默认 SmartLife-<WLAN MAC 后四位>
    ap_password 热点配网密码,默认为空
    log_level 日志等级,默认为 debug 级 4
    storage_path 文件存储路径,需要可读写文件系统
    start_mode Wi-Fi 配网模式,支持以下类型:
    • WF_START_AP_ONLY:仅支持 热点(AP)配网
    • WF_START_SMART_ONLY:仅支持快连(EZ)配网
    • WF_START_AP_FIRST:支持 AP 和 EZ 配网,热点配网优先
    • WF_START_SMART_FIRST:支持 AP 和 EZ 配网,EZ 配网优先
    • WF_START_SMART_AP_CONCURRENT: AP 和 EZ 配网共存模式
  • Zigbee 协议配置部分:

    字段
    必须 说明
    storage_path 文件存储路径,需要可读写文件系统
    cache_path 临时目录,用于文件缓存,如 OTA 文件
    dev_name 串口名称
    cts 是否开启流控,涂鸦 NCP 均开启了流控
    thread_mode
    • 1:线程模式运行 Zigbee host 程序
    • 0:进程默认运行 Zigbee host 程序
  • 蓝牙协议配置部分:

    字段
    必须 说明
    enable_hb 是否使能心跳
    scan_timeout 扫描超时时间
    mode slave/master/mesh

    解析部分在 user_iot_init 中实现,可自行参考代码。

编译

本小节将会介绍在 VSCode 上编译 THP23-X-D 固件。

  1. 展开开发包的 TuyaOS > apps 目录,选择 demo 目录,并单击右键,在菜单中选择 Build Project,再输入版本号按下回车键,开始编译。

    多模网关

  2. 观察 VSCode 下方的 终端,会看到编译的输出打印。直到看到如下图所示打印时,代表编译成功,生成的固件位于 output 目录下。

    多模网关

    固件说明:

    • demo_fw_QIO_<版本号>.bin:全量固件,用于整片 Flash 烧录,需要进入 U-boot 进行烧录,详见《THP23-X-D QIO 烧录指南.pdf》。

    • demo_fw_UG_<版本号>.bin:OTA 固件,用于固件升级,可以上传到涂鸦 IoT 开发平台进行远程 OTA 升级。

    • demo_<版本号>_debug:保留符号表的主程序,用于 GDB 调试等场景。

    • gateway.tar.gz:程序包的压缩包,用于临时调试,可以加速调试进程,详见 简易调试 章节。

      在编译 vendor 时候,64 位系统需要安装 32 位运行库和编译库。

运行

前置工作基本完成了,接下来您可以运行示例程序,查看效果。

您可以把 OTA 固件烧录到 THP23-X-D 开发板上,详见 OTA 烧录。烧录完成后,断电重启设备。

THP23-X-D 支持有线配网和热点配网,您可以用涂鸦智能 App 来激活网关,App 详细教程请参考 使用指南

上传 OTA 固件

详细步骤请参考文档 固件升级

串口登录

您可以通过串口方式登录到 THP23-X-D 开发板后台,便于开发调试。

  • 调试串口为 UART_TXUART_RX

  • 串口默认波特率为 115200

  • 用户名为 root

  • 默认密码为 tygw@SSD20x

    若默认密码不正确,请联系 提交工单 涂鸦客户支持,提供 S/N。

简易调试

由于 OTA 固件升级需要擦除和写入 Flash,并且需要重启系统才能生效,在开发调试过程比较消耗时间。因此,您可以使用 gateway.tar.gz 将程序解压缩到运行目录,手动运行程序,这样可以方便您进行调试,节省开发时间。

  1. 电脑安装 TFTP Server,并将 gateway.tar.gz 放在 TFTP Server 的目录下。

  2. 通过串口方式登录到 THP23-X-D 后台,详见 串口登录

  3. 在 THP23-X-D 后台执行压缩包下载命令:

    cd /tmp && tftp <tftp 服务器 IP 地址> -gr gateway.tar.gz
    
  4. 在 THP23-X-D 后台执行停止程序命令:

    /tmp/tuya/tuya_user1/app_stop.sh
    
  5. 在 THP23-X-D 后台执行压缩包解压命令:

    cd /tmp && echo "tuya_start_dir=/tmp/tuya/tuya_user1" > /tmp/tuya/start.conf;tar -C /tmp/tuya -xvf gateway.tar.gz
    
  6. 在 THP23-X-D 后台执行启动程序命令:

    /tmp/tuya/tuya_start.sh /tmp/tuya
    

    程序启动后,可以执行 ps 命令观察 tyZ3Gw 程序是否运行。

  7. 在 THP23-X-D 后台执行实时日志打印命令:

    tail -f /tmp/tuya.log
    

OTA 烧录

本小节将会介绍如何在 THP23-X-D 开发板烧录 OTA 固件,需要通过串口登录到后台,登录方法请参见 串口登录

  1. 电脑安装 TFTP Server,并将 OTA 固件放在 TFTP Server 的目录下。

  2. 通过串口登录到 THP23-X-D 后台,详见 串口登录

  3. 在 THP23-X-D 后台执行固件下载和升级命令:

    cd /tmp && tftp <tftp 服务器 IP 地址> -g -l <固件文件名> && unpack -f <固件文件名>
    
  4. 升级完成后断电重启。

全量烧录

本小节将会介绍如何在 THP23-X-D 开发板烧录全量固件。烧录全量固件需要在串口以下操作均在 THP23-X-D 后台完成,需要通过串口登录到后台,登录方法请参见 串口登录

数据备份

烧录全量固件将会把整片 Flash 擦除,然后写入 128MB QIO 固件。所以,在烧录之前,您要把开发板上的授权信息进行备份,待烧录完成后,把数据进行恢复。

备份授权信息

  1. 执行 nvram show,把打印的信息拷贝备份到电脑上。

  2. 烧录完固件后要通过 nvram set <key> <value> 命令写入。

  3. 写入完成后执行 nvram commit 写入 Flash。

    需要备份以下 key 的内容:

    • country
    • AUTHKEY
    • slave_mac1
    • bsn
    • master_mac
    • UUID

进入 UBoot

默认是禁用进入 UBoot 的,需要先登录到开发板的后台把运行进入 UBoot 标志打开。

执行 nvram set persist.uboot.enter on && nvram commit,然后断电重启,在重启过程不停地按 Enter 键,就会进入 UBoot。

多模网关

固件烧录

  1. 终端上要设置 serverip(电脑 IP)和 ipaddr(设备 IP,默认是 192.168.1.55),终端输入 :pri 可以看到当前的 IP 情况。

  2. 输入 setenv serverip xxxxsetenv ipaddr xxxx 后,网线插上后,输入 ping 指令,ping xxxxx(设置的 serverip),出现 alive,说明网络通畅。

  3. demo_fw_QIO_<版本号>.bin 放到 TFTP 的路径下(TFTP 开启 Server 服务,并且在 Setting 里面已绑定 TFTP 到电脑服务端 IP)。

    多模网关

  4. 终端输入 tftp 0x21000000 demo_fw_QIO_<版本号>.bin 上传,务必确认上传 100% 成功。

    多模网关

  5. 终端输入 nand erase.chip

  6. 终端输入 nand write 0x21000000 0x0 ${filesize}

  7. 网关重新上电,或者在终端输入 res 重启设备。

    多模网关

    多模网关

全量固件烧录较久,请耐心等待烧录完成,烧录完成断电重启即可。

数据恢复

全量固件烧录完成并重启后,最后一个步骤是把在 数据备份 章节备份的数据重新写入到 Flash。

示例:

# nvram set country CN
# nvram set AUTHKEY h8eHMxNGVCUxzsKLCd2cmgAgFwI6OUaY
# nvram set slave_mac1 105a17f3cc2b
# nvram set bsn JDCJ30UTU00009
# nvram set master_mac 105a17f3cbf2
# nvram set UUID 1420ee8d85e3a146
# nvram commit

安全设置

作为网关,安全是十分重要的,本 Demo 出于二次开发的方便,会开放一些限制,供您自行设置。

建议您后续对 Demo 中的安全选项进行修改。

root 密码

开发板默认密码为 tygw@SSD20x,建议及时修改 root 密码,修改指令为:echo root:password | chpasswd -m,将 password 替换为自定义密码即可。

SSH

SSH 的开启可能会遭受到骇客的远程试探和攻击。不使用远程登录时,建议关闭 SSH,并且修改默认端口,都可以起到一定的防范作用。

打开 build/board/startup.sh 文件,将 dropbear -p 22 注释,系统启动时就不会自动开启 SSH,需要开启时执行此命令即可。通过修改 -p <端口号> 来自定义端口。

可执行程序

release 版的可执行程序应该是经过 strip 的,本 Demo 中,已在 pack.sh 对可执行程序进行了 strip。

U-Boot

在不使用的情况下,建议关闭 U-Boot。

  • 关闭设置:

    nvram set persist.boot.enter off
    nvram commit
    
  • 打开设置:

    nvram set persist.boot.enter on
    nvram commit
    

其它安全建议

除以上方法,在商用时建议还进行以下安全方法补充:

  • 通过涂鸦的云服务对设备进行 OTA 升级,且 OTA 固件进行校验。您也可对固件自定义加签解签。
  • 移除物理调试接口,如 JTAG/SWD 等。开发板已经进行了移除,如自行打板请注意此项。
  • 日志信息中不包含任何敏感数据,例如 UUID、AUTHKEY、密码等。
  • 无涂鸦服务之外的本地网络端口占用。
  • 无涂鸦服务之外的远程网络服务访问。
  • 所有网络交互的数据,仅限上传至/下载自设备所在或法律允许的国家/地区的服务器。
  • 无 web server、telnetd 等本地网络服务。
  • 固件内不包含硬编码的敏感信息。

如何申请白名单

在 TuyaOS Wind IDE 插件中,按以下步骤申请:

多模网关

支持与帮助

在开发过程遇到问题,您可以登录 TuyaOS 开发者论坛 网关中控开发版块 进行沟通咨询。