========
快速上手
========

在loongpio库中，你可以通过简单的数行代码，对龙芯派的管脚进行
输入输出操作。下面将通过五个模块来简单展示loongpio库的特点和
用法。

引用loongpio库
==============

在引用loongpio库的对应模块后，系统将会自动配置好对应管脚的
输入输出模式，并进行该模块对应的一系列准备工作。而在程序结束
后，loongpio将自动处理模块销毁、释放等工作。

举例来说，如果使用loongpio按钮模块 :class:`Button` ，
需要这样引用：

.. code-block:: python

    from loongpio import Button

在引用完成后，在你的代码中你可以这样调用：

.. code-block:: python

    btn = Button(GPIO13)

或者你可以直接引用loongpio库：

.. code-block:: python

    import loongpio

然后再如下调用：

.. code-block:: python

    btn = loongpio.Button(13)

GPIO管脚命名
============

loongpio库中在引用GPIO管脚时，推荐使用GPIO序号来代表具体管脚。
这有别于管脚的物理序号。具体的管脚序号见下表：

.. image:: images/pin_layout.svg

同一个管脚可以使用不同的别名进行引用，例如“GPIO13”管脚接上了LED模块，
它的管脚名是“GPIO13”，物理管脚是37，在调用时我们使用以下的
方法来定义都是等效的：

.. code-block:: pycon

    >>> led = LED(GPIO13)
    >>> led = LED(LS2K_GPIO13)
    >>> led = LED(13)
    >>> led = LED(PIN37)

.. note::

    仅有GPIO可以直接使用数字别名，其它功能的管脚没有数字别名。
    如“PWM0”只能使用 :program:`PWM0` 或 :program:`PIN45`
    进行调用。

尽管有不同的别名，在生成对应模块的对象属性中，仍然是以标准管脚名
来进行命名的：

.. code-block:: pycon

    >>> btn = Button(PIN37)
    >>> servo = Servo(PIN45)
    >>> btn
    <loongpio.Button object on pin GPIO13>
    >>> servo
    <loongpio.Servo object on pin PWM0>

后来的文档中，为了避免混乱，我们会直接引用标准管脚名进行叙述。

LED
===

可以使用下面的代码制作闪烁小灯：

.. code-block:: python

    from loongpio import LED
    from time import sleep
    
    led = LED(GPIO4)
    
    while True:
        led.on()
        sleep(1)
        led.off()
        sleep(1)

亮度可调的LED
=============

一般情况下LED都可以通过PWM（脉冲宽度调制）的方式来
改变输出功率。我们将LED连接到龙芯派的PWM引脚上，然后
使用PWMLED模块来调用，通过0和1之间的变量来代表LED的亮度：

.. code-block:: python

    from loongpio import PWMLED
    from time import sleep
    
    led = LED(PWM0)
    
    while True:
        led.value = 0 # 关闭
        sleep(1)
        led.value = 0.5 # 半亮
        sleep(1)
        led.value = 1 # 全亮
        sleep(1)

按钮
====

检测按钮是否被按下：

.. code-block:: python

    from loongpio import Button
    
    btn = Button(GPIO4)
    
    while True:
        if btn.is_pressed:
            print("按钮被按下  \r")
        else:
            print("按钮未被按下\r")

等待按钮被按下再继续：

.. code-block:: python

    from loongpio import Button
    
    btn = Button(GPIO4)
    
    btn.wait_for_press()
    print("按钮被按下了")

舵机
====

可以简单地将舵机从其最小脉冲宽度向最大脉冲宽度移动：

.. code-block:: python

    from loongpio import Servo
    from time import sleep
    
    servo = Servo(PWM0)
    
    while True:
        servo.min()
        sleep(2)
        servo.mid()
        sleep(2)
        servo.max()
        sleep(2)

可以使用一个由0到1.0间的数字来表示舵机输入信号
的占空比，从而改变舵机的指向(初始化舵机后占空比
默认设定为0.5)：

.. code-block:: pycon

    >>> servo = Servo(PWM0)
    >>> servo.value
    0.5
    >>> servo.value = 0
    >>> servo.value = 0.8
    >>> servo.value = 2
    >>> servo.value
    0.8

无源蜂鸣器
==========

可以用PWM的方式来为无源蜂鸣器提供振荡源，通过改变频率
发出不同音高的声音。

.. code-block:: pycon

    >>> from loongpio import TonalBuzzer
    >>> buzzer = TonalBuzzer(PWM0)
    >>> buzzer.play(440.0)
    >>> buzzer.stop()

可以使用\ `科学音调记号法`_\ 来标记特定的音值，用以替代
频率的表示方法。在使用五线谱大调谱正中间的音值时，可以
省略数字：

.. code-block:: python

    from loongpio import TonalBuzzer
    from time import sleep
    
    notes = ['C', 'D', 'E', 'F', 'G']
    buzzer = TonerBuzzer(PWM0)
    
    for note in notes:
        buzzer.play(note)
        sleep(1)

在调用音名的时候，以下的几种表达式是等效的：

.. code-block:: pycon

    >>> buzzer.play('C')
    >>> buzzer.play('C4')
    >>> buzzer.play(261.6)

可以通过\ `查表`_\ 相应的音名和对应的频率：

.. _查表: tones.html

.. _科学音调记号法: https://en.wikipedia.org/wiki/Scientific_pitch_notation

DHT11温湿度传感器
=================

DHT11温湿度传感器是一款可以实时检测空气的温度和湿度，
并传回数据的传感器。可以通过以下的方法简单调用：

.. code-block:: python

    from loongpio import DHT11
    from time import sleep
    
    sensor = DHT11(4)
    
    while True:
        tem, hum = sensor.getTemperature, sensor.getHumidity
        print('当前的温度为'+str(tem)+'摄氏度')
        print('当前的相对湿度为'+str(hum)+'%')
        sleep(5)

HC-SR04距离传感器
=================

HC-SR04通过超声波来测量与最近的障碍物的距离。

.. code-block:: python

    from loongpio import DistanceSensor
    from time import sleep
    
    sensor = DistanceSensor(trigger=3, echo=4)
    
    while True:
        print('距离：'+str(sensor.distance*100)+'cm')
        sleep(1)

.. note::

    使用市售的HC-SR04传感器来进行实验时，需要连接额外的
    电子元件到。如下图：
    
    .. image:: images/wiring-HCSR04.svg
       :width: 500px
       :align: center
    
    准备330Ω和470Ω的两个电阻，将330Ω的连接到传感器的ECHO口，
    将470Ω连接到传感器的GND口，两个电阻的另一端同时连接到GPIO的
    ECHO口上。