Output modules

Light

LED Matrix

led_matrix.show(image = "hi", index = 1)

Sets the image to be displayed on the LED matrix.

Parameters:

• image: character string. The default value is hi. The following figure shows the image on the LED matrix when image is set to hi.

 

 

To display an image that is not predefined, you need to set image to the hexadecimal number corresponding to the image. The hexadecimal numbers are obtained as follows:

Take the on/off state of the eight LEDs on one column as an 8-digit binary number. Convert the 8-digit binary number into a 2-digit hexadecimal number. There is 16 columns, and therefore a 32-digit hexadecimal number can be used to indicate the on/off state of the LEDs. The following figure shows the LEDs on the LED matrix.

 

 

Example program 1

from halocode import *
led_matrix.show(image = "hello", index = 1) #Enables the LED matrix to display the image "hello"

 

Example program 2

from halocode import *
led_matrix.show(image = "00003c7e7e3c000000003c7e7e3c0000", index = 1) 
#Enables the LED matrix to display the image "hello"

 

led_matrix.print(message, index = 1)

Displays the specified characters on the LED matrix in scrolling mode.

Parameters:

• message: character string. The value can be a combination of any English characters, digits, and punctuations. Chinese characters are not supported. When exceeding the display range of the LED matrix, a message is displayed in scrolling mode.

 

led_matrix.print_until_done(message, index = 1)

Displays the specified characters on the LED matrix till the scrolling ends.

Parameters:

• message: character string. The value can be a combination of any English characters, digits, and punctuations. Chinese characters are not supported. When exceeding the display range of the LED matrix, a message is displayed in scrolling mode. The thread is blocked until the scrolling ends.

 

led_matrix.print_at(message, x, y, index = 1)

Displays the specified characters with the specified start point (x,y) on the LED matrix.

Parameters:

• message: character string. The value can be a combination of any English characters, digits, and punctuations. Chinese characters are not supported. When exceeding the display range of the LED matrix, a message is displayed in scrolling mode.
• x: numeric value ranging from 0 to 15, indicating the start x-coordinate
• y: numeric value ranging from 0 to 7, indicating the start y-coordinate

 

led_matrix.on(x, y, index = 1)

Lights up the LED in the specified position (x,y) on the LED matrix.

Parameters:

• x: numeric value ranging from 0 to 15, indicating the x-coordinate of the LED to be lit up
• y: numeric value ranging from 0 to 7, indicating the y-coordinate of the LED to be lit up

 

led_matrix.off(x, y, index = 1)

Turns off the LED in the specified position (x,y) on the LED matrix.

Parameters:

• x: numeric value ranging from 0 to 15, indicating the x-coordinate of the LED to be turned off
• y: numeric value ranging from 0 to 7, indicating the y-coordinate of the LED to be turned off

 

led_matrix.toggle(x, y, index = 1)

Changes the state (on/off) of the LED in the specified position (x,y) on the LED matrix.

Parameters:

• x: numeric value ranging from 0 to 15, indicating the x-coordinate of the LED of which the state is to be changed
• y: numeric value ranging from 0 to 7, indicating the y-coordinate of the LED of which the state is to be changed

 

led_matrix.clear(index = 1)

Turns off all the LEDs on the LED matrix.

 

RGB LED

rgb_led.on(r, g, b, index = 1)

Sets the color of the RGB LED.

Parameters:

• r: numeric value or character string
  To set r to a numeric value, indicating the value of the red component. The setting range is 0 to 255. The value 0 indicates no red component, and 255 indicates the maximum red component.
  To set r to a character string, the value is a color name or abbreviation. The following shows the color names and their abbreviations:

red r
orange o
yellow y
green g
cyan c
blue b
purple p
white w
black k

• g: numeric value, indicating the value of the green component. The setting range is 0 to 255. The value 0 indicates no green component, and 255 indicates the maximum green component.
• b: numeric value, indicating the value of the blue component. The setting range is 0 to 255. The value 0 indicates no blue component, and 255 indicates the maximum blue component.
• pct: numeric value. The setting range is 0 to 100, indicating the brightness of the LED. The default value is 100. When it is set to 0, the LED is turned off; and when it is set to 100, the LED is lit up in the color with the set red, green, and blue components.

 

