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.

image

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