WASM API

Boppo provides a WASM API to program new activities, interactive content, and games that run directly on Boppo.

Existing Language Libraries

To get started developing your own activities quickly its best to read the documentation for your language of choice:

• Rust: boppofun/rust_boppo_wasm
  • Run cargo generate boppofun/rust_boppo_wasm_template to create a new project using the suggested template
• AssemblyScript: coming soon
• If your preferred langauge does not exist and it has the ability to compile to WASM modules suitable for an ESP32 let us know your interested in a language binding or feel free to build your own using the WASM API below.

WASM API for Language Bindings

The following APIs are meant to be used by language binding libraries. For activity developers please read the API documentation for your language which will wrap the following in a more friendly API.

The Boppo tablet WASM runtime is WASIp1 compatible but not all WASI features are supported (e.g. filesystem APIs are not yet available).

Error Codes

Functions that return i32 return 0 on success or a negative error code on failure:

Code	Meaning
-1	NotFound — the handle does not exist or has already been unloaded
-2	PermissionDenied — the path is outside the allowed directories
-3	InvalidPath — the path string is not valid UTF-8 or cannot be resolved
-4	InvalidParameter — an unrecognised parameter value was passed
-255	Unknown — an unknown error occurred

Host Functions

boppo_poll(timeout_ms: i32) -> i64

If timeout_ms is less than 0, the function will block indefinitely until an event occurs. If timeout_ms is greater than 0 the function will return after the timeout if no host event occurred first. If timeout_ms is 0, the function will check for events and return immediately if none are available.

Returns a HostEvent represented as an i64. The least significant byte is the event type, and the remaining bytes are event-specific data.

Event types:

• 0: Exit

  The WASM activity should exit gracefully (i.e. return from the _start/main() function).

  Payload: None

• 1: Button

  A top button has been pressed or released.

  Payload: The two most significant bytes are a 2 byte payload. Of those 2 bytes, the least significant 4 bits are the button index of the event. The next 10 bits are the current pressed state (1 is pressed) of all ten 10 buttons (in index order). The 15th bit is if the current event is a press event (1) or a release event (0).

• 2: Finished Audio

  A sound with an active controller has finished playing. The controller is automatically freed when this event is returned from boppo_poll.

  Payload:

  • Bytes 1–7: controller ID as a 56-bit little-endian unsigned integer (lower 7 bytes of the u64 controller ID). Valid controller IDs are less than 2⁵³.

• 3: Timeout

  The timeout_ms has elapsed without another event occurring.

  Payload: None

boppo_set_and_flush_lights(framebuffer_colors: *void)

Sets all 40 of the device lights and flushes the lights to the hardware.

The passed in pointer must point to a buffer of 120 bytes. Each light is represented by a 3 byte color value (RGB).

The ordering of the lights is the same as defined in the Rust Lights struct

boppo_execute_command(command_ptr: *const u8, command_len: usize) -> i32

Executes a device command. The command must be a UTF-8 string passed as a pointer (command_ptr) with its byte length (command_len).

See the Commands reference for the full list of available commands.

Returns 0 on success, or -255 (Unknown) on failure.

boppo_play_sound_instruction(si_ptr: *const u8, si_len: usize) -> i32

Starts playback of a sound described by a JSON-encoded Sound Instruction. The JSON must be passed as a pointer (si_ptr) with its byte length (si_len).

See Sound Instruction for the full format reference. The WASM API additionally supports the controller instruction.

Path resolution within the instruction:

• Relative paths resolve to the activity's directory (the folder containing the .wasm file).
• Absolute paths (starting with /) resolve relative to the shared activities directory (/sd/activities), giving access to shared resources such as common sound-effect files.

Returns 0 on success, or a negative error code on failure (see Error Codes).

boppo_set_sound_controller_parameter(controller_id: u64, parameter: i32, value: f32) -> i32

Sets a playback parameter on the sound identified by controller_id. The ID must match an id used in a controller instruction passed to boppo_play_sound_instruction. Supported parameter values:

• 0: Stop — stop the sound and free the controller. value is ignored. A Finished Audio event is sent.
• 1: Pause — pause or unpause the sound. value of 0.0 unpauses; any other value pauses.
• 2: Volume — set the volume multiplier. 1.0 is the default level; values above 1.0 amplify the signal.
• 3: Speed — set the playback speed multiplier. 1.0 is normal speed.

Returns 0 on success, or a negative error code on failure (see Error Codes). Note that NotFound is returned if the controller_id does not match any active controller which includes when a sound has finished (since controllers are dropped when the sound finishes). Applications likely do not want to consider this an error.

boppo_stop_all_sounds()

Stops playback of all currently playing sounds. A Finished Audio event is sent for each sound that has an active controller. Sounds playing without a controller are stopped silently.

Module Exports

_start() (required)

As defined by WASIp1 this is the function the runtime will call to start the WASM activity. When this function returns the runtime will return to the active menu.

Runtime Environment

Stack Size

The WASM stack is 32 KB.

Environment Variables

Variable	Description
HOST_VERSION	The firmware version string of the host device.