Multi-Mode Gateway

The multi-mode gateway is a core board for gateway development. It can help you get acquainted with the development process on the Tuya IoT Development Platform as well as prototype your idea and build demo applications.

Overview

The multi-mode gateway is integrated with a Bluetooth module and a Zigbee module and uses the SSD202D TuyaOS production package, enabling you to build a smart gateway with no code. Without any adaptation, your gateway can connect to all sub-devices that use Bluetooth or Zigbee in the Tuya ecosystem.

Get development kit

Step 1: Install Tuya Wind IDE

Install Tuya Wind IDE that manages all the TuyaOS development kits and resources.

Step 2: Request type development kit

Click Resource Center on the left navigation pane. Search for a gateway type development kit and click Request Permission. Wait for the request to be approved.

• Development Mode: TuyaOS OS Development
• Type Development Kit: Gateway Development:Gateway Device Development Kit
• Development Platform: SoC/SigmaStar/Linux/SSD202D

Step 3: Download type development kit

After your permission request is approved, click Create Framework on the home page, select SSD202D, and click Download.

• Development Mode: TuyaOS OS Development
• Type Development Kit: Gateway Development:Gateway Device Development Kit
• Development Platform: SoC/SigmaStar/Linux/SSD202D

Step 4: Request product development kit

The type development kit includes the library, header, and example. You can request the product development kit for multi-mode gateway to perform custom development.

After you download the type development kit, click Dev Framework on the left navigation pane, find the latest package under the Product Dev Kit tab, and request permission. Wait for the request to be approved.

Step 5: Download product development kit

After your permission request is approved, download the product development kit.

The product development kit is downloaded to TuyaOS/apps.

Quick start

Directory

• The directory of the development kit:

  ├── hardware                  # Hardware documentation.
  ├── pc
  │    └── tools                # Development tools.
  ├── software
  │    ├── packages             # SDK package.
  │    ├── SDKInformation.json  # SDK information file.
  │    └── TuyaOS               # SDK directory.
  │        ├── apps             # The sample applications, which can be modified as needed.
  │        ├── build
  │        ├── build_app.sh     # The build script.
  │        ├── CHANGELOG.md
  │        ├── doc              # API reference.
  │        ├── include          # SDK header files.
  │        ├── libs             # SDK libraries. You can link them as needed.
  │        ├── LICENSE          # Tuya MIT License
  │        ├── Makefile
  │        ├── output           # The build output.
  │        ├── README.md
  │        ├── scripts
  │        └── vendor           # The toolchain. When you build a project, the toolchain is automatically downloaded to this directory.
  └── tuya.json
  

• The directory of TuyaOS > apps > demo:

  ├── application_components       # The open source gateway components.
  ├── application_drivers          # The open source gateway drivers.
  ├── app.mk
  ├── audio                        # The audio file.
  ├── build                        # The resources that should be included in the gateway project.
  ├── build.conf
  ├── build.sh                     # The build script.
  ├── doc                          # Documentation.
  ├── include                      # The header file.
  ├── key                          # The source code for buttons.
  ├── led                          # The source code for LEDs.
  ├── Makefile                     # The Makefiles used to build projects.
  ├── package.json
  ├── README.md                    # README
  └── src                          # The source code.
  

