APIs for Function Extension
APIs for Function Extension
Display+
In addition to extending functions through extension boards and electronic modules, CyberPi can extend functions through its components and parts. Currently, the Sprites and Doodle APIs are provided to extend the functions of CyberPi’s screen. More APIs are being developed.
Tips: These APIs support only MicroPython programming and can’t be used in combination with Python 3 libraries. Use thses APIs only in Upload mode. For details about the description and instructions of the programming modes, see “Live and Upload modes.”
Sprites
The Sprites APIs enable you to make the maximum use of CyberPi’s screen for creation. With these APIs, you can make various games and UIs.
Setting the background
background.fill(r, g, b)
Initiates the background of the screen
Currently, you can set the entire background to only one color. You can’t set a multi-color background.
Parameters:
- r: int, intensity of the red color, ranging from 0 to 255
- g: int, intensity of the green color, ranging from 0 to 255
- b: int, intensity of the blue color, ranging from 0 to 255
background.copy()
Copies all the elements displayed on the screen to serve as the background
Currently, this API is not open to users.
Creating sprites
sprite1 = cyberpi.sprite()
Declares a sprite
sprite.pixel_set(color, x, y)
Changes the color of a pixel (defined by the x- and y- coordinates)
Currently, this API is not open to users.
Parameters:
- color: str, color value to be set for the pixel, ranging from “0x000000” to “0xFFFFFF”
- x: int, x-coordinate of the pixel, ranging from 0 to 127
- y: int, y-coordinate of the pixel, ranging from 0 to 127
The coordinates of CyberPi’s screen are defined as follows.
sprite.draw_text(text)
Defines a text as a sprite
By default, the font size of the text is 16 pixels.
Parameter:
- text: str, character string to be used as the sprite
If you enter a text in a language that is not supported by the character library, garbage characters are displayed. CyberPi supports the following languages:
- ✅Simplified Chinese (SC)
- ✅English (EN)
- ✅French | Français
- ✅Spanish | Español
- ✅Traditional Chinese | 繁體中文
- ✅German | Deutsch
- ✅Italian | Italiano
- ✅Portuguese | Português
- ✅Russian | русский язык
- ✅Korean | 한국어
- ✅Japanese | 日本語
- ✅Dutch | Nederlands
sprite.draw_icon(name)
Defines an icon as a sprite
Parameter:
name: str, name of the icon to be used as the sprite
The following table describes the icons and their names.
| Value | Icon | Value | Icon | |
| “music” |  |
“download” |  |
|
| “image” |  |
“sunny” |  |
|
| “video” |  |
“cloudy” |  |
|
| “clock” |  |
“rain” |  |
|
| “play” |  |
“snow” |  |
|
| “pause” |  |
“train” |  |
|
| “next” |  |
“rocket” |  |
|
| “prev” |  |
“truck” |  |
|
| “sound” |  |
“car” |  |
|
| “temperature” |  |
“droplet” |  |
|
| “light” |  |
“distance” |  |
|
| “motion” |  |
“fire” |  |
|
| “home” |  |
“magnetic” |  |
|
| “gear” |  |
“gas” |  |
|
| “list” |  |
“vision” |  |
|
| “right” |  |
“color” |  |
|
| “wrong” |  |
“overcast” |  |
|
| “shut_down” |  |
“sandstorm” |  |
|
| “refresh” |  |
“foggy” |  |
|
| “trash_can” |  |
sprite.draw_pixel(pixel, x_size, y_size)
Defines a pixel pattern as a sprite
Parameters:
- pixel: array, hexadecimal array, describing the colors of pixels from left to right and from top to bottom of the pattern. For example, [0xFF0000, 0x00FF00, 0x0000FF] indicates that colors of the first three pixels of the pattern to be used are red, green, and blue, respectively.
- x_size: int, width of the pixel pattern, 16 by default
- y_size: int, height of the pixel pattern, 16 by default
Colors set for pixels that exceed the defined width (x_size) and height (y_size) are discarded, and areas without color settings are defined as transparent.
sprite.draw_QR(content)
Defines a QR code as a sprite
Parameter:
content: str, content of the QR code to be used as the sprite
sprite.draw_sketch()
Defines a sketch as a sprite
sprite.mirror(axis)
Reflects the sprite vertically or horizontally
Parameter:
- axis: str, the value range is as follows:
“x”: reflecting the sprite around the x-axis, that is, reflecting it vertically
“y”: reflecting the sprite around the y-axis, that is, reflecting it horizontally
sprite.delete()
Deletes the sprite
Moving sprites
sprite.set_align(align_point = “center”)
Sets the anchor point of the sprite
The anchor point of the sprite determines its central point when it moves or rotates.
Parameter:
- align_point: str, position of the anchor point; the value range is as follows:
“top_mid”: in the upper center of the sprite
“top_left”: in the upper left of the sprite
“top_right”: in the upper right of the sprite
“center”: in the center of the sprite
“mid_left”: in the middle left of the sprite
“mid_right”: in the middle right of the sprite
“bottom_mid”: in the lower center of the sprite
“bottom_left”: in the lower left of the sprite
“bottom_right”: in the lower right of the sprite
sprite.move_x(step)
Moves the sprite along the x-axis for the specified pixels
Parameter:
- step: int, number of pixels the sprite is to be moved
sprite.move_y(step)
Moves the sprite along the y-axis for the specified pixels
Parameter:
- step: int, number of pixels the sprite is to be moved
sprite.move_to(x, y)
Moves the sprite to the specified position (defined by the x- and y- coordinates)
Parameters:
- x: int, x-coordinate of the position
- y: int, y-coordinate of the position
sprite.move_random()
Moves the sprite to a random position
This API sets the x- and y-coordinates of the position randomly to values ranging from 0 to 127.
Rotating sprites
sprite.rotate(angle)
Rotates the sprite clockwise the specified degrees
Parameter:
- angle: int
sprite.rotate_to(angle = 90)
Rotates the sprite to the specified direction (defined by degrees)
Parameter:
- angle: int, 90° by default
Using the sound icon as the sprite, the following figure shows the degrees and their corresponding directions:
Scaling sprites
sprite.set_size(size = 100)
Sets the percentage for scaling the sprite uniformly
Parameter:
- size: int, 100% by default
sprite.set_scale(x_size = 100, y_size = 100)
Sets the percentage for scaling the width and height of the sprite
Parameters:
- x_size: int, percentage for scaling the width of the sprite, 100% by default
- y_size: int, percentage for scaling the height of the sprite, 100% by default
Currently, this API is not open to users.
Setting colors
sprite.set_color(r, g, b)
Sets the color of the sprite
With this API, all the non-empty pixels are rendered in the specified color.
Parameters:
- r: int, intensity of the red color of the color filter, ranging from 0 to 255
- g: int, intensity of the green color of the color filter, ranging from 0 to 255
- b: int, intensity of the blue color of the color filter, ranging from 0 to 255
sprite.close_color()
Removes the color filter
This API restores the sprite to the initial state defined by draw_XXX().
Layer and display control
sprite.show()
Shows the sprite
By default, sprites are shown.
sprite.hide()
Hides the sprite
sprite.z_up(step)
Brings the sprite forward by the specified number of layers
Parameter:
step: int, number of layers by which the sprite is brought forward
sprite.z_down(step)
Sends the sprite backward by the specified number of layers
Parameter:
step: int, number of layers by which the sprite is sent back
sprite.z_max()
Brings the sprite to the front
sprite.z_min()
Sends the sprite to the back
Detection
display.color_get(x, y)
Obtains the color of the specified pixel (defined by x- and y-coordinates) displayed on the screen
Parameters:
- x: int, x-coordinate of the pixel, ranging from 0 to 127
- y: int, x-coordinate of the pixel, ranging from 0 to 127
A string is returned, indicating the hexadecimal value of the color, ranging from “0x000000” to “0xFFFFFF”.
sprite.is_touch(other_sprite)
Determines whether the sprite touches another one or the edge of the screen
When a non-empty pixel of a sprite comes in contact with that of another sprite, it is determined that the two sprites touch each other. When the x- or y-coordinate of one non-empty pixel of a sprite is greater than 128, it is determined that the sprite touches the edge of the screen.
Parameter:
other_sprite: sprite or str
When you set other_sprite to sprite, the value can be any one sprite, indicating that this API determines whether the sprite touches the specified one.
When you set other_sprite to str, the value can only be “edge”, indicating that this API determines whether the sprite touches the edge of the screen.
A bool value is returned.
sprite.get_align()
Obtains the anchor point of the sprite
A string is returned. The string can be one of the following:
“top_mid”: in the upper center of the sprite
“top_left”: in the upper left of the sprite2“
“top_right”: in the upper right of the sprite
“center”: in the center of the sprite
“mid_left”: in the middle left of the sprite
“mid_right”: in the middle right of the sprite
“bottom_mid”: in the lower center of the sprite
“bottom_left”: in the lower left of the sprite
“bottom_right”: in the lower right of the sprite
sprite.get_x()
Obtains the x-coordinate of the sprite
An int value is returned.
sprite.get_y()
Obtains the y-coordinate of the sprite
An int value is returned.
sprite.get_rotation()
Obtains the angle the sprite faces
An int value is returned. Value range: –180° to +180°
sprite.get_size()
Obtains the scaling of the sprite
When the width and height of the sprite are not scaled uniformly, the scaling is the square root of the product of x_size and y_size.
An int value is returned.
sprite.get_xsize()
Obtains the scaling of the width (along the x-coordinate) of the sprite
An int value is returned.
sprite.get_ysize()
Obtains the scaling of the height (along the y-coordinate) of the sprite
An int value is returned.
Rendering
screen.inable_autorender()
Enables the default rendering (ten frames) of the screen
screen.disable_autorender()
Disables the default rendering (ten frames) of the screen
screen.render()
Starts manual rendering
Doodle
sketch.clear()
Deletes all the sketches
sketch.start()
Puts the pen down to start sketching
sketch.end()
Lifts the pen up to stop sketching
sketch.set_speed(speed)
Sets the moving speed of the pen
Parameter:
- speed: int, speed at which the pen moves, ranging from 1 to 10
sketch.set_color(r, g, b)
Sets the color of the pen
Parameters:
- r: int or str
When you set r to int, the value indicates the intensity of the red color of the pen, ranging from 0 to 255.
When you set r to str, the value indicates the name or abbreviation of the color of the pen. The following describes the color names and abbreviations:
red r
orange o
yellow y
green g
cyan c
blue b
purple p
white w
black k
- g: int, intensity of the green color of the pen, ranging from 0 to 255
- b: int, intensity of the blue color of the pen, ranging from 0 to 255
sketch.set_size(size)
Sets the stroke size of the pen
The stroke cap of the pen is in the round shape.
Parameter:
- size: int, indicating the stroke size of the pen
sketch.cw(angle)
Rotates the pen the specified degrees clockwise
Parameter:
- angle: int, number of degrees the pen is rotated
sketch.ccw(angle)
Rotates the pen the specified degrees counterclockwise
Parameter:
- angle: int, number of degrees the pen is rotated
sketch.set_angle(angle)
Sets the angle the pen faces
sketch.move(step)
Moves the pen the specified number of pixels in the direction it faces
Parameter:
- step: int, number of pixels the pen moves
sketch.move_x(step)
Moves the pen the specified number of pixels from left to right along the x-axis
Parameter:
- step: int, number of pixels the pen moves along the x-axis
sketch.move_y(step)
Moves the pen the specified number of pixels from top to bottom along the y-axis
Parameter:
- step: int, number of pixels the pen moves along the y-axis
sketch.move_to(x, y)
Moves the pen to the specified position (defined by the x- and y-coordinates)
Parameters:
- x: int, x-coordinate of the pen
- y: int, y-coordinate of the pen
sketch.circle(r, angle)
Draws a circular arc with the specified radius and angle
The circle center is in the direction that is perpendicular to that the pen faces.
Parameters:
- r: int, radius of the circular arc the pen draws
- y: int, angles of the circular arc the pen draws
sketch.get_x()
Obtains the x-coordinate of the pen
An int value is returned.
sketch.get_y()
Obtains the y-coordinate of the pen
An int value is returned.
sketch.get_size()
Obtains the stroke size of the pen
An int value is returned.
sketch.get_angle()
Obtains the degrees of the direction the pen faces
An int value is returned.
sketch.if_start()
Determines whether the pen is put down
A bool value is returned.
sprite_sketch = sprite.draw_sketch()
Uses the sketch as the sprite