rgb_led.off(index = 1)

Turns off the RGB LED.

 

rgb_led.set_red(val, index = 1)

Changes the R value of the RGB LED.

Parameters:

• val: numeric value, indicating the R value of the RGB LED after the change. The setting range is 0 to 255.

 

rgb_led.set_green(val, index = 1)

Changes the G value of the RGB LED.

Parameters:

• val: numeric value, indicating the G value of the RGB LED after the change. The setting range is 0 to 255.

 

rgb_led.set_blue(val, index = 1)

Changes the B value of the RGB LED.

Parameters:

• val: numeric value, indicating the B value of the RGB LED after the change. The setting range is 0 to 255.

rgb_led.add_red(val, index = 1)

Increases the R value of the RGB LED.

Parameters:

• val: numeric value, indicating the amount by which the R value of the RGB LED is increased. The setting range is –255 to +255.

 

rgb_led.add_green(val, index = 1)

Increases the G value of the RGB LED.

Parameters:

• val: numeric value, indicating the amount by which the G value of the RGB LED is increased. The setting range is –255 to +255.

 

rgb_led.add_blue(val, index = 1)

Increases the B value of the RGB LED.

Parameters:

• val: numeric value, indicating the amount by which the B value of the RGB LED is increased. The setting range is –255 to +255.

 

rgb_led.get_red(val, index = 1)

Obtains the R value of the RGB LED.

Returns a numeric value ranging from 0 to 255.

 

rgb_led.get_green(index = 1)

Obtains the G value of the RGB LED.

Returns a numeric value ranging from 0 to 255.

 

rgb_led.get_blue(index = 1)

Obtains the B value of the RGB LED.

Returns a numeric value ranging from 0 to 255.

 

LED Driver

led_driver.on(r, g, b, id = "all", index = 1)

Sets the color of the specified LED or all LEDs.

Parameters:

• r: numeric value or character string.
  To set r to a numeric value,indicating the value of the red component. The setting range is 0 to 255. The value 0 indicates no red component, and 255 indicates the maximum red component.
  To set r to a character string, the value is a color name or abbreviation. The following shows the color names and their abbreviations:

red r
orange o
yellow y
green g
cyan c
blue b
purple p
white w
black k

• g: numeric value, indicating the value of the green component. The setting range is 0 to 255. The value 0 indicates no green component, and 255 indicates the maximum green component.
• b: numeric value, indicating the value of the blue component. The setting range is 0 to 255. The value 0 indicates no blue component, and 255 indicates the maximum blue component.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.show(color, index = 1)

Sets color(s) for multiple LEDs.

Parameters:

• color: character string, in the format of "color1 color2 color3 color4 color5 color6 color7 color8 color9 color10 color11 color12", where colorx can be red, green, blue, yellow, cyan, purple, white, orange, or black, or it can also be r, g, b, y, c, p, w, o, or k, the abbreviation of a color name. When more than 12 LEDs are specified, only the first 12 LEDs are set.

 

led_driver.off(led_id = "all", index = 1)

Turns off the specified LED or all LEDs.

Parameters:

• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.set_red(val, led_id = "all", index = 1)

Changes the R value of the specified LED.

Parameters:

• val: numeric value, indicating the R value of the specified LED after the change. The setting range is 0 to 255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.set_green(val, led_id = "all", index = 1)

Changes the G value of the specified LED.

Parameters:

• val: numeric value, indicating the G value of the specified LED after the change. The setting range is 0 to 255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.set_blue(val, led_id = "all", index = 1)

Changes the B value of the specified LED.

Parameters:

• val: numeric value, indicating the B value of the specified LED after the change. The setting range is 0 to 255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.add_red(val, led_id = "all", index = 1)

Increases the R value of the specified LED.

Parameters:

• val: numeric value, indicating the amount by which the R value of the specified LED is increased. The setting range is –255 to +255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.add_green(val, led_id = "all", index = 1)

Increases the G value of the specified LED.

Parameters:

• val: numeric value, indicating the amount by which the G value of the specified LED is increased. The setting range is –255 to +255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.add_blue(val, led_id = "all", index = 1)

