Elfshield Micropython API Reference

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

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:

indexSet the motor interface, 1 for M1 and 2 for M2
speedSet 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:

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)
    

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:

indexSet the servo interface, 1 for Servo1 and 2 for Servo2
angleSet the steering angle of the servo, range: 0~180, the angle is only an integer.

Return_Value: None

An Example:

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)
    

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:

import music
import time

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

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


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:

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)
    

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

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

An Example:

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

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

ultrasonic_setColor(port,index,red,green,blue)
Description:Set the color of the ultrasonic built-in RGB light and display.
Parameter:

portSelect port, range PORT_A~PORT_D
indexSelect RGB lights, range 1~3, 1 for left, 2 for right, 3 for all
redred value
greengreen value
blueblue 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:

portSelect port, range PORT_A~PORT_D
indexSelect LED lights, range 1~3, 1 for left, 2 for right, 3 for all
statusSet 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:

portSelect port, range PORT_A~PORT_D

Return_Value: 3~500 (unit: cm)

An Example:

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)   
     

lineFollower_read(port,index)
Description:Get line follower sensor measurement distance.
Parameter:

portSelect port, range PORT_A~PORT_D
indexSelect the probe, 1 for S1 and 2 for S2

Return_Value:0~1023, integer

An Example:

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)
    

digitalModule_showNumber(port,number)
Description:Digital tube display number.
Parameter:

portSelect port, range PORT_A~PORT_D
numberSet the number you want to display

Return_Value:None

An Example:

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)
    

waterAtomizer_set(port,status)
Description:Set the water atomizer module working status.
Parameter:

portSelect port, range PORT_A~PORT_D
statusWorking status, 0 does not work and 1 work

Return_Value:None

An Example:

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)
    

mp3setDevice(port,device)
Description:Set which storage device the MP3 module playing from.
Parameter: ^port|Select port, range PORTA~PORTD| ^device|2 for the TF card, 4 for the MP3 module onboard FLASH| Return_Value:None mp3setVolume(port,volume)
Description:Set the MP3 module volume.
Parameter: ^port|Select port, range PORTA~PORTD| ^volume|volume value| Return_Value:None mp3playMusic(port,index)
Description:Select song and play it.
Parameter: ^port|Select port, range PORTA~PORTD| ^index|Select a song, range: 1~3000| Return_Value:None mp3play(port)
Description:play.
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:None mp3pause(port)
Description:pause.
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:None mp3prevMusic(port)
Description:previous music.
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:None mp3nextMusic(port)
Description:next music.
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:None mp3isOver(port)
Description:Determine if the audio has finished playing or not.
Parameter: ^port|Select port, range PORTA~PORTD| 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 mp3setVolume(PORTA,20) mp3playMusic(PORTA,3) display.show(Image.HAPPY) while True: r = led4buttonreadKey(PORTB) print® if(r == 1): time.sleepms(100) if (r == 1): mp3play(PORTA) elif(r == 2): time.sleepms(100) if (r == 2): mp3pause(PORTA) elif(r == 3): time.sleepms(100) if (r == 3): mp3nextMusic(PORTA) elif(r == 4): time.sleepms(100) if (r == 4): mp3prevMusic(PORTA)
time.sleep_ms(10)
</sxh>
====5V 130 Motor Module API==== dc130motorspeed(port,speed)
Description:Drive 5V 130 motor.
Parameter: ^port|Select port, range PORTA~PORTD| ^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: dc130motorspeed(PORTA,255) time.sleepms(1000)
dc130motor
speed(PORTA,-255) time.sleepms(1000)
</sxh>
==== Relay Moudle API====
relayModule
set(port,status)

Description:Set relay status
Parameter: ^port|Select port, range PORTA~PORTD| ^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: relayModuleset(PORTA,0) time.sleepms(1000) relayModuleset(PORTA,1) time.sleepms(1000)
</sxh>
====RGBLED-5 Module API==== RGBLEDsetColor(port,index,red,green,blue)
Description:Set the color of the RGBLED-5 module and display it.
Parameter: ^port|Select port, range PORTA~PORTD| ^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: RGBLEDsetColor(PORTA,1,0,0,20) time.sleepms(100) RGBLEDsetColor(PORTA,2,0,0,20) time.sleepms(100) RGBLEDsetColor(PORTA,3,0,0,20) time.sleepms(100) RGBLEDsetColor(PORTA,4,0,0,20) time.sleepms(100) RGBLEDsetColor(PORTA,5,0,2,20) time.sleepms(100) RGBLEDsetColor(PORTA,0,20,20,20) time.sleepms(100) RGBLEDsetColor(PORTA,0,0,0,0) time.sleep_ms(100)
</sxh>
====Temperature and Humidity Sensor API==== humitureSensorreadTemperature(port)
Description:reading temperature
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:0~50 (unit: °C) humitureSensorreadHumidity(port)
Description:reading humidity
Parameter: ^port|Select port, range PORTA~PORTD| 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:”,humitureSensorreadHumidity(PORTA),“%”) print(“Temperature:”,humitureSensorreadTemperature(PORTA)) time.sleep_ms(500)
</sxh>
====Tilt Switch Sensor API==== tiltSwitchread(port,index)
Description:Read the module tilt status
Parameter: ^port|Select port, range PORTA~PORTD| ^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: ”,tiltSwitchread(PORTA,1)) print(“Sw2: ”,tiltSwitchread(PORTA,2)) time.sleep_ms(100)
</sxh>

