====== Elfshield Micropython API Reference ======

===== microbit 模块 =====

  在使用Elfshield扩展板驱动直流电机、舵机时，请在你的脚本前加入：
  from microbit import *

==== 直流电机驱动API ====

**motor.init()**\\
描述：电机驱动前初始化。\\
参数：无\\
返回值：无

**motor.runSpeed(index,speed)**\\
描述：设置电机接口及速度。\\
参数：
^index|设置电机接口，1为M1接口，2为M2接口|
^speed|设置电机速度，正速度为顺时针转，负速度为逆时针转,速度范围：-255~255，**速度只能为整数**|
返回值：无

示例：\\
电机M1、M2正传5s，反转5s。

<sxh python; first-line: 1;highlight: [89,92]; title: motor_test.py>
from microbit import *
import time

motor.init()
speed = 255
while True: 
    motor.runSpeed(1,value)
    motor.runSpeed(2,value)
    time.sleep_ms(5000)
   
    motor.runSpeed(1,-value)
    motor.runSpeed(2,-value)
    time.sleep_ms(5000)
    
</sxh>
\\

==== 舵机驱动API ====

**servo.init()**\\
描述：舵机驱动前初始化。\\
参数：无\\
返回值：无

**servo.angle(index,angle)**\\
描述：设置舵机接口及角度。\\
参数：
^index|设置舵机接口，1为Servo1，2为Servo2|
^angle|设置舵机旋转角度，范围：0~180，**角度只能为整数**|
返回值：无

示例：\\
舵机Servo1、Servo2在0和180度之间往回旋转。

<sxh python; first-line: 1;highlight: [89,92]; title: servo_test.py>
from microbit import *
import time

servo.init()

while True: 
    servo.angle(1,0)
    servo.angle(2,0)
    time.sleep_ms(1000)
    servo.angle(1,180)
    servo.angle(2,180)
    time.sleep_ms(1000)
    
</sxh>
\\

===== music模块(蜂鸣器驱动API) =====

  在使用Elfshield扩展板上驱动板载的蜂鸣器时，请在你的脚本前写入：
  import music

