From bd5989f75f4bed8ff1739e7afbec23c6fa2c0a7b Mon Sep 17 00:00:00 2001 From: hificat <48591454+hzkincony@users.noreply.github.com> Date: Sat, 8 Oct 2022 11:37:34 +0800 Subject: [PATCH] Add files via upload --- API_Reference_CN.md | 215 +++++++++++++++++++++++++++++++++++++++++++ API_Reference_EN.md | 220 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 435 insertions(+) create mode 100644 API_Reference_CN.md create mode 100644 API_Reference_EN.md diff --git a/API_Reference_CN.md b/API_Reference_CN.md new file mode 100644 index 0000000..aa252d0 --- /dev/null +++ b/API_Reference_CN.md @@ -0,0 +1,215 @@ +# kc868-arduino-library API Reference + +这个库是为ESP32系列编写的，暂时没有适配其他arduino单片机型号。使用这个库，只需要包含 `KC868.h` 这个文件，代码如下： + +```C++ +#include "KC868.h" +``` + +--- + +## 函数列表 + +- **KC868(HardwareSerial \*hs)** + + - KC868在使用之前需要创建一个全局对象才可以使用。创建完这个对象后，才可以使用下面的方法去实现功能。你可以使用`KC868()`来创建这个对象.代码如下： + + ```c++ + KC868 kc868(&Serial2); + ``` + + - 你需要传入一个串口对象的指针,在ESP32上，暂时只支持硬件串口. + +- **boolean begin(unsigned long baud, uint32_t config, int8_t rxPin, int8_t txPin, bool invert, unsigned long timeout_ms, uint8_t rxfifo_full_thrhd)** + + - begin函数的作用是打开串口。他的参数和官方串口打开的参数一模一样。第一个波特率是必须传入的参数。其他的都可以省略。你只需要简单的使用下面的代码就可以完成初始化。 + + ```c++ + kc868.begin(115200); + ``` + + - 如果你想使用其他IO口作为串口，可以使用下面的代码： + + ```c++ + kc868.begin(115200,SERIAL_8N1,22,23); + ``` + + - 其中22是接收引脚，23是发送引脚。 + +- **boolean close()** + + - 关闭KC868对应的串口。 + +- **void poll()** + + - 接收KC868的上报的数据并且定时下发查询报文，此函数必须被放置在`loop()`函数中。 + +- **boolean readSwitch(int idx)** + + - 读取指定序号的继电器状态，参数范围1-32,对应32路继电器。 + - 返回值是`boolean`类型，`true`是继电器打开状态，`flase`是关闭状态。 + - 代码示例： + + ```c++ + int ret = kc868.readSwitch(1); + Serial.printf("The value of relay 1 is %d .\n",ret); + ``` + +- **boolean readSwitchCache(int idx)** + + - 读取指定序号的继电器状态，参数idx的范围是1-32,对应32路继电器。 + - 返回值是`boolean`类型，`true`是继电器打开状态，`flase`是关闭状态. + - 与`readSwitch`不同的是，这个直接返回内存中保存的继电器的值，而非实时读取。 + +- **uint32_t readSwitchAll()** + + - 读取32路继电器状态。 + - 返回值是`uint32_t`类型，一共32bit,最高位为继电器32的状态，最低位为继电器1的状态。如：返回值是0x00000001,则代表第1路继电器打开状态，返回值是0x00000003,代表第1号和第2号继电器都是打开状态。 + - 代码示例： + + ```c++ + uint32_t ret = kc868.readSwitchAll(); + Serial.printf("The value of all relay is %d .\n",ret); + ``` + +- **boolean writeSwitch(int idx, int value)** + + - 设置指定序号的继电器状态。参数idx的范围是1-32，对应32路继电器；参数value的值为0和1,0是关闭，1是打开 + - 返回值是`boolean`类型，`true`表示操作成功，`false`表示操作失败。 + - 代码示例： + + ```c++ + boolean ret = kc868.writeSwitch(2,1);//打开第2路继电器 + Serial.printf("open relay 2 "); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAll(uint32_t value)** + + - 设置所有32路继电器状态。参数value的`uint32_t`，共32bit位。最高位为继电器32的状态，最低位为继电器1的状态。如 value的值为0x80000000，表示打开第32路继电器，如value的值为0x00000080,表示打开第8路继电器。 + - 返回值是`boolean`类型，`true`表示操作成功，`false`表示操作失败。 + - 代码示例： + + ```c++ + uint32_t v = 0x00000001; + boolean ret = kc868.writeSwitchAll( v );//打开第1路继电器 + Serial.printf("open relay 1 "); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAllON()** + + - 同时打开32路继电器。 + - 返回值是`boolean`类型，`true`表示操作成功，`false`表示操作失败。 + - 代码示例： + + ```c++ + boolean ret = kc868.writeSwitchAllON();//打开所有继电器 + Serial.printf("open all relay"); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAllOFF()** + + - 同时关闭32路继电器。 + - 返回值是`boolean`类型，`true`表示操作成功，`false`表示操作失败。 + - 代码示例： + + ```c++ + boolean ret = kc868.writeSwitchAllOFF();//关闭所有继电器 + Serial.printf("close all relay"); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean readSensor(int idx)** + + - 读取指定序号的输入传感器状态，参数idx的范围是1-6,对应6路输入开关量。 + - 返回值是`boolean`类型，`true`是触发，`flase`是未触发. + - 这里的返回值不是真实的电路电平，实际电路中，触发的电平的是电平。 + - 代码示例： + + ```c++ + boolean ret = kc868.readSensor(1);//读取开关量1的状态 + Serial.printf("io1 intput is"); + if(ret) + Serial.println("tirgged!"); + else + Serial.println("not tirgged."); + ``` + +- **uint8_t readSensorAll()** + + - 读取所有输入传感器状态 + - 返回值是`uint8_t`类型，一共8bit，取低6位，从右往左，第6位为输入传感器6的状态，最低位为输入传感器1的状态。 + - 代码示例： + + ```c++ + uint8_t value = kc868.readSensorAll();//读取所有开关量的状态 + Serial.printf("The intput state is %02x.\n",value); + ``` + +- **void setSwitchChangeHook(hook func)** + + - 设置继电器发生改变的回调函数，回调函数的名称定义如下： + + `void SwitchUpdate(uint8_t idx, uint8_t state)` + + 函数有两个参数，idx的范围是1-32，对应发生改变的继电器的序号，state的值为0或1，0对应关闭，1对应打开。 + - 代码示例： + + ```c++ + void SwitchUpdate(uint8_t idx, uint8_t state) + { + Serial.printf("relay %d is set to %d.\n",idx,state); + } + + kc868.setSwitchChangeHook(SwitchUpdate); + ``` + +- **void setSensorChangeHook(hook func)** + + - 设置输入传感器发生改变的回调函数，回调函数的名称定义如下： + + `void SwitchUpdate(uint8_t idx, uint8_t state)` + + 函数有两个参数，idx的范围是1-6，对应发生改变的输入传感器的序号，state的值为0或1，0对应未触发，1对应触发。 + - 代码示例： + + ```c++ + void SensorUpdate(uint8_t idx, uint8_t state) + { + Serial.printf("sensor %d is set to %d.\n",idx,state); + } + + kc868.setSwitchChangeHook(SensorUpdate); + ``` + +- **void setReadMode(uint8_t mode)** + + - 设置读取继电器输入状态的模式，mode的值为0或者1，0是直接读取，每次发送查询命令时，实时读取。1是读取缓存，系统每2s读取一次所有继电器的状态，并保存。读取继电器时直接返回内存中的值。 + - 注意 `kc8688.setReadMode(0);`可以省略不写。 + - 当使用 `kc868.setReadMode(1);`时，调用`readSwitch()`,仍然会返回内存中的值。无需调用`readSwitchCache()`。 + - 代码示例： + + ```c++ + kc868.begin(115200); + kc868.setReadMode(1); + ``` + - 使用默认模式则只需要使用下面的代码： + + ```c++ + kc868.begin(115200); + ``` + diff --git a/API_Reference_EN.md b/API_Reference_EN.md new file mode 100644 index 0000000..5005a58 --- /dev/null +++ b/API_Reference_EN.md @@ -0,0 +1,220 @@ +# kc868-arduino-library API Reference + +This library for KC868-H32B Pro smart controller based on ESP32 chip, you should include "KC868.h" in your code as follows: + +```C++ +#include "KC868.h" +``` + +--- + +## function list + +- **KC868(HardwareSerial \*hs)** + + - KC868 needs to create a global object before it can be used. After creating this object, you can use the following methods to implement functions. You can use `KC868()` to create this object. The code is as follows: + + ```c++ + KC868 kc868(&Serial2); + ``` + + - You should use ESP32 hardware serial port with kc868 function for initialization. + +- **boolean begin(unsigned long baud, uint32_t config, int8_t rxPin, int8_t txPin, bool invert, unsigned long timeout_ms, uint8_t rxfifo_full_thrhd)** + + - begin function is to open the serial port. Its parameter as same as arduino official serial port. The first baud rate is a parameter that must be passed in. Everything else can be omitted. You just need to simply use the following code to complete the initialization. + + ```c++ + kc868.begin(115200); + ``` + + - If you want to use any IO ports as serial ports, you can use the following code: + + ```c++ + kc868.begin(115200,SERIAL_8N1,22,23); + ``` + + - GPIO22 is RXD pin, GPIO23 is TXD pin. + +- **boolean close()** + + - Close the serial port of kc868 + +- **void poll()** + + - To receive the reported data from kc868 and send query messages regularly, this function must be placed in the `loop()` function. + +- **boolean readSwitch(int idx)** + + - Read the relay status of the specified channel number, the parameter range is 1-32, corresponding to 32 relays. + - The return value is of type `boolean`, `true` is relay ON, and `flase` is relay OFF. + - Code example: + + ```c++ + int ret = kc868.readSwitch(1); + Serial.printf("The value of relay 1 is %d .\n",ret); + ``` + +- **boolean readSwitchCache(int idx)** + + - Read the relay status of the specified channel number, the parameter range is 1-32, corresponding to 32 relays. + - The return value is of type `boolean`, `true` is relay ON, and `flase` is relay OFF. + - what different `readSwitch`, this one returns the value of the relay held in memory directly, rather than reading it in real time. + +- **uint32_t readSwitchAll()** + + - Read the status of 32 channel relays. + - The return value is of type `uint32_t`, with a total of 32 bits, the highest bit is the state of relay 32, and the lowest bit is the state of relay 1. For example, the return value is 0x00000001, which means that relay1 is ON, and the return value is 0x00000003, which means that the relay1 and relay2 are both ON. + - Code example: + + + ```c++ + uint32_t ret = kc868.readSwitchAll(); + Serial.printf("The value of all relay is %d .\n",ret); + ``` + +- **boolean writeSwitch(int idx, int value)** + + - Turn ON/OFF specified channel relay. The range of parameter 'idx' is 1-32, corresponding to 32 relays; the value of parameter value is 0 and 1, 0 is OFF, 1 is ON + - The return value is of type `boolean`, `true` means the operation succeeded, `false` means the operation failed. + - Code example: + + + ```c++ + boolean ret = kc868.writeSwitch(2,1); //Turn ON relay2 + Serial.printf("open relay 2 "); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAll(uint32_t value)** + + - Turn ON/OFF any 32 relays by one command. `uint32_t` of the parameter value, a total of 32 bits. The highest bit is the state of relay32, and the lowest bit is the state of relay1. If the value is 0x80000000, it means to Turn ON relay32, if the value of value is 0x00000080, it means to turn ON relay8. You just replace any bit with 1 or 0 for turn ON, turn OFF relay. + - The return value is of type `boolean`, `true` means the operation succeeded, `false` means the operation failed. + - Code example: + + ```c++ + uint32_t v = 0x00000001; + boolean ret = kc868.writeSwitchAll( v ); //Turn ON relay1 + Serial.printf("open relay 1 "); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAllON()** + + - Turn ON all 32 channel relays + - The return value is of type `boolean`, `true` means the operation succeeded, `false` means the operation failed. + - Code example: + + ```c++ + boolean ret = kc868.writeSwitchAllON(); //Turn ON all relays + Serial.printf("open all relay"); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean writeSwitchAllOFF()** + + - Turn OFF all 32 channel relays + - The return value is of type `boolean`, `true` means the operation succeeded, `false` means the operation failed. + - Code example: + + ```c++ + boolean ret = kc868.writeSwitchAllOFF(); //Turn OFF all relays + Serial.printf("close all relay"); + if(ret) + Serial.println("success!"); + else + Serial.println("fail."); + ``` + +- **boolean readSensor(int idx)** + + - Read the state of the input sensor with the specified channel number. The range of the parameter 'idx' is 1-6, corresponding to 6 digital input ports. + - The return value is of type `boolean`, `true` is triggered, `flase` is not triggered. + - Code example: + + ```c++ + boolean ret = kc868.readSensor(1); // read digital input1 + Serial.printf("io1 intput is"); + if(ret) + Serial.println("tirgged!"); + else + Serial.println("not tirgged."); + ``` + +- **uint8_t readSensorAll()** + + - Read all digital input ports status + - The return value is of type `uint8_t`, a total of 8 bits, take the lower 6 bits, from right to left, the 6th bit is the digital input6, and the lowest bit of the state is the state of the digital input1. + - Code example: + + + ```c++ + uint8_t value = kc868.readSensorAll(); //read 6 channel digital input ports + Serial.printf("The intput state is %02x.\n",value); + ``` + +- **void setSwitchChangeHook(hook func)** + + - Set the callback function when the relay state changed. The name of the callback function is defined as follows: + + `void SwitchUpdate(uint8_t idx, uint8_t state)` + + function has two parameters, the range of 'idx' is 1-32, corresponding to the channel number of the relay that has changed, the value of state is 0 or 1, 0 means to OFF, and 1 means to ON. + - Code example: + + + ```c++ + void SwitchUpdate(uint8_t idx, uint8_t state) + { + Serial.printf("relay %d is set to %d.\n",idx,state); + } + + kc868.setSwitchChangeHook(SwitchUpdate); + ``` + +- **void setSensorChangeHook(hook func)** + + - Set the callback function when the digital input changed. The name of the callback function is defined as follows: + + `void SwitchUpdate(uint8_t idx, uint8_t state)` + + function has two parameters, the range of 'idx' is 1-6, corresponding to the channel number of the digital input that has changed, the value of state is 0 or 1, 0 means triggered, and 1 means not triggered. + - Code example: + + ```c++ + void SensorUpdate(uint8_t idx, uint8_t state) + { + Serial.printf("sensor %d is set to %d.\n",idx,state); + } + + kc868.setSwitchChangeHook(SensorUpdate); + ``` + +- **void setReadMode(uint8_t mode)** + + - Set the mode of reading the state of the relay, the value of mode is 0 or 1, '0' is directly read, and every time a query command is sent, it is read in real time. '1' is the read cache, the system reads the status of all relays every 2s and saves them. The value in memory is returned directly when the relay is read. + - Note that `kc8688.setReadMode(0);` can be omitted without writing. Because default is mode=0 + - When using `kc868.setReadMode(1);`, calling `readSwitch()` will still return the value in memory. No need to call `readSwitchCache()`. + - Code example: + + + + ```c++ + kc868.begin(115200); + kc868.setReadMode(1); + ``` + - To use the default mode, just use the following code： + + ```c++ + kc868.begin(115200); + ``` +