From a6be80435ebc7608010394ca04b598eb87df08f2 Mon Sep 17 00:00:00 2001 From: "Yoda.ou" Date: Sun, 25 Apr 2021 15:25:29 +0800 Subject: [PATCH] update md file. --- README.md | 70 ++++++++++++++++--------- README_zh.md | 145 --------------------------------------------------- 2 files changed, 44 insertions(+), 171 deletions(-) delete mode 100644 README_zh.md diff --git a/README.md b/README.md index ef0c3b73..7141a641 100644 --- a/README.md +++ b/README.md @@ -13,27 +13,22 @@ Tuya Homebridge Plugin -https://www.npmjs.com/package/homebridge-tuya-platform +Homebridge custom plugin for controlling Powered by Tuya (PBT) devices in HomeKit, it's based on [Tuya Open API](https://developer.tuya.com/en/docs/cloud/?_source=github). The plugin is officially maintained by the Tuya Developer Team. -[中文版](README_zh.md) | [English](README.md) + -## What is HomeKit? - -HomeKit is Apple's smart home platform introduced in 2014. It allows users of Apple devices to securely and easily control any devices with a 'Works with Apple HomeKit' badge, such as lights, door locks, thermostats, outlets, and many more. - -## What is Homebridge? +## Supported Tuya Device Types -Homebridge is a lightweight NodeJS server you can run on your home network that emulates the iOS HomeKit API. It supports plugins that provide a basic bridge from HomeKit to various third-party APIs provided by manufacturers of smart home devices. We recommend you check the [Homebridge](https://github.com/homebridge/homebridge/blob/master/README.md) before getting started with Homebridge plugins. +The following Tuya Device types are currently supported by this plugin: -## Users - -If you are a smart home geek and have a bundle of devices from different platforms, this step-by-step tutorial will help you make devices HomeKit-enabled and then develop Tuya Homebridge plugins. +- [Light](https://github.com/tuya/tuya-homebridge/blob/master/lib/light_accessory.js): Supports Tuya WiFi light devices +- [Switch](https://github.com/tuya/tuya-homebridge/blob/master/lib/outlet_accessory.js): Supports Tuya WiFi switch devices ## Preparation ### Registration -Please check [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuya-android-iot-app-sdk-sample/blob/activator_tool/Tuya_IoT_Platform_Configuration_Guide.md) to register an account on the [Tuya IoT Platform](https://iot.tuya.com?_source=github), and get the required information. Basically, you need to create a Cloud project and complete the configuration of asset, user, and application. Then, you will get the username, password, Access ID, and Access Secret. +Please check [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuya-android-iot-app-sdk-sample/blob/activator_tool/Tuya_IoT_Platform_Configuration_Guide.md) to register an account on the [Tuya IoT Platform](https://iot.tuya.com?_source=github), and get the required information. You need to create a Cloud project and complete the configuration of asset, user, and application. Then, you will get the **username**, **password**, **Access ID**, and **Access Secret**. ### Hardware Preparation @@ -52,12 +47,13 @@ Please check [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuy ## Quick Start -1. Open the Terminal. +**1.** Open the Terminal. + + Terminal - Terminal +**2.** Check the [Homebridge](https://github.com/homebridge/homebridge/blob/master/README.md) and install Homebridge in your system. -1. See the [Homebridge](https://github.com/homebridge/homebridge/blob/master/README.md) and install Homebridge on your system. -2. Install Tuya Homebridge plugin. +**3.** Install Tuya Homebridge plugin. > **Note**: If you encounter any problems with the installation, you may need to preface this command with `sudo` to make it run as an administrator. @@ -67,30 +63,40 @@ Please check [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuy ``` 2. Wait for the plugin to install and check whether the installation is successful. For more information, see the video below. - [![asciicast](https://asciinema.org/a/t6GY37mDPbfeG6AXVxuwROBlC.svg)](https://asciinema.org/a/t6GY37mDPbfeG6AXVxuwROBlC?autoplay=1) + [](https://asciinema.org/a/t6GY37mDPbfeG6AXVxuwROBlC?autoplay=1) ## Configuration -Before use, you need to configure the `config.json` file in the Homebridge plugin. +You need to configure the `config.json` file in the Homebridge plugin. + +**1.** Go to the directory `homebridge-tuya-platform`. + -1. Go to the directory `homebridge-tuya-platform`. ``` cd ./node_modules/homebridge-tuya-platform ``` -2. Go to the directory `config`. +**2.** Go to the directory `config`. + + ``` cd ./config ``` -3. Edit the `config.json` file. + +**3.** Edit the `config.json` file. + + ``` vim config.json ``` -4. In `options`, enter the `username`, `password`, `accessId`, and `accessKey` that you get from the [Tuya IoT Platform](https://iot.tuya.com/). The `lang` defaults to `en`. The `endPoint` is the domain name of the currently used [Tuya Open API](https://developer.tuya.com/en/docs/cloud/?_source=github). - Edit registration information + +**4.** In the `options` part, enter the `username`, `password`, `accessId`, and `accessKey`, which you can follow the **Configure Cloud Development Project** part in [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuya-android-iot-app-sdk-sample/blob/activator_tool/Tuya_IoT_Platform_Configuration_Guide.md) to get. + +The `lang` value can set `en` as default and the `endPoint` is the domain name of the currently used [Tuya Open API](https://developer.tuya.com/en/docs/cloud/?_source=github). +Edit registration information -5. Save and exit. +**5.** Save and close the file. ## Start Tuya Homebridge Plugin @@ -102,7 +108,8 @@ Before use, you need to configure the `config.json` file in the Homebridge plugi ``` homebridge -D -U ./config/ -P ./ ``` - [![asciicast](https://asciinema.org/a/2gaFGeKXZtEF1pmOhqTG41M30.svg)](https://asciinema.org/a/2gaFGeKXZtEF1pmOhqTG41M30?autoplay=1) + + [](https://asciinema.org/a/2gaFGeKXZtEF1pmOhqTG41M30?autoplay=1) ## Bridge to HomeKit @@ -112,7 +119,7 @@ Open the Home app on your Apple device. Pair with Homebridge by scanning the QR Fork Tuya's Homebridge repo in GitHub and follow the step-by-step tutorial to start the plugin service. -### Set up development environment +### Set up the development environment ``` —-VSCode @@ -171,6 +178,17 @@ For more info, please check the [Tuya Open API docs](https://developer.tuya.com/ - `addMessageListener(listener)`: Adds callbacks. - `removeMessageListener(listener)`: Removes callbacks. +## What is HomeKit? + +HomeKit is Apple's smart home platform introduced in 2014. It allows users of Apple devices to securely and easily control any devices with a 'Works with Apple HomeKit' badge, such as lights, door locks, thermostats, outlets, and many more. + +## What is Homebridge? + +Homebridge is a lightweight NodeJS server you can run on your home network that emulates the iOS HomeKit API. It supports plugins that provide a basic bridge from HomeKit to various third-party APIs provided by manufacturers of smart home devices. We recommend you check the [Homebridge](https://github.com/homebridge/homebridge/blob/master/README.md) before getting started with Homebridge plugins. + +## Users + +If you are a smart home geek and have a bundle of devices from different platforms, this step-by-step tutorial will help you make devices HomeKit-enabled and then develop Tuya Homebridge plugins. ## Feedback diff --git a/README_zh.md b/README_zh.md deleted file mode 100644 index 92dc1250..00000000 --- a/README_zh.md +++ /dev/null @@ -1,145 +0,0 @@ -Tuya-Homebridge -======================== - -[中文版](README_zh.md) | [English](README.md) - -## 什么是 HomeKit -HomeKit 是苹果 2014 年发布的智能家居平台。借助 HomeKit，用户可以使用苹果设备控制家里所有标有“Works with Apple HomeKit”（兼容 Apple HomeKit）的设备。这些设备包括灯、锁、恒温器和智能插头等。 - -## 什么是 HomeBridge -HomeBridge 是一个轻量级的 NodeJS 服务器，可以在家庭网络上运行。它模拟了 iOS HomeKit API，支持 HomeBridge 插件，提供了各种第三方智能家居设备 API 和 HomeKit 之间的桥梁。 -您可以轻松地通过 HomeBridge 来把第三方智能设备接入 HomeKit。在使用和开发 HomeBridge 插件之前，建议查看 [HomeBridge](https://github.com/homebridge/homebridge/blob/master/README.md)。 - -## 受众人群/潜在群体 -HomeBridge 插件开发适合家里有比较多的智能设备的智能家居爱好者，以及爱折腾、爱玩电子设备且有一定的技术能力（通过简单的技术教程，会安装和使用）的用户。 - -## 开始前准备 - -### 注册信息准备 -涂鸦应用注册信息会在将来用到。 -请参考 [Tuya IoT Platform Configuration Guide](https://github.com/tuya/tuya-android-iot-app-sdk-sample/blob/activator_tool/Tuya_IoT_Platform_Configuration_Guide.md), 在 [涂鸦 IoT 平台](https://iot.tuya.com) 上注册账号，创建对应的云开发项目，最后创建该账号下的资产、用户和云应用，获取到对应的用户名、密码、Access ID 和 Access Secret。 - -### 硬件准备 -|硬件|说明| -|:----|:----| -|PC、树莓派或服务器|用于安装插件和启动服务。本文以苹果电脑为例进行演示。| -|智能设备|用于演示智能设备的接入和控制。| -|iOS 设备|用于控制 HomeKit。| - -### 软件准备 -|软件|说明| -|:----|:----| -|命令行工具|用户自行选择。本文使用 macOS 自带的 **终端**。| -|配网工具|[Tuya Device Manager App](https://github.com/tuya/tuya-android-iot-app-sdk-sample/releases) 或 微信小程序（搜索关键词“涂鸦智能配网”）。| - -## 安装 -1. 打开终端工具。 - - - -2. 参考 [HomeBridge](https://github.com/homebridge/homebridge/blob/master/README.md) 安装 HomeBridge。 -3. 安装 Tuya HomeBridge 插件。 - >**注意**：如果在安装过程中遇到问题，可尝试在命令行之前加上 sudo，将执行命令角色权限变更为管理员。 - 1. 安装插件。 - ``` - npm install homebridge-tuya-platform - ``` - - 2. 等待安装完成，判断是否安装成功。详细过程可以参考下面的视频。 - - [![asciicast](https://asciinema.org/a/t6GY37mDPbfeG6AXVxuwROBlC.svg)](https://asciinema.org/a/t6GY37mDPbfeG6AXVxuwROBlC?autoplay=1) - -## 配置 -在使用之前，需要先配置 HomeBridge 插件中的 config.json 文件。 -1. 进入 homebridge-tuya-platform 目录。 - ``` - cd ./node_modules/homebridge-tuya-platform - ``` -2. 进入 config 目录。 - ``` - cd ./config - ``` -3. 编辑 config.json 文件。 - ``` - vim config.json - ``` -4. 在 `options` 中填入注册信息准备过程中获取到的用户名、密码、Access ID 和 Access Secret。其中，`lang` 默认为 en，`endPoint` 为当前 Tuya open API 服务的域名。 - 编辑注册信息 -5. 保存并退出编辑。 - -## 启动 Tuya HomeBridge 插件 -1. 回到 homebridge-tuya-platform 根目录。 - ``` - cd .. - ``` -2. 启动插件。 - ``` - homebridge -D -U ./config/ -P ./ - ``` - [![asciicast](https://asciinema.org/a/2gaFGeKXZtEF1pmOhqTG41M30.svg)](https://asciinema.org/a/2gaFGeKXZtEF1pmOhqTG41M30?autoplay=1) -## 使用 -打开苹果设备，在 App Store 中安装苹果官方“家庭” 应用软件，通过扫描启动插件步骤中的二维码，或者输入 8 位数字的 Pin 值（Pin 值也可在 Config.json 文件中找到）来添加配件。 - -## 开发插件与贡献代码 -您可以 fork 仓库代码分支，按照安装、配置、使用 tuya 插件的步骤，将代码启动起来。 - -### 开发环境搭建 -``` -—-VSCode -—-engines - "node": “>=0.12.0” - "homebridge": ">=0.2.0" -—-dependencies - "axios": “^0.21.1", - "crypto-js": “^4.0.0”, - "mqtt": “^4.2.6", - "uuid": "^8.3.2" -``` - -### 品类扩充 - -#### 一、插件的实现部分的原理简介 - -7f02e6c5e6654a882713361ae88a679c - -#### 二、需要关注的 js 文件 - -* 入口文件 index.js。在 addAccessory() 函数中新增你的品类，并创建对应的 xx_accessory.js 文件。 - 7f02e6c5e6654a882713361ae88a679c - -* 文件xx_accessory.js。在xx_accessory.js中，只需在 refreshAccessoryServiceIfNeed() 函数中遍历你所新增品类支持的 function，以及根据支持的 function 生成 Service 对应的 Characteristic。 - - 7f02e6c5e6654a882713361ae88a679c - -* 文件tuyaopenapi.js：设备相关接口。 -* 文件tuyamqttapi.js：支持 MQTT 服务。 - - -## 常见安装问题 - -请见 [HomeBridge](https://github.com/homebridge/homebridge/blob/master/README.md) Common Issues。 - -## Tuya Open API -- login(username, password) 登录 -- getDeviceList() 获取账号资产下的所有设备（设备对应Accessory） -- get_assets() 获取人员可操作资产列表 -- getDeviceIDList(assetID) 查询资产下的设备ID列表 -- getDeviceFunctions(deviceID) 获取设备指令集 -- getDeviceInfo(deviceID) 获取单个设备信息 -- getDeviceListInfo(devIds = []) 批量获取设备信息 -- getDeviceStatus(deviceID) 获取单个设备状态 -- getDeviceListStatus(devIds = []) 批量获取设备状态 -- sendCommand(deviceID, params) 下发设备命令 - -## MQTT -- start() 启动mqtt -- stop() 停止mqtt -- addMessageListener(listener) 添加回调函数 -- removeMessageListener(listener) 移除回调函数 - -## 问题反馈 - -您可以通过 **Github Issue** 或通过 [**工单**](https://service.console.tuya.com) 来进行反馈您所碰到的问题。 - -## LICENSE -更多信息请参考 [LICENSE](LICENSE) 文件。