Elfshield驱动蜂鸣器所使用的是官方提供的music模块，相关api可点击以下链接查看：\\
music模块参考（英文）：[[https://microbit-micropython.readthedocs.io/en/latest/tutorials/music.html#]]\\
music模块参考（中文）：[[http://docs.dfrobot.com.cn/bxy/music.html]]\\

示例1：
<sxh python; first-line: 1;highlight: [89,92]; title: buzzer_test.py>
import music
import time

while True: 
    music.play('c2:2')
    time.sleep_ms(100)
        
</sxh>

示例2：
<sxh python; first-line: 1;highlight: [89,92]; title: music_test.py>
import music
import time

music.set_tempo(bpm=220)
# play Prelude in C.
notes = [
    'c4:1', 'e', 'g', 'c5', 'e5', 'g4', 'c5', 'e5', 'c4', 'e', 'g', 'c5', 'e5', 'g4', 'c5', 'e5',
    'c4', 'd', 'a', 'd5', 'f5', 'a4', 'd5', 'f5', 'c4', 'd', 'a', 'd5', 'f5', 'a4', 'd5', 'f5',
    'b3', 'd4', 'g', 'd5', 'f5', 'g4', 'd5', 'f5', 'b3', 'd4', 'g', 'd5', 'f5', 'g4', 'd5', 'f5',
    'c4', 'e', 'g', 'c5', 'e5', 'g4', 'c5', 'e5', 'c4', 'e', 'g', 'c5', 'e5', 'g4', 'c5', 'e5',
    'c4', 'e', 'a', 'e5', 'a5', 'a4', 'e5', 'a5', 'c4', 'e', 'a', 'e5', 'a5', 'a4', 'e5', 'a5',
    'c4', 'd', 'f#', 'a', 'd5', 'f#4', 'a', 'd5', 'c4', 'd', 'f#', 'a', 'd5', 'f#4', 'a', 'd5',
    'b3', 'd4', 'g', 'd5', 'g5', 'g4', 'd5', 'g5', 'b3', 'd4', 'g', 'd5', 'g5', 'g4', 'd5', 'g5',
    'b3', 'c4', 'e', 'g', 'c5', 'e4', 'g', 'c5', 'b3', 'c4', 'e', 'g', 'c5', 'e4', 'g', 'c5',
    'a3', 'c4', 'e', 'g', 'c5', 'e4', 'g', 'c5', 'a3', 'c4', 'e', 'g', 'c5', 'e4', 'g', 'c5',
    'd3', 'a', 'd4', 'f#', 'c5', 'd4', 'f#', 'c5', 'd3', 'a', 'd4', 'f#', 'c5', 'd4', 'f#', 'c5',
    'g3', 'b', 'd4', 'g', 'b', 'd', 'g', 'b', 'g3', 'b3', 'd4', 'g', 'b', 'd', 'g', 'b'
] 

music.play(notes)

</sxh>
\\

===== neopixel模块(RGB灯驱动API) =====

  在使用Elfshield扩展板上驱动板载的3颗RGB灯，或者通过PORT_A~PORT_D驱动灯带时，请在你的脚本前写入：
  from elfshield import *
  import neopixel

Elfshield驱动RGB灯所使用的是官方提供的neopixel模块，elfshield模模块只提供IO口的封装：

^elfshield ^microbit^
|OnBoard\_RGB | pin8 |
| PORT\_A | pin13|
| PORT\_B | pin14|
| PORT\_C | pin15|
| PORT\_D | pin16|

关于neopixel块的api请参考（英文版）：[[https://microbit-micropython.readthedocs.io/en/latest/neopixel.html]]\\
关于neopixel块的api请参考（中文版）：[[http://docs.dfrobot.com.cn/bxy/neopixel.html]]

示例：

<sxh python; first-line: 1;highlight: [89,92]; title: rgb_test.py>
from microbit import *
from elfshield import *
import time
import neopixel
from random import randint

np = neopixel.NeoPixel(OnBoard_RGB,3) #创建一个RGB灯对象np，设置接口为板载RGB,数量为3

while True:
    for pixel_id in range(0, len(np)):

        # 为当前RGB灯指定0到60之间的随机红色，绿色和蓝色值    
        red = randint(0, 50)
        green = randint(0, 50)
        blue = randint(0, 50)

        np[pixel_id] = (red, green, blue)

        # 显示Neopixel条带上的当前像素数据    
        np.show()
        time.sleep_ms(500)
    np.clear()
    time.sleep_ms(500)
    
</sxh>
\\

===== elfshield模块 =====

  在使用Elfshield扩展板时，为了方便，请在脚本前写入：
  from elfshield import *

==== 板载声音传感器API ====

**volume_level()**\\
描述：获取板载声音传感器的值\\
参数：无\\
返回值：0~1023的整数

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: rgb_test.py>
from microbit import *
#write your program:
from elfshield import *
import time

while True:
    value = volume_level()
    print(value)
    sleep(100)
  
</sxh>
\\

==== RGB超声波传感器模块API ====

**ultrasonic_setColor(port,index,red,green,blue)**\\
描述：设置超声波内置RGB灯的颜色并显示\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择RGB灯，范围1~3，1为左，,2为右边，3为全选|
^red|红色分量|
^green|绿色分量|
^blue|蓝色分量|
返回值：无

**ultrasonic_setLED(port,index,status)**\\
描述：mini RGB超声波上两颗黄色LED灯驱动（**仅适用于mini RGB超声波**）\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择LED灯，范围1~3，1为左边，2为右边，3为全选|
^status|设置LED灯的状态，0为灭，1为亮|
返回值：无

**ultrasonic_getDistance(port)**\\
描述：获取超声波测距数据\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：3~500(单位:cm)

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: rgb_ultrasonic_test.py>
from elfshield import *
import time

while True:
    ultrasonic_setColor(PORT_A,3,255,255,255)
    r = ultrasonic_getDistance(PORT_A)
    print(r)
    time.sleep_ms(100)   
     
</sxh>
\\

==== 双路巡线传感器API ====

**lineFollower_read(port,index)**\\
描述：获取巡线传感器的值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择探头，1为S1，2为S2|
返回值：0~1023，整数

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: linefollower_test.py>
from elfshield import *
import time

while True:
    print("S1: ",lineFollower_read(PORT_A,1))
    print("S2: ",lineFollower_read(PORT_A,2))
    time.sleep_ms(100)
    
</sxh>
\\

==== 数码管模块API ====

**digitalModule_showNumber(port,number)**\\
描述：数码管显示数字\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^number|设置需要显示的数字|
返回值：无

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: digitalModule_test.py>
from elfshield import *
import time

while True:
    digitalModule_showNumber(PORT_A,123)
    time.sleep_ms(1000)
    digitalModule_showNumber(PORT_A,1.26)
    time.sleep_ms(1000)
    digitalModule_showNumber(PORT_A,-100)
    time.sleep_ms(1000)
    digitalModule_showNumber(PORT_A,-1.04)
    time.sleep_ms(1000)
    
</sxh>
\\

==== 雾化器模块API ====

**waterAtomizer_set(port,status)**\\
描述：设置雾化器模块工作状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^status|工作状态，0不工作，1工作|
返回值：无

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: waterAtomizer_test.py>
from elfshield import *
import time

while True:
    waterAtomizer_set(PORT_A,1)
    time.sleep_ms(200)
    waterAtomizer_set(PORT_A,0)
    time.sleep_ms(200)
    
</sxh>
\\

==== MP3模块API ====

**mp3_setDevice(port,device)**\\
描述：设置MP3模块从哪个存储设备播放\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^device|2为选TF卡，4为选MP3模块板载FLASH|
返回值：无

**mp3_setVolume(port,value)**\\
描述：设置MP3模块播放音量\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^value|音量值|
返回值：无

**mp3_playMusic(port,index)**\\
描述：选择播放第index首\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择曲目，范围：1~3000|
返回值：无

**mp3_play(port)**\\
描述：MP3播放\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：无

**mp3_pause(port)**\\
描述：MP3暂停播放\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：无

**mp3\_prevMusic(port)**\\
描述：上一曲\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：无

**mp3\_nextMusic(port)**\\
描述：下一曲\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：无

**mp3\_isOver(port)**\\
描述：判断音频是否播放完\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：True或者False

示例：\\
MP3与4位按键模块组成简易MP3播放器
<sxh python; first-line: 1;highlight: [89,92]; title: MP3_test.py>
from elfshield import *
import time

mp3_setVolume(PORT_A,20)
mp3_playMusic(PORT_A,3)
display.show(Image.HAPPY)
while True:
    r = led4button_readKey(PORT_B)
    print(r)
    if(r == 1):
        time.sleep_ms(100)
        if (r == 1):
            mp3_play(PORT_A)
    elif(r == 2):
        time.sleep_ms(100)
        if (r == 2):
            mp3_pause(PORT_A)
    elif(r == 3):
        time.sleep_ms(100)
        if (r == 3):
            mp3_nextMusic(PORT_A)
    elif(r == 4):
        time.sleep_ms(100)
        if (r == 4):
            mp3_prevMusic(PORT_A)
    
    time.sleep_ms(10)
    
</sxh>
\\

====5V 130电机模块API ====

**dc130motor_speed(port,speed)**\\
描述：驱动130电机\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^speed|设置电机速度，正速度为顺时针转，负速度为逆时针转,速度范围：-255~255，**速度只能为整数**|
返回值：无

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: dc130Motor_test.py>
from elfshield import *
import time

while True:
    dc130motor_speed(PORT_A,255)
    time.sleep_ms(1000)  
    dc130motor_speed(PORT_A,-255)
    time.sleep_ms(1000)
    
</sxh>
\\

==== 继电器模块API ====

**relayModule_set(port,status)**\\
描述：设置继电器状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^status|设置继电器状态，0为常闭接通，1为常开接通|
返回值：无

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: relayModule_test.py>
from elfshield import *
import time

while True:
    relayModule_set(PORT_A,0)
    time.sleep_ms(1000)
    relayModule_set(PORT_A,1)
    time.sleep_ms(1000)
    
</sxh>
\\

==== RGBLED-5模块API ====

**RGBLED_setColor(port,index,red,green,blue)**\\
描述：设置RGBLED-5模块所亮颜色并显示\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择RGB灯，范围0~5，0为全选|
^red|红色分量|
^green|绿色分量|
^blue|蓝色分量|
返回值：无

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: RGBLED_5_test.py>
from elfshield import *
import time

display.show(Image.HEART)
while True:
    RGBLED_setColor(PORT_A,1,0,0,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,2,0,0,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,3,0,0,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,4,0,0,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,5,0,2,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,0,20,20,20)
    time.sleep_ms(100)
    RGBLED_setColor(PORT_A,0,0,0,0)
    time.sleep_ms(100)
    
</sxh>
\\

==== 温湿度传感器API ====

**humitureSensor_readTemperature(port)**\\
描述：温湿度传感器读取温度\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~50(单位：℃)


**humitureSensor_readHumidity(port)**\\
描述：温湿度传感器读取湿度\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：20~90（单位：百分比）

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: RGBLED_5_test.py>
from elfshield import *

display.show(Image.HAPPY)
while True:
    print("Humidity:",humitureSensor_readHumidity(PORT_A),"%")
    print("Temperature:",humitureSensor_readTemperature(PORT_A))
    time.sleep_ms(500)
    
</sxh>
\\

==== 倾斜开关传感器API ====

**tiltSwitch_read(port,index)**\\
描述：读取模块倾斜状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择需要读取的传感器，1或2|
返回值：True或者False

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: tiltSwitch_test.py>
from elfshield import *
import time

while True:
    print("Sw1: ",tiltSwitch_read(PORT_A,1))
    print("Sw2: ",tiltSwitch_read(PORT_A,2))
    time.sleep_ms(100)
    
</sxh>  
\\


==== 火焰传感器API ====

**flameSensor_readValue(port,index)**\\
描述：读取火焰传感器探头的值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^index|选择需要读取的传感器，1~3|
返回值：0~255，整数

示例： 
<sxh python; first-line: 1;highlight: [89,92]; title: flameSensor_test.py>
from elfshield import *
import time

while True:
    print("flameSensor1: ",flameSensor_readValue(PORT_A,1))
    print("flameSensor2: ",flameSensor_readValue(PORT_A,2))
    print("flameSensor3: ",flameSensor_readValue(PORT_A,3))
    time.sleep_ms(100)
    
</sxh>  
\\

==== 可燃气体传感器API ====

**gasSensor_readValue(port)**\\
描述：读取可燃气体浓度值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~255

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: gasSensor_test.py>
from elfshield import *
import time

while True:
    print(gasSensor_readValue(PORT_B))
    time.sleep_ms(100)
    
</sxh>
\\

==== 人体红外传感器API ====

**PIRsensor_read(port)**\\
描述：检测人体红外传感器状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：布尔值，True或者False

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: PIRsensor_test.py>
from elfshield import *
import time

while True:
    print(PIRsensor_read(PORT_A))
    time.sleep_ms(100)
    
</sxh>
\\

==== 颜色识别传感器API ====

**colorSensor_setLight(port,status)**\\
描述：设置颜色识别传感器上面LED灯的状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^status|0为灭，1为亮|
返回值：无

**colorSensor_whiteBalance(port)**\\
描述：白平衡设置\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：无

**colorSensor_readRed(port)**\\
描述：读取红色分量\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~65535，整数

**colorSensor_readGreen(port)**\\
描述：读取绿色分量
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~65535，整数

**colorSensor_readBlue(port)**\\
描述：读取蓝色分量\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~65535，整数

**colorSensor_readLight(port)**\\
描述：读取光强\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~65535，整数


示例：
<sxh python; first-line: 1;highlight: [89,92]; title: colorSensor_test.py>
import machine
from microbit import *
#write your program:
from elfshield import *
import time
import music

colorSensor_setLight(PORT_A,1)
time.sleep_ms(1000)
colorSensor_setLight(PORT_A,0)
time.sleep_ms(1000)
colorSensor_setLight(PORT_A,1)
time.sleep_ms(1000)
colorSensor_whiteBalance(PORT_A)   
while True:
    print("Red: ",colorSensor_readRed(PORT_A))
    print("Blue: ",colorSensor_readBlue(PORT_A))
    print("Green: ",colorSensor_readGreen(PORT_A))
    print("Light: ",colorSensor_readLight(PORT_A))
    time.sleep_ms(100) 
    
</sxh>
\\

==== 旋转电位器API ====

**potentiometer_value(port)**\\
描述：读取旋转电位器返回值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~255，整数

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: potentiometer_test.py>
from elfshield import *
import time

while True:
    print(potentiometer_value(PORT_A))
    time.sleep_ms(100)
    
</sxh>
\\

==== 滑动电位器API ====

**slidingPotentiometer_value(port)**\\
描述：读取滑动电位器返回值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~255，整数

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: slidingPotentiometer_test.py>
from elfshield import *
import time

while True:
    print(slidingPotentiometer_value(PORT_A))
    time.sleep_ms(100)
    
</sxh>
\\

==== 全向摇杆模块API ====

**joystick\_readX\_axis(port)**\\
描述：读取摇杆X轴方向的值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~255，整数

**joystick\_readY\_axis(port)**\\
描述：读取摇杆Y轴方向的值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~255，整数

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: joystick_test.py>
from elfshield import *
import time

while True:
    print("X: ",joystick_readX_axis(PORT_A))
    print("Y: ",joystick_readY_axis(PORT_A))
    time.sleep_ms(100)
    
</sxh>
\\

==== 单路触摸传感器API ====

**touchSensor_setMode(port,mode)**\\
描述：设置触摸传感器工作模式\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
^mode|模式0（默认）为当触摸时为True，释放为False；1为触摸后释放，保持True状态，再触摸释放，保持False状态|
返回值：无

**touchSensor_read(port)**\\
描述：读取触摸传感器状态\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：布尔值，True或False

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: touchSensor_test.py>
from elfshield import *
import time

touchSensor_setMode(PORT_A,0)
while True:
    r = touchSensor_read(PORT_A)
    print(r)
    time.sleep_ms(100)
    
</sxh>
\\

==== 4位LED按键模块API ====

**led4button_readKey(port)**\\
描述：按键检测，读取按键值\\
参数：
^port|选择PORT口，范围PORT\_A~PORT\_D|
返回值：0~4,0无按键按下

示例：
<sxh python; first-line: 1;highlight: [89,92]; title: led4button_test.py>
from elfshield import *
import time

while True:
    print(led4button_readKey(PORT_A))
    time.sleep_ms(100)
    
</sxh>