Wi-Fi HomeKit General Solution

Tuya’s Wi-Fi HomeKit general solution allows your device that has an embedded MCU to be integrated with the Tuya Developer Platform and Apple HomeKit Platform. Your MCU can communicate with Tuya’s Wi-Fi module through serial communication so that your device can be connected to the cloud. Tuya provides one-stop services including network modules, mobile apps, and cloud services, to help you easily build an IoT-enabled product. Integration with HomeKit enables your product to be interconnected with all HomeKit-compatible products and controlled by using devices in Apple’s ecosystem.

How it works

Wi-Fi HomeKit module is connected to the cloud through a router without a gateway, which means you can provide users with fast and easy interaction with smart devices. The following block diagram shows how communication works.

Procedure

This section describes operations on the Tuya Developer Platform and considerations for development.

Step 1: Create product

This section provides important information you can use to create products on the Tuya Developer Platform. For more information, see the MCU Low-Code Development.

1. Log in to the Tuya Developer Platform and create a product.

2. Select the desired product that supports the HomeKit solution.

   

3. After you create a product, you can configure the function, panel, module, and firmware based on your requirements. Then, download the MCU SDK accordingly.

4. The platform recommends applicable Wi-Fi modules that adopt PCB antennas and common packagings, such as TYWE3SE and CR3L.

   

5. After you select the module and firmware, you can purchase modules online and proceed with the PCB layout. References:

   • TYWE1S Module Datasheet
   • TYWE1S Module
   The operating current of the module is within 100 mA on average but the peak current is more than 400 mA with a duration in microseconds. The consideration for electricity allowance is required in your circuit design.

Step 2: Test communication

Before proceeding with coding, you can use the MCU simulation mode of Tuya’s module debugging assistant to test the communication between the Wi-Fi HomeKit module and the MCU.

In the MCU simulation mode, the debugging assistant simulates the MCU and responds to the command from the module. After you pair the module with the mobile app, you can test whether the data point (DP) reporting and sending works properly. This section briefly describes how to test data communication by using the debugging assistant. For more information, see Module Debugging Assistant.

A step-by-step guide to test pairing.

1. Set up the peripheral circuit according to the minimal system schematics.

   If you want to perform a simple test, you can use the jump wire to set up the testing environment.

2. Open the debugging assistant and import the debugging file. Choose MCU Simulation and in the Protocol field, select Wi-Fi > HomeKit.

3. Connect the module to your computer by using a USB-to-TTL adapter. Set the Serial Port and Baud Rate. Click Open and then Start Debugging to start the data communication.

   • Before you start debugging, you must set the initial configuration such as product category, services, and features. Otherwise, you will be prompted with error messages.
   • During debugging, the module constantly sends heartbeats to the MCU after power-on. It will start initialization on receiving the correct response from the MCU. If the module does not send data after power-on, you should check whether the peripheral circuit of the module works as expected.

4. Reset the module to enter pairing mode.

   The module can be connected to the Tuya Developer Platform and the Apple HomeKit platform, hereinafter referred to as Tuya binding and HomeKit Accessory Protocol (HAP) binding respectively.

   Things to note:

   • Since Tuya binding and HAP binding are performed by using the Tuya Smart app and Apple’s Home app respectively, the Tuya account is isolated and independent of the Apple account.

   • A device that has been paired with the Tuya Smart app for Android still can be added to the Home app on the iPhone that is connected to the same LAN as is the Android phone.

   • Removing a device from the Tuya Smart app or the Home app will clear the binding status.

   • Resetting a device will clear the binding status and trigger restoring defaults. The device will enter pairing mode.

     • Tuya binding: cloud-based binding that only applies to pairing over Bluetooth. The mobile app initiates a binding request, and the device does not know which account it is to be bound with.

     • HAP binding: LAN-based binding. Both the mobile app and the device know their binding status.

   For more information about two Wi-Fi pairing modes, go to Help Center.

5. The following steps show how to pair a HomeKit device.

   Scan QR code with the Home app to pair a HomeKit device.

   1. Open the Home app and scan the setup code.

   2. Add the device to the Home app.

   3. Tap the setting icon on the control panel of the device.

   4. Navigate to the Tuya Smart app.

      

   Tuya Smart app discovers and binds a HomeKit device.

   1. Open the Home app. Tap Add Accessory to discover HomeKit devices.

   2. Select a device to add to Home.

   3. The device is added.

      

   Bind a HomeKit device with the Tuya Smart app.

   1. The device must have been added to the Home app.

   2. Open the Tuya Smart app and tap Me > HomeKit.

   3. Select the discovered HomeKit device and bind it.

      

   Discover a HomeKit device pending pairing with the Tuya Smart app.

   1. The Tuya Smart app can discover a HomeKit device by Bluetooth scanning and pair it. Tap a paired device and go to the control panel of a paired device and tap the pencil icon in the top right corner. Tap Add to Home to bind it with the Home app.
   2. Then the status of the Add to Home field will become Bound.
      

Step 3: Develop software

In the previous testing step, the left interface of Tuya’s debugging assistant shows you the data communication between the MCU and the module. For more information about communication logic, see the protocol documentation included in the development document.

• The basic protocol is product-neutral and shared by the modules. It consists of commands for module initialization and extended functions. For more information, see Wi-Fi HomeKit Serial Protocol.

• The function protocol works to report and send commands based on the basic protocol and specifies the DP data format.

Tuya provides two methods to implement the communication between your MCU and Tuya’s module.

• Interface with the protocol yourself

  If your MCU does not have sufficient resources or porting SDK is not feasible, you can interface the serial protocol yourself. For more information, see Wi-Fi HomeKit Serial Protocol.

• Port the MCU SDK

  If your MCU has sufficient resources, we recommend you port the MCU SDK for efficiency purposes. The MCU SDK is written in C language. You can directly import it to your project. The MCU SDK requires the following MCU hardware resources:

  • 4 KB flash memory.

  • About 100 bytes of the RAM are required, depending on the data length of the data point (DP). If you enable OTA updates, it must be greater than 260 bytes.

  • The 9-level nested function is adopted. The functions in the SDK can be your reference.

    For more information, see Port MCU SDK.

Step 4: Verify protocol

After you port the MCU SDK, you can use the module simulation mode in the debugging assistant to verify the code.

• In the module simulation mode, the debugging assistant automatically sends the initial data to the MCU to check whether the communication works properly. An error message will be returned if any issue occurs. After initialization, you can test different functions.

  The module simulation mode only verifies the communication between the MCU and the module and does not provide real networking capability. After finishing the test, you can connect the MCU to the actual module and test pairing functionality and specific features.

• In the MCU simulation mode, before you start debugging, you must complete the initial configuration on the debugging assistant such as the HomeKit device category, services, and functions. Otherwise, the initialization might fail.

  

Step 5: Test real devices

After the code is verified, you can pair the module with the app and test DP data communication.

You can query device logs by device ID on the Tuya Developer Platform. For more information, see Operation Management.