• The directory of TuyaOS > apps > demo > build:

  ├── board
  │    ├── audio_file              # The audio file.
  │    ├── keyname.txt             # The firmware key records, used for production testing.  After you change the name of the firmware key, be sure to document the change in this file. Note that the name of the firmware key is not the project name.
  │    ├── startup.sh              # The startup script. After startup, the system runs this script first. Do not edit this script unless necessary.
  │    └── unpack                  # The program to unpack the update package.
  ├── image
  │    ├── app_upgrade.sh          # The script to invoke when an OTA firmware update is initiated.
  │    ├── async_run.sh
  │    ├── config.json             # Gateway information configuration.
  │    ├── json_parser.sh
  │    ├── prod_upgrade.sh         # The script to invoke when a bulk update is initiated.
  │    ├── show_net_stat.sh        # Prints network status.
  │    ├── start_record.sh
  │    ├── tuya_start.sh           # Starts to run the gateway project.
  │    ├── tuya_user1
  │    │    ├── app_detect.sh        # Monitors the program running.
  │    │    ├── app_stop.sh          # Stops the gateway program.
  │    │    ├── config.json          # Gateway information configuration.
  │    │    ├── debugtool            # Debug the Zigbee network. For example, you can get the Zigbee network information.
  │    │    ├── log_detect.sh        # Monitors logging to archive and package logs.
  │    │    ├── process_monitor.sh      # Software watchdog to monitor the process.
  │    │    └── tuya_start_children.sh  # Starts up the main program.
  │    ├── udhcpc.script           # The DHCP script for wired connections.
  │    ├── udhcpd.conf             # The DHCP configuration for wired connections.
  │    └── wlan0_udhcpc.script     # Configures the DHCP for Wlan0.
  ├── image_create.sh              # Packages the QIO and OTA files, which will invoke the BSP packaging tool.
  ├── pack.sh                      # Packages projects.
  ├── rcp_image
  │    └── si_rcp_uart_mg21_OTA_1.4.3.bin   # RCP OTA firmware.
  └── third_image                   # Third-party open source packages.
  

The following tables list the description of important configurations for some scripts.

• app_upgrade.sh and prod_upgrade.sh

  Field	Description
  ncp_ver65_flag=“/tmp/ncp_ver65_1_1_9_flag”	Change this field according to the version of the network co-processor (NCP), which must match the NCP version specified in the ncp_image folder. Suppose that the NCP version is changed to 12.34.56. You should change this field to "/tmp/ncp_ver65_12_34_56_flag" accordingly. The host automatically generates a ncp_ver65_x_x_x_flag file in the /tmp directory based on the NCP version. When the script fails to match the ncp_ver65_flag field, it triggers an NCP update.
  ug_tool=/bin/unpack	The unpack program. It does not validate signatures by default. To enable signature validation, set it to -s and use it with the board support package (BSP) build parameter BUILD_ARG.

• tuya_start.sh

  Field	Description
  TY_ENV_USER_TMP_DIR=“/tmp”	The temporary directory, which can be changed as required.
  DEFULT_APP_RUN_DIR=“/tmp/tuya/”	The working directory, which can be changed as required.

• tuya_start_children.sh

  Field	Description
  TY_ENV_USER_LOG_DIR=“/tuya/data/log_dir”	The directory where logs are stored, which can be changed as required.
  TY_ENV_USER_STORAGE_DIR=“/tuya/data/user_data”	The directory where user information is stored, which can be changed as required.
  TY_ENV_USER_TMP_DIR=“/tmp”	The temporary directory, which can be changed as required, but should be consistent with that set in tuya_start.sh.
  TY_ENV_USER_BIN_DIR=“/tmp/tuya”	The working directory, which can be changed as required, but should be consistent with that set in tuya_start.sh.

• process_monitor.sh

  Field	Description
  PRO_MONITOR_MAX_NUM=6	The software watchdog timer. When the timer expires, the application is restarted every 20 seconds.

• image_create.sh

  Field	Description
  BUILD_ARG=	The BSP build parameters. This field is empty by default, meaning signing is not performed. -a: Cloud service-signed. -al: Local self-signed.

Configurations

Before you build a project, replace the value for PID with the PID of the gateway product you create on the Tuya IoT Development Platform.

The configuration file is stored in TuyaOS > apps > demo > build > image > tuya_user1 > config.json.

The following table describes the fields in config.json.

Format

 {
     "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> }, ... ]
     },
 }

Field description

• Common configurations:

  Field	Required	Description
  pid	Yes	The SDK runs in non-OEM mode. PID specifies the PID of the current device. In this demo, the PID is jaxsdzxvod99ueen.
  uuid	No	The universally unique identifier. The system reads UUID from the NVRAM first. If no UUID is found, the UUID specified here is used. For more information about NVRAM, see Back up authorization information.
  authkey_key	No	The authorization key. The system reads the authorization key from the NVRAM first. If no authorization key is found, the authorization key specified here is used. For more information about NVRAM, see Back up authorization information.
  ap_ssid	No	The SSID of the access point (AP) used for pairing in AP mode. If not specified, the default value is SmartLife-<the last four characters of the WLAN MAC>.
  ap_password	No	The password of the AP, defaulting to empty.
  log_level	No	The log level, defaulting to debug level (level 4).
  storage_path	Yes	The file storage path. The file system must be read/write.
  start_mode	No	The supported Wi-Fi pairing modes: WF_START_AP_ONLY: AP mode only. WF_START_SMART_ONLY: EZ mode (Wi-Fi Easy Connect) only. WF_START_AP_FIRST: Both AP mode and EZ mode are available, with AP mode taking priority. WF_START_SMART_FIRST: Both AP mode and EZ mode are available, with EZ mode taking priority. WF_START_SMART_AP_CONCURRENT: AP mode and EZ mode coexist.