====Flame Sensor API==== flameSensorreadValue(port,index)
Description:Read the value of the flame sensor probe
Parameter: ^port|Select port, range PORTA~PORTD| ^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: ”,flameSensorreadValue(PORTA,1)) print(“flameSensor2: ”,flameSensorreadValue(PORTA,2)) print(“flameSensor3: ”,flameSensorreadValue(PORTA,3)) time.sleep_ms(100)
</sxh>

====Gas Sensor API==== gasSensorreadValue(port)
Description:Read flammable gas concentration value
Parameter: ^port|Select port, range PORTA~PORTD| 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(gasSensorreadValue(PORTB)) time.sleep_ms(100)
</sxh>
====PIR Sensor API==== PIRsensorread(port)
Description:Detecting the status of the PIR sensor
Parameter: ^port|Select port, range PORTA~PORTD| 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(PIRsensorread(PORTA)) time.sleep_ms(100)
</sxh>
====Color Sensor API==== colorSensorsetLight(port,status)
Description:Set the status of the LED light on the color recognition sensor
Parameter: ^port|Select port, range PORTA~PORTD| ^status|0 is off and 1 is on| Return_Value:None colorSensorwhiteBalance(port)
Description:White balance setting
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:None colorSensorreadRed(port)
Description:Get red value
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:0~65535, integer colorSensorreadGreen(port)
Description:Get green value
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:0~65535, integer colorSensorreadBlue(port)
Description:Get blue value
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:0~65535, integer colorSensorreadLight(port)
Description:Get light value
Parameter: ^port|Select port, range PORTA~PORTD| 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 colorSensorsetLight(PORTA,1) time.sleepms(1000) colorSensorsetLight(PORTA,0) time.sleepms(1000) colorSensorsetLight(PORTA,1) time.sleepms(1000) colorSensorwhiteBalance(PORTA)
while True: print(“Red: ”,colorSensor
readRed(PORTA)) print(“Blue: ”,colorSensorreadBlue(PORTA)) print(“Green: ”,colorSensorreadGreen(PORTA)) print(“Light: ”,colorSensorreadLight(PORTA)) time.sleepms(100)
</sxh>
====Potentiometer Module API==== potentiometervalue(port)
Description:Read the rotary potentiometer value
Parameter: ^port|Select port, range PORTA~PORTD| 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(potentiometervalue(PORTA)) time.sleep_ms(100)
</sxh>
====Sliding Potentiometer Module API==== slidingPotentiometervalue(port)
Description:Read the slide potentiometer value
Parameter: ^port|Select port, range PORTA~PORTD| 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(slidingPotentiometervalue(PORTA)) time.sleep_ms(100)
</sxh>
====Joystick Module API==== joystickreadXaxis(port)
Description:Read the value of the joystick module in the X-axis direction
Parameter: ^port|Select port, range PORTA~PORTD| Return_Value:0~255, integer joystickreadYaxis(port)
Description:Read the value of the joystick module in the Y-axis direction
Parameter: ^port|Select port, range PORTA~PORTD| 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: ”,joystickreadXaxis(PORTA)) print(“Y: ”,joystickreadYaxis(PORTA)) time.sleep_ms(100)
</sxh>
====Single Touch Sensor API==== touchSensorsetMode(port,mode)
Description:Set the touch sensor working moden
Parameter: ^port|Select port, range PORTA~PORTD| ^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 touchSensorread(port)
Description:Read touch sensor status
Parameter: ^port|Select port, range PORTA~PORTD| 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 touchSensorsetMode(PORTA,0) while True: r = touchSensorread(PORTA) print® time.sleep_ms(100)
</sxh>
====Four LED Button Module API==== led4buttonreadKey(port)**
Description:Key detection, read the button value
Parameter: ^port|Select port, range PORT
A~PORTD| ReturnValue: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(led4buttonreadKey(PORTA)) time.sleep_ms(100)
</sxh>