Increases the B value of the specified LED.

Parameters:

• val: numeric value, indicating the amount by which the B value of the specified LED is increased. The setting range is –255 to +255.
• id: character string or numeric value. The default value is all.
  To set id to a character string, the value must be all, indicating all LEDs.
  To set id to a numeric value, the setting range is 1 to 96, indicating the serial number of an LED.

 

led_driver.set_mode(mode = "steady", index = 50)

Sets the display mode of the LED driver.

Parameters:

• mode: character string. The values are described as follows:
  steady: static mode. In this mode, the LEDs are normally on.
  breath: blinking mode. In this mode, the LEDs blink periodically.
  marquee: marquee mode. In this mode, LEDs on the LED strip or LED ring are lit up in scrolling mode.

Play

Speaker

speaker.mute(index = 1)

Stops the playing of the speaker.

 

speaker.play_tone(freq, index = 1)

Sets the frequency of the speaker.

Parameters:

• freq: numeric value. The setting range is 20 to 20,000. The speaker makes no sound if the frequency you set exceeds the setting range. In addition, to protect your ears, the upper limit of the frequency is set to 5,000 Hz. If the value you set ranges from 5,000 to 20,000, the speaker plays sounds at the frequency of 5,000 Hz. To play a melody by changing the frequency of the speaker, you need to know the mapping between frequency and notes. The following is a reference.

	do / C	re / D	mi / E	fa / F	sol / G	la / A	si / B
2	65 Hz	73 Hz	82 Hz	87 Hz	98 Hz	110 Hz	123 Hz
3	131 Hz	147 Hz	165 Hz	175 Hz	196 Hz	220 Hz	247 Hz
4 (Standard Alto)	262 Hz	294 Hz	330 Hz	349 Hz	392 Hz	440 Hz	494 Hz
5	523 Hz	587 Hz	659 Hz	698 Hz	784 Hz	880 Hz	988 Hz
6	1047 Hz	1175 Hz	1319 Hz	1397 Hz	1568 Hz	1760 Hz	1976 Hz
7	2093 Hz	2349 Hz	2637 Hz	2794 Hz	3136 Hz	3520 Hz	3951 Hz
8	4186 Hz	4699 Hz

For example, the standard alto pitch (the first international pitch) is A4 = 440Hz.

 

speaker.play_music(music, index = 1)

Plays the specified preset or user-defined audio file by the speaker.

Parameters:

• music: character string. The value can be a 4-byte combination of any English characters, numbers, and punctuations, indicating the name of an audio file stored on the speaker. The speaker supports only mp3 files. This API function does not block the current thread when being implemented. A large number of short audio files are preset on the speaker. A large number of short audio files are preset on the speaker. For the file names and descriptions, click Preset sounds to download the list. For how to play a user-defined audio file, see Speaker.

 

speaker.play_music_until_done(music, index = 1)

Plays the specified preset or user-defined audio file by the speaker until the playing is complete.

Parameters:

• music: character string. The value can be a 4-byte combination of any English characters, numbers, and punctuations, indicating the name of an audio file stored on the speaker. The speaker supports only mp3 files. This API function blocks the current thread until the playing is complete.

 

speaker.set_vol(val, index = 1)

Sets the volume of the speaker.

Parameters:

• vol: numeric value, indicating the volume value of the speaker. The setting range is 0 to 100.

 

speaker.add_vol(val, index = 1)

Changes the volume of the speaker (not applicable to some sounds with special frequency).

Parameters:

• vol: numeric value, indicating the amount by which the volume of the speaker is changed. The setting range is –100 to +100.

 

speaker.get_vol(index = 1)

Obtains the volume of the speaker.

Returns a numeric value ranging from 0 to 100. The value 100 indicates the maximum volume of the speaker.

 

speaker.is_play(index = 1)

Determines whether the speaker is playing music.

Returns a boolean value:

True: playing music

False: not playing music

Motion

Motor Driver

motor_driver.set(power, index = 1)

Sets the output power of the motor driver.

Parameters:

• power: numeric value, indicating the output power of the motor driver. The setting range is –100 to +100, in percentage (%). The output power of 100% corresponds to the PWM waveform with a resolution of 1024. Generally, a positive value enables a motor to run counterclockwise, and a negative value enables a motor to run clockwise.

 