• Configurations specific to Zigbee protocol:

  Field	Required	Description
  storage_path	Yes	The file storage path. The file system must be read/write.
  cache_path	Yes	A temporary directory to store cache files, such as OTA update files.
  dev_name	Yes	The name of the serial port.
  cts	Yes	Specifies whether to enable flow control. Tuya’s NCP has flow control enabled.
  thread_mode	Yes	1: Run the Zigbee host program in thread mode. 0: Run the Zigbee host program in process mode.

• Configurations specific to Bluetooth protocols:

  Field	Required	Description
  enable_hb	Yes	Specifies whether to enable heartbeat.
  scan_timeout	Yes	The scan timeout.
  mode	Yes	slave/master/mesh

  Parsing is implemented in user_iot_init. A sample code is provided for your reference.

Build

This section describes how to build THP23-X-D firmware with Visual Studio Code (VS Code).

1. Expand TuyaOS > apps. Right-click on the demo directory and choose Build Project. Enter a version number and press the Enter key.

   

2. You can see the output in the TERMINAL window. When the TERMINAL displays a message as shown below, it means the build is successful. The build output is stored in the output directory.

   

   Firmware description:

   • demo_fw_QIO_<version number>.bin: The production firmware that should be flashed to the entire flash memory with U-Boot. For more information, see the THP23-X-D QIO Firmware Flashing Guide.

   • demo_fw_UG_<version number>.bin: The OTA firmware update. You can upload this binary to the Tuya IoT Development Platform and deploy an OTA update to end devices.

   • demo_<version number>_debug: The main program that has the symbol table retained, which can be used for debugging with GDB.

   • gateway.tar.gz: The compressed archive of packages. You can use it for quick debugging. For more information, see Simple Debugging.

     If you use a 64-bit OS to build vendor applications, be sure to install the runtime libraries and compilation libraries for 32-bit.

Run

Run the sample application to see how it behaves.

You can flash the THP23-X-D board with the OTA firmware update. For more information, see Flash OTA firmware update. After flashing, restart the device.

THP23-X-D supports pairing over wired connection and pairing in AP mode. You can use the Smart Life app to activate the gateway. For more information about the app, see User Guide.

Update

For more information, see Update Firmware.

Log in via serial port

You can log in to the THP23-X-D backend using a serial port for development and debugging.

• Debugging serial port: UART_TX and UART_RX

• Baud rate: 115200

• Username: root

• Password: tygw@SSD20x

  If the default password does not work, submit a service ticket and provide the S/N.

Simple debugging

To perform an OTA firmware update, the flash memory is erased and written with the update file. Then, the system is restarted to make the update take effect. This is a time-consuming process. You can extract the gateway.tar.gz to the working directory and run the program manually. This can reduce debugging time.

1. Install TFTP Server on your computer and place gateway.tar.gz in the directory where TFTP Server resides.

2. Log in to the THP23-X-D backend using a serial port. For more information, see Log in via serial port.

3. In the THP23-X-D backend, run the following command to download the archive.

   	cd /tmp && tftp <tftp server IP address> -gr gateway.tar.gz
   

4. In the THP23-X-D backend, run the following command to stop the program.

   	/tmp/tuya/tuya_user1/app_stop.sh
   

5. In the THP23-X-D backend, run the following command to extract the archive.

   	cd /tmp && echo "tuya_start_dir=/tmp/tuya/tuya_user1" > /tmp/tuya/start.conf;tar -C /tmp/tuya -xvf gateway.tar.gz
   

6. In the THP23-X-D backend, run the following command to start the program.

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

   You can run ps to check if tyZ3Gw works properly.

