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

=====microbit module=====

  When using the Elfshield board to drive your DC motors or servos, please add the following code before your script:
  from microbit import *
  
====DC Motor Driver API====

**motor.init()**\\
Description:Initialize before the motor is driven.\\
Parameter:None\\
Return_Value: None

**motor.runSpeed(index,speed)**\\
Description:Set the motor interface and speed.\\
Parameter:
^index|Set the motor interface, 1 for M1 and 2 for M2|
^speed|Set the motor speed, the positive speed is clockwise, the negative speed is counterclockwise, the speed range is -255~255, **the speed  is only an integer**.|
Return_Value: None

An Example：

<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>
\\

====Servo Drive API====

**servo.init()**\\
Description:Initialize before the servo is driven.\\
Parameter:None\\
Return_Value: None

**servo.angle(index,angle)**\\
Description:Set the servo interface and angle.\\
Parameter:
^index|Set the servo interface, 1 for Servo1 and 2 for Servo2|
^angle|Set the steering angle of the servo, range: 0~180, **the angle is only an integer**.|
Return_Value: None

An Example:

<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 module(Buzzer Driver API)=====

  When using the Elfshield board to drive the on-board buzzer, please write the following code before your script:
  import music

The Elfshield driver buzzer uses the official music module. The related API can be viewed by clicking on the following link:\\
[[https://microbit-micropython.readthedocs.io/en/latest/tutorials/music.html#]]\\

Example 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>

Example 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 module (RGB Light Driver API)=====

  When driving the on-board 3 RGB lights on the Elfshield board, or driving the strips via PORT_A~PORT_D, please write the following
  code before your script:
  import neopixel
  
Elfshield drives the RGB lamp using the official neopixel module, and the elfshield module only provides the IO port definition:

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

Please refer to the api of neopixel module at [[https://microbit-micropython.readthedocs.io/en/latest/neopixel.html]]

An Example：

<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) # Setup the Neopixel strip on OnBoard_RGB with a length of 3 pixels

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

        # Assign the current LED a random red, green and blue value between 0 and 50   
        red = randint(0, 50)
        green = randint(0, 50)
        blue = randint(0, 50)

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

         # Display the current pixel data on the Neopixel strip
        np.show()
        time.sleep_ms(500)
    np.clear()
    time.sleep_ms(500)
    
</sxh>
\\

=====elfshield module=====

  For the convenience of using the Elfshield board, please write the following code before the script:
  from elfshield import *

====Onboard Sound Sensor API====

**volume_level()**\\
Description:Get the value of the onboard sound sensor.\\
Parameter:None\\
Return\_Value: An integer from 0 to 1023

An Example:
<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 Ultrasonic Sensor Module API====

**ultrasonic_setColor(port,index,red,green,blue)**\\
Description:Set the color of the ultrasonic built-in RGB light and display.\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
^index|Select RGB lights, range 1~3, 1 for left, 2 for right, 3 for all|
^red|red value|
^green|green value|
^blue|blue value|
Return\_Value: None

**ultrasonic_setLED(port,index,status)**\\
Description:Drive two yellow LED lights on mini RGB ultrasonic (**only for mini RGB ultrasonic**).\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
^index|Select LED lights, range 1~3, 1 for left, 2 for right, 3 for all|
^status|Set the status of the LED light. 0 is off and 1 is bright|
Return\_Value: None

**ultrasonic\_getDistance(port)**\\
Description:Get ultrasonic measurement distance.\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
Return\_Value: 3~500 (unit: cm)

An Example:
<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>
\\

====Line Follower Sensor API====

**lineFollower\_read(port,index)**\\
Description:Get line follower sensor measurement distance.\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
^index|Select the probe, 1 for S1 and 2 for S2|
Return\_Value:0~1023, integer

An Example:
<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>
\\

====Digital Tube Module API====

**digitalModule\_showNumber(port,number)**\\
Description:Digital tube display number.\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
^number|Set the number you want to display|
Return\_Value:None

An Example:
<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>
\\

====Water Atomizer Module API====

**waterAtomizer\_set(port,status)**\\
Description:Set the water atomizer module working status.\\
Parameter:
^port|Select port, range PORT\_A~PORT\_D|
^status|Working status, 0 does not work and 1 work|
Return\_Value:None

An Example:
<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(2000)
    waterAtomizer_set(PORT_A,0)
    time.sleep_ms(1000)
    
</sxh>
\\

====MP3 Module API====

**mp3_setDevice(port,device)**\\
Description:Set which storage device the MP3 module playing from.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^device|2 for the TF card, 4 for the MP3 module onboard FLASH|
Return_Value:None

**mp3_setVolume(port,volume)**\\
Description:Set the MP3 module volume.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^volume|volume value|
Return\_Value:None

**mp3_playMusic(port,index)**\\
Description:Select song and play it.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^index|Select a song, range: 1~3000|
Return\_Value:None

**mp3_play(port)**\\
Description:play.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return\_Value:None

**mp3_pause(port)**\\
Description:pause.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return\_Value:None

**mp3_prevMusic(port)**\\
Description:previous music.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:None

**mp3_nextMusic(port)**\\
Description:next music.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:None

**mp3_isOver(port)**\\
Description:Determine if the audio has finished playing or not.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:Boolean value,**True** or **False**

An Example:\\
MP3 module and 4-bit button module form a simple MP3 player

<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 Motor Module API====

**dc130motor_speed(port,speed)**\\
Description:Drive 5V 130 motor.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^speed|Set the motor speed, the positive speed is clockwise, the negative speed is counterclockwise, the speed range is -255~255, **speed is only an integer**|
Return_Value:None

An Example:
<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>
\\

==== Relay Moudle API====

**relayModule_set(port,status)**\\
Description:Set relay status\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^status|Set the relay status, 0 is normally closed, 1 is normally open|
Return_Value:None

An Example:
<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 Module API====
**RGBLED_setColor(port,index,red,green,blue)**\\
Description:Set the color of the RGBLED-5 module and display it.\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^index|Select RGB lights, range 0~5, 0 for all|
^red|red value|
^green|green value|
^blue|blue value|
Return_Value: None

An Example:
<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>
\\

====Temperature and Humidity Sensor API====

**humitureSensor_readTemperature(port)**\\
Description:reading temperature\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~50 (unit: °C)

**humitureSensor_readHumidity(port)**\\
Description:reading humidity\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:20~90 (unit: %)

An Example:
<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>
\\

====Tilt Switch Sensor API====

**tiltSwitch_read(port,index)**\\
Description:Read the module tilt status\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^index|Select the sensor you want to read, 1 or 2|
Return_Value:Boolean value,**True** or **False**

An Example:
<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>  
\\

====Flame Sensor API====

**flameSensor_readValue(port,index)**\\
Description:Read the value of the flame sensor probe\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^index|Select the sensor you want to read, range 1~3|
Return_Value:0~255, integer

An Example:
<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>  
\\

====Gas Sensor API====

**gasSensor_readValue(port)**\\
Description:Read flammable gas concentration value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~255, integer

An Example:
<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>
\\

====PIR Sensor API====

**PIRsensor_read(port)**\\
Description:Detecting the status of the PIR sensor\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:Boolean value,**True** or **False**

An Example:
<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>
\\

====Color Sensor API====

**colorSensor_setLight(port,status)**\\
Description:Set the status of the LED light on the color recognition sensor\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^status|0 is off and 1 is on|
Return_Value:None

**colorSensor_whiteBalance(port)**\\
Description:White balance setting\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:None

**colorSensor_readRed(port)**\\
Description:Get red value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~65535, integer

**colorSensor_readGreen(port)**\\
Description:Get green value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~65535, integer

**colorSensor_readBlue(port)**\\
Description:Get blue value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~65535, integer

**colorSensor_readLight(port)**\\
Description:Get light value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~65535, integer

An Example:
<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>
\\

====Potentiometer Module API====

**potentiometer_value(port)**\\
Description:Read the rotary potentiometer value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~255, integer

An Example:
示例：
<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>
\\

====Sliding Potentiometer Module API====

**slidingPotentiometer_value(port)**\\
Description:Read the slide potentiometer value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~255, integer

An Example:
<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>
\\

====Joystick Module API====

**joystick_readX_axis(port)**\\
Description:Read the value of the joystick module in the X-axis direction\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~255, integer


**joystick_readY_axis(port)**\\
Description:Read the value of the joystick module in the Y-axis direction\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~255, integer

An Example:
<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>
\\

====Single Touch Sensor API====

**touchSensor_setMode(port,mode)**\\
Description:Set the touch sensor working moden\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
^mode|Mode 0(default):touched as **True**, released as **False**; Mode 1：keep True state when touched, then touch release, keep False state|
Return_Value:None

**touchSensor_read(port)**\\
Description:Read touch sensor status\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:Boolean value,**True** or **False**

An Example:
<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>
\\

====Four LED Button Module API====

**led4button_readKey(port)**\\
Description:Key detection, read the button value\\
Parameter:
^port|Select port, range PORT_A~PORT_D|
Return_Value:0~4,0 for no button pressed

An Example:
<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>