motor_driver.add(power, index = 1)

Increases the output power of the motor driver.

Parameters:

• power: numeric value, indicating the amount by which the output power of the motor driver is increased, in percentage (%). The setting range is –200 to +200. The output power of 100% corresponds to the PWM waveform with a resolution of 1024.

 

motor_driver.get(index = 1)

Obtains the output power of the motor driver.

Returns a numeric value ranging from –100 to +100.

 

motor_driver.get_load(index = 1)

Obtains the load value of the motor driver. The load value varies according to the operation of the connected motor. When the motor operates with a heavy load or is stalled (heavy load may also be caused by short circuit), a large load value is obtained.

Returns a numeric value ranging from 0 to 1024.

 

motor_driver.stop(index = 1)

Stops the power output of the motor driver.

 

Servo Driver

servo_driver.set(angle, index = 1)

Sets the angle the servo connected to the servo driver is located.

Parameters:

• angle: numeric number, indicating the angle the connected servo is located. The setting range is 0 to 180, in degrees (°).

 

servo_driver.add(angle, index = 1)

Sets the angle the connected servo rotates from the current position.

Parameters:

• angle: numeric number, indicating the angle the servo rotates from the current position. The setting range is –180 to +180, in degrees (°).

 

servo_driver.get(index = 1)

Obtains the angle the servo connected to the servo driver is located.

Returns a numeric value ranging from 0 to 180, in degrees (°).

 

servo_driver.get_load(index = 1)

Obtains the load value of the servo driver. The load value varies according to the operation of the connected servo. When the servo operates with a heavy load or is stalled (heavy load may also be caused by short circuit), a large load value is obtained.

Returns a numeric value ranging from 0 to 1024.

 

servo_driver.release(index = 1)

Releases the servo connected to the servo driver. After the servo is released, you can manually rotate it and the servo_driver.get(index) function can no longer obtains the correct angle of the servo.

 

Smart Servo Motor (12 Kg)

smart_servo.turn(angle, speed, index = 1)

Rotates the smart servo by the specified angle. This function blocks the current thread until the rotating is completed or suspended by another function.

Parameters:

• angle: numeric value, indicating the angle the servo rotates from the current position. A positive value indicates clockwise rotation, and a negative value indicates counterclockwise rotation.

 

smart_servo.turn_to(angle, speed, index = 1 )

Rotates the smart servo to the specified angle. This function blocks the current thread until the rotating is completed or suspended by another function.

Parameters:

• angle: numeric value, indicating the angle the servo is located after the rotation. A positive value indicates clockwise rotation, and a negative value indicates counterclockwise rotation.

 

smart_servo.run(power, index = 1)

Sets the speed at which the smart servo rotates.

Parameters:

• power: numeric value. The setting range is 0 to 100.

 

smart_servo.stop(index = "all")

Stops the motion of the smart servo.

Parameters:

• index: character string or numeric value. The default value is all, indicating all smart servos connected in the chain.

 

smart_servo.get_angle(index = 1)

Obtains the angle the smart servo is located.

Returns a numeric value, indicating the angle the smart servo rotates from the initial position.

 

smart_servo.get_speed(index = 1)

Obtains the rotating speed of the smart servo, either the automatic rotating or the rotating drived by external force.

Returns a numeric value. indicating the rotating speed, in degrees per second (°/s).

 

smart_servo.release_angle(index = "all")

Releases the smart servo. After the smart servo is released, it is no longer locked at the angle and you can rotate it manually. If you do not rotate it, it remains at the angle when it is released until any one of the following functions is executed:

smart_servo.turn(angle)

smart_servo.turn_to(angle)

smart_servo.drive(power, t = "forever")

smart_servo.lock_angle()

 

smart_servo.lock_angle(index = "all")

Locks the smart servo at the current angle. After being locked, a smart servo cannot be rotated by external force.

 

smart_servo.reset(index = "all")

Resets the smart servo. After being reset, the smart servo takes the current position as the zero point. The number of times a smart servo can be reset is limited, and therefore this function blocks the current thread for three seconds to prevent it from being executed again.