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。 

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)

舵机驱动API

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

servo.angle(index,angle)
描述：设置舵机接口及角度。
参数：

index设置舵机接口，1为Servo1，2为Servo2
angle设置舵机旋转角度，范围：0~180，角度只能为整数

返回值：无

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

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)

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： 

import music
import time

while True: 
    music.play('c2:2')
    time.sleep_ms(100)

示例2： 

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)

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

示例： 

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)

elfshield模块

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

板载声音传感器API

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

示例： 

from microbit import *
#write your program:
from elfshield import *
import time

while True:
    value = volume_level()
    print(value)
    sleep(100)

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)

示例： 

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)

双路巡线传感器API

lineFollower_read(port,index)
描述：获取巡线传感器的值
参数：

port选择PORT口，范围PORT_A~PORT_D
index选择探头，1为S1，2为S2

返回值：0~1023，整数

示例： 

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)

数码管模块API

digitalModule_showNumber(port,number)
描述：数码管显示数字
参数：

port选择PORT口，范围PORT_A~PORT_D
number设置需要显示的数字

返回值：无

示例： 

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)

雾化器模块API

waterAtomizer_set(port,status)
描述：设置雾化器模块工作状态
参数：

port选择PORT口，范围PORT_A~PORT_D
status工作状态，0不工作，1工作

返回值：无

示例： 

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)

MP3模块API

mp3_setDevice(port,device)
描述：设置MP3模块从哪个存储设备播放
参数：

port选择PORT口，范围PORT_A~PORT_D
device2为选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播放器 

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)

5V 130电机模块API

dc130motor_speed(port,speed)
描述：驱动130电机
参数：

port选择PORT口，范围PORT_A~PORT_D
speed设置电机速度，正速度为顺时针转，负速度为逆时针转,速度范围：-255~255，速度只能为整数

返回值：无

示例： 

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)

继电器模块API

relayModule_set(port,status)
描述：设置继电器状态
参数：

port选择PORT口，范围PORT_A~PORT_D
status设置继电器状态，0为常闭接通，1为常开接通

返回值：无

示例： 

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)

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蓝色分量

返回值：无

示例： 

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)

温湿度传感器API

humitureSensor_readTemperature(port)
描述：温湿度传感器读取温度
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：0~50(单位：℃)

humitureSensor_readHumidity(port)
描述：温湿度传感器读取湿度
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：20~90（单位：百分比）

示例： 

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)

倾斜开关传感器API

tiltSwitch_read(port,index)
描述：读取模块倾斜状态
参数：

port选择PORT口，范围PORT_A~PORT_D
index选择需要读取的传感器，1或2

返回值：True或者False

示例： 

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)


火焰传感器API

flameSensor_readValue(port,index)
描述：读取火焰传感器探头的值
参数：

port选择PORT口，范围PORT_A~PORT_D
index选择需要读取的传感器，1~3

返回值：0~255，整数

示例： 

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)


可燃气体传感器API

gasSensor_readValue(port)
描述：读取可燃气体浓度值
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：0~255

示例： 

from elfshield import *
import time

while True:
    print(gasSensor_readValue(PORT_B))
    time.sleep_ms(100)

人体红外传感器API

PIRsensor_read(port)
描述：检测人体红外传感器状态
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：布尔值，True或者False

示例： 

from elfshield import *
import time

while True:
    print(PIRsensor_read(PORT_A))
    time.sleep_ms(100)

颜色识别传感器API

colorSensor_setLight(port,status)
描述：设置颜色识别传感器上面LED灯的状态
参数：

port选择PORT口，范围PORT_A~PORT_D
status0为灭，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，整数

示例： 

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)

旋转电位器API

potentiometer_value(port)
描述：读取旋转电位器返回值
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：0~255，整数

示例： 

from elfshield import *
import time

while True:
    print(potentiometer_value(PORT_A))
    time.sleep_ms(100)

滑动电位器API

slidingPotentiometer_value(port)
描述：读取滑动电位器返回值
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：0~255，整数

示例： 

from elfshield import *
import time

while True:
    print(slidingPotentiometer_value(PORT_A))
    time.sleep_ms(100)

全向摇杆模块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，整数

示例： 

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)

单路触摸传感器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

示例： 

from elfshield import *
import time

touchSensor_setMode(PORT_A,0)
while True:
    r = touchSensor_read(PORT_A)
    print(r)
    time.sleep_ms(100)

4位LED按键模块API

led4button_readKey(port)
描述：按键检测，读取按键值
参数：

port选择PORT口，范围PORT_A~PORT_D

返回值：0~4,0无按键按下

示例： 

from elfshield import *
import time

while True:
    print(led4button_readKey(PORT_A))
    time.sleep_ms(100)