haas-python-hcsr04 0.0.8
This is hcsr04 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-hcsr04")
import haas-python-hcsr04
```
# 超声波测距传感器

## 一、产品简介
&emsp;&emsp;
HC-SR04超声波传感器使用声纳来确定物体的距离，其工作原理类似与蝙蝠。测量范围从2厘米到450厘米，HC-SR04超声波传感器上配有超声波发射器和接收器两个模块。
<br>
&emsp;&emsp;
超声波测距传感器是数字接口类型，其基本工作过程如下:
* 发射器（触发引脚-Trig），发送信号 一段高频声音<br>
* 当信号遇到一个物体时，它会被反射<br>
* 然后发射器（回声引脚-Echo）接收该信号<br>

<div align="center">
<img src=./../../docs/images/ext_超声波测距_定义尺寸.png  width=35%/>
</div>

引脚定义
* VCC：DC-5V<br>
* Trig：触发(输入)<br>
* Echo：回声(输出)<br>
* GND：地

<br>

## 二、技术参数
* 电源：+ 5V DC<br>
* 静态电流：<2mA<br>
* 工作电流：15mA<br>
* 有效角度：<15°<br>
* 测距：2厘米 - 450厘米<br>
* 分辨率：0.3厘米<br>
* 测量角度：30度<br>
* 触发输入脉冲宽度：10uS<br>
* 尺寸：45mm x 20mm x 15mm<br>

## 三、软件接口

超声波测距传感器HaaS Python驱动：[下载地址](https://github.com/alibaba/AliOS-Things/tree/master/haas_lib_bundles/python/libraries/hcsr04)
<br>


### HCSR04(trigObj,echoObj) - 创建超声波传感器对象
<br>

* 函数原型

> hcsr04Obj = HCSR04(trigObj,echoObj)

* 参数说明

参数|类型|必选参数？|说明|
|:-:|:-:|:-:|:-|
|trigObj|GPIO|是|GPIO配置输出，触发引脚，调用此函数前需确保trigObj对象已经处于open状态|
|echoObj|GPIO|是|GPIO配置输入，测量引脚，调用此函数前需确保echoObj对象已经处于open状态|

* 返回值

> HCSR04对象成功，返回HCSR04对象；HCSR04对象创建失败，抛出Exception

* 示例代码
```python
import hcsr04
from driver import GPIO

print("Testing HCSR04 ...")
echoDev = GPIO()
echoDev.open("echo")

trigDev = GPIO()
trigDev.open("trig")

hcsr04Dev = hcsr04.HCSR04(trigDev,echoDev)
```

* 输出
```python
Testing HCSR04 ...
```
</br>

### measureDistance() - 获取超声波测量的距离
<br>

* 函数功能：

> 获取超声波测量的距离

* 函数原型：

> HCSR04.measureDistance()

* 参数说明：
> 无

* 返回值：
> 返回值为cm单位的距离值

* 示例：

```python
import hcsr04
from driver import GPIO
import utime

print("Testing HCSR04 ...")
echoDev = GPIO()
echoDev.open("echo")

trigDev = GPIO()
trigDev.open("trig")

hcsr04Dev = hcsr04.HCSR04(trigDev,echoDev)
while True:             # 无限循环
    distance = disDev.measureDistance()
    print(str(distance)+' CM')
    utime.sleep(1)      # 打印完之后休眠1秒
```

* 输出
```python
Testing HCSR04 ...
34 CM
492 CM
```

</br>

## 四、接口案例

此使用实例在board.json中定义了名为IR的GPIO类型的对象。在Python脚本中执行一次获取IR人体红外传感器状态值并打印在日志中。

* 案例代码
```python
{
  "name": "board-name",
  "version": "1.0.0",
  "io": {
    "trig": {
      "type": "GPIO",
      "port": 25,
      "dir": "output",
      "pull": "pullup"
    },
    "echo": {
      "type": "GPIO",
      "port": 26,
      "dir": "input",
      "pull": "pullup"
    }
  }
}
```

```python
import hcsr04
from driver import GPIO
import utime

print("Testing HCSR04 ...")
echoDev = GPIO()
echoDev.open("echo")

trigDev = GPIO()
trigDev.open("trig")

hcsr04Dev = hcsr04.HCSR04(trigDev,echoDev)
while True:             # 无限循环
    distance = disDev.measureDistance()
    print(str(distance)+' CM')
    utime.sleep(1)      # 打印完之后休眠1秒
```

* 输出
```python
Testing HCSR04 ...
34 CM
492 CM
```

## 五、工作原理

### 超声波工作示意图
<div align="center">
<img src=./../../docs/images/ext_超声波测距原理_定义尺寸.png  width=40%/>
</div>
<br>

### 基本原理
* 采用IO口Trig触发测距，对Trig口输出至少10us的高电平
* 模块自动发送8个40Khz的方波，自动检测是否有信号返回
* 有信号返回，通过IO口Echo输出一个高电平，高电平持续的时间就是超声波从发送到返回的时间
* 测试距离 = （高电平持续的时间/声速340m/s）/2

<br>

### 时序原理
<div align="center">
<img src=./../../docs/images/ext_超声波测距时序_定义尺寸.png width=40%/>
</div>

## 参考文献及购买链接
[1] [购买链接](https://detail.tmall.com/item.htm?id=13674895744)