7. In the THP23-X-D backend, run the following command to print real-time logs.

   	tail -f /tmp/tuya.log
   

Flash OTA firmware update

This section describes how to flash the THP23-X-D board with an OTA firmware update. You need to log in to the backend via serial port.

1. Install TFTP Server on your computer and place the update file in the directory where TFTP Server resides.

2. Log in to the THP23-X-D backend using a serial port. For more information, see Log in via serial port.

3. In the THP23-X-D backend, run the following command to download and install the firmware update.

   	cd /tmp && tftp <tftp server IP address> -g -l <firmware file name> && unpack -f <firmware file name>
   

4. After the update is installed, restart the device.

Flash full firmware

This section describes how to flash the THP23-X-D board with the full firmware. You need to log in to the backend via serial port to perform actions.

Back up data

To flash the firmware to the board, the flash memory is completely erased and written with the 128 MB QIO binary. Therefore, you need to back up the authorization information on the board and restore it after the firmware is flashed.

Back up authorization information

1. Run nvram show and copy the output to your computer.

2. After the firmware is flashed, run nvram set <key> <value> to write the authorization information.

3. Then, run nvram commit to write to the flash memory.

   Back up the following information:

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

Enter U-Boot mode

Log in to the backend and enable U-Boot.

Run nvram set persist.uboot.enter on && nvram commit and restart the device. During restart, press and hold the Enter key to go into the U-Boot mode.

Flash firmware

1. In the terminal, set the serverip (the IP address of your computer) and ipaddr (the IP address of your device, defaulting to 192.168.1.55). Run :pri to view IP addresses.

2. After you set setenv serverip xxxx and setenv ipaddr xxxx and connect an Ethernet cable to the device, enter ping. If ping xxxxx (your serverip) is alive, it means the network works fine.

3. Place demo_fw_QIO_<version number>.bin to the TFTP Server directory. Be sure you have enabled the Server service for TFTP and configure the IP address of your computer in the TFTP Setting.

   

4. In the terminal, enter tftp 0x21000000 demo_fw_QIO_<version number>.bin to upload the file. Be sure the file is successfully uploaded.

   

5. In the terminal, enter nand erase.chip.

6. In the terminal, enter nand write 0x21000000 0x0 ${filesize}.

7. Power off and on the gateway, or enter res in the terminal to restart the gateway.

   

It may take a while to complete firmware flashing.

Restore data

After you restart the device on successful flashing, you can restore data by writing the backup data to the flash memory.

Example:

# 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

Security settings

Security is an important consideration for gateways. In this demo, some settings are open for configuration to facilitate custom development.

Root password

The default password for the development board is tygw@SSD20x. To change the password, run echo root:password | chpasswd -m and replace the password with your own.

SSH

Enabling SSH can leave the system vulnerable to unauthorized access attempts and cyberattacks. It is recommended to disable SSH when remote login is not needed and modify the default port to protect your system.

Open build/board/startup.sh and comment out dropbear -p 22 so that the system will not launch SSH on startup. To enable SSH again, run this command. You can edit -p <port number> to define a port.

Executable

In the release build, the executable should be striped. In this demo, the executable has been striped with pack.sh.

U-Boot

• Run the following command to disable U-Boot.

  	nvram set persist.boot.enter off
  	nvram commit
  

• Run the following command to enable U-Boot.

  	nvram set persist.boot.enter on
  	nvram commit
  

Other recommendations

If your product is intended for commercial use, consider the following recommendations to enhance security.

• Deploy firmware updates via OTA using Tuya’s cloud service and validate the update file. Add and verify a custom signature.
• Remove the physical debug interfaces, such as JTAG and SWD. The development board has these interfaces removed. Take care of this when you design your PCB layout.
• Do not expose any sensitive data in logs, such as UUID, AUTHKEY, and passwords.
• Allow only Tuya’s services to use the local network port.
• Allow only Tuya’s services to access the device remotely.
• All network interaction data shall be uploaded to or downloaded from the server where the device is deployed, or the server in the country or region in compliance with applicable laws and regulations.
• Do not use local network services such as web server and Telnet.
• Do not include any hard-coded sensitive information in the firmware.

Get a non-generally available development kit

In Tuya Wind IDE, request access to a non-generally available development kit as instructed in the following figure.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.