haas-python-soil-moisture 0.0.7
This is soil_moisture driver for HaaS Python. HaaS Python is forked from micropython.
License: Apache License, Version 2.0


## HaaS Python介绍
HaaS Python是阿里云IoT团队最新研发的一套低代码编程框架，兼容MicroPython编程规范，依托HaaS平台软硬件积木提供AI、支付、蓝牙配网、云连接、UI等物联网场景常用的能力，从而解决了物联网应用开发难的问题。有了Python轻应用框架，物联网编程不再局限于专业软件开发人员，一般的技术员也可以快速实现复杂的物联网需求。
更多HaaS Python介绍和开发资料见[HaaS Python官网](https://haas.iot.aliyun.com/haasapi/index.html?spm=a2cpu.b16145223.0.0.595660b1dZDX71#/?from=corp),[创意案例](https://haas.iot.aliyun.com/solution?from=crop), [硬件积木](https://haas.iot.aliyun.com/solution/hardware?from=corp)

HaaS Python is a set of low-code programming frameworks newly developed by Alibaba Cloud IoT team. It is compatible with MicroPython programming specifications. It relies on the hardware and software building blocks of the HaaS platform to provide capabilities commonly used in IoT scenarios such as AI, payment, Bluetooth network configuration, cloud connection, and UI. Solve the difficult problem of IoT application development. With the Python light application framework, IoT programming is no longer limited to professional software developers, and general technicians can quickly implement complex IoT requirements.
For more HaaS Python introduction and development materials, see [HaaS Python official website](https://haas.iot.aliyun.com/haasapi/index.html?spm=a2cpu.b16145223.0.0.595660b1dZDX71#/?from=corp), [Creative Case](https://haas.iot.aliyun.com/solution?from=crop), [Hardware Building Blocks](https://haas.iot.aliyun.com/solution/hardware?from=corp)

## 安装方法
* 在[HaaS Python官网](https://haas.iot.aliyun.com/haasapi/index.html?spm=a2cpu.b50127119.0.0.4e1260b1ebMIf1#/)下载开发板对应的固件，并完成固件烧录

Download the firmware corresponding to the development board at [HaaS Python website](https://haas.iot.aliyun.com/haasapi/index.html?spm=a2cpu.b50127119.0.0.4e1260b1ebMIf1#/) and complete the firmware burning

* 在开发板上运行以下命令完成安装和使用,如果您在使用过程中遇到问题，欢迎在[github上向我们提交issue](https://github.com/alibaba/AliOS-Things/issues)，我们的工程师会及时解答

Run the following commands on the development board to complete the installation and use. If you encounter problems during use, please submit an issue to us on [github](https://github.com/alibaba/AliOS-Things/issues), Our engineers will answer in time
```
import upip
upip.install("haas-python-soil_moisture")
import haas-python-soil_moisture
```
# 土壤湿度传感器 - SoilMoisture

## 一、产品简介
土壤湿度传感器主要用于检测土壤中湿度是否达到阀值及湿度的大小，通过电位器调节土壤湿度控制阀值，可以自动对菜园，花园自动浇水，家庭花盆土壤湿度的控制，各种电子比赛，电子积木等。

<div align="center">
<img src="./../../docs/images/soil_moisture_front.jpg"  width=40%/>
</div>

引脚定义：
* VCC：接电源正极（3.3-5V）
* GND：接电源负极
* DO：TTL开关信号输出
* AO：模拟信号输出

## 二、技术参数
* 传感器表面采用镀镍处理，具有较好的抗氧化、导电性、耐用性；
* 采用LM393比较器输出，信号无噪音，波形好，驱动能力强，大于15mA；
* 配合电位器可调节灵敏度，控制土壤的湿度信号检测；
* 传感器设有固定螺栓孔，方便安装；
* 工作电压：3.3V - 5V
* 输出形式：数字开关量输出（0和1），模拟量AO电压输出；
* PCB尺寸：3.2CM x 1.4CM

## 三、软件接口

土壤湿度传感器HaaS Python驱动：[下载地址](https://github.com/alibaba/AliOS-Things/tree/master/haas_lib_bundles/python/libraries/soil_moisture)
<br>

### SoilMoisture(DO) - 创建 SoilMoisture 驱动对象
* 函数原型：
> drv = SoilMoisture(DO)

* 参数说明：

|参数|类型|必选参数？|说明|
|-----|----|:---:|----|
|DO|GPIO|是|调用此函数前需确保 DO 对象已经处于 open 状态|

* 返回值：
SoilMoisture 对象成功，返回 SoilMoisture 对象；SoilMoisture 对象创建失败，抛出 Exception

* 示例代码：

```python
import utime   # 延时函数在utime库中
from driver import GPIO
import soil_moisture

# 初始化 GPIO
DO = GPIO()
DO.open('LM393_DO')   # 按照 board.json 中名为 "LM393_DO" 的设备节点的配置参数
drv = soil_moisture.SoilMoisture(DO)
print("SoilMoisture inited!")
```

* 输出：
```log
SoilMoisture inited!
```

### moistureDetect() - 检测当前湿度是否达到阀值

* 函数功能：
通过 GPIO 读取数字开关量，湿度未达阀值时为高电平 1，湿度达到阀值时为低电平 0

* 函数原型：
> drv.moistureDetect()

* 参数说明：
无

* 返回值
开关量（数据类型：整型）

* 示例：

```python
detected = drv.moistureDetect()
if detected == 0:
    print("moisture is detected")
else:
    print('no moisture detected')
```

* 输出：
```log
moisture is detected
```

## 四、接口案例
此使用实例在 board.json 中定义了名为 LM393_DO 的 GPIO 类型的对象。在 Python 脚本中周期性的检查当前土壤湿度检测值结果并打印在日志中。

* 代码：
```python
# board.json配置：
{
    "name": "board-name",
    "version": "1.0.0",
    "io": {
      "LM393_DO": {
        "type": "GPIO",
        "port": 25,
        "dir": "input",
        "pull": "pullup"
      }
    },
    "debugLevel": "ERROR",
    "repl": "disable"
}

```
```python
# Python代码
import utime   # 延时函数在utime库中
from driver import GPIO
import soil_moisture

if __name__ == '__main__':
    # 初始化 GPIO
    DO = GPIO()
    DO.open('LM393_DO')   # 按照 board.json 中名为 "LM393_DO" 的设备节点的配置参数
    if ret != 0:
        raise Exception('open device failed %s' % ret)
    drv = soil_moisture.SoilMoisture(DO)
    print("SoilMoisture inited!")

    while True:      # 无限循环
        detected = drv.moistureDetect()  # 周期性检查噪音值
        if detected == 0:
            print("moisture is detected")
        else:
            print('no moisture detected')
        utime.sleep_ms(30)

    DO.close()  # 关闭 GPIO 设备
```

* 输出：
```python
...
no moisture detected
no moisture detected
moisture is detected
moisture is detected
...

```

## 五、通信协议
主控芯片与土壤湿度感应传感器之间使用 GPIO 通讯，土壤湿度传感器通过 LM393 比较器对模拟信号电压进行比较，当达到阀值则输出对应开关量。

使用时感应板上未达阀值时，DO 输出高电平，感应板上湿度达到阀值时，DO 输出低电平。感应板恢复干燥环境时，DO又恢复到高电平状态。DO TTL 数字开关量可以方便检测土壤湿度是否达到阀值状态。

模拟量输出 AO 口可以和 ADC 接口相连，通过 AD 转换，可以获得土壤湿度更精确的数值;

## 六、工作原理
如下是原理图，土壤湿度感应板输出电压到 LM393+ 口，LM393- 口接电位器，因此感应板与 510K 电阻产生分压电路输出电压到 LM393+，电位器产生参考电压输出到 LM393-。

LM393 的原理是：
* 当电压输入 LM393- 大于 LM393+ 时输出 OUT 与地接通（低电平）
* 当电压输入 LM393- 小于 LM393+ 时输出 OUT 开路（上拉电阻高电平）

因为 OUT 引脚有一颗 510K 上拉电阻，因此在开路的情况下为高电平，与地接通时时为低电平。

我们以 VCC 3.3V为例，当感应板无湿度环境时，LM393+ 为3.3V，LM393- 通过电位器输出电压假设为2V，那么 LM393- < LM393+，OUT 为开路，输出高电平 1，反之输出低电平。

<div align="center">
<img src="./../../docs/images/soil_moisture_schema.jpg"  width=50%/>
</div>

## 参考文献及购买链接
[1] [LM393 Datasheet](https://www.ti.com/document-viewer/LM393/datasheet)<br>
[2] [购买链接](https://detail.tmall.com/item.htm?id=37365775741)