Skip to content

Glasses hardware APIs: gm_plugin.h

Start with GlassSDK/include/gm_plugin.h in the toolkit for hardware APIs. Read the function tables, capability bits, and parameter descriptions before the corresponding examples.

Start with these three headers#

  1. Open GlassSDK/include/gm_plugin.h and find gm_plugin_host_api_t, the core service table that the glasses firmware provides to plugins.
  2. Find gm_plugin_descriptor_t, which defines callbacks such as on_start, on_loop, and on_event that your plugin implements.
  3. For UI drawing, continue with gm_plugin_lvgl_api.h. For random numbers, LZ4, and common C string/memory operations, see gm_plugin_extensions.h and gm_plugin_libc.h.

Core API quick reference#

What you want to doEntry in gm_plugin.hUsage considerations
Logging and timinghost->log、host->monotonic_mslog arguments must match the format string. monotonic_ms is a wrapping uint32 millisecond counter. Use unsigned subtraction to calculate intervals; do not treat it as a date/time.
Allocate and free memoryhost->alloc、host->freeCheck for NULL and pair allocations with releases. Do not substitute an assumed system heap.
Query display dimensions and pixel formathost->display_get_infoUse the returned dimensions and format. Do not assume the simulator's dimensions are fixed for all hardware.
Text, controls, pictureshost->graphics.lvglFunction defined in gm_plugin_lvgl_api.h; Create UI in on_start, check the LVGL table version.
Per-pixel drawinghost->graphics.framebuffer.lock / unlockFollow the returned tile, y, and stride. Do not call LVGL while the framebuffer is locked.
Display power, brightness, position, and distancehost->display_controlCheck GM_PLUGIN_CAP_DISPLAY_CONTROL first. Use the enum definitions for setter values.
Receive button inputplugin->on_event：GM_PLUGIN_EVENT_BUTTONCheck both button and action. Primary-button single/double clicks differ from navigation-button TRIGGER events.
Raw IMU and head gestureshost->imu_enable、host->imu_read；GM_PLUGIN_EVENT_IMU_GESTUREEnable the required mode first. A sample may be temporarily unavailable; handle GM_PLUGIN_EBUSY.
Business messages between phone and glasseshost->bt_send；GM_PLUGIN_EVENT_BT_MESSAGEUse application-defined channels. The callback payload is borrowed memory; copy it before asynchronous use.
Battery level, charging, and wear statehost->battery_percent、battery_charging、wearingCheck GM_PLUGIN_CAP_DEVICE_STATE. This does not request low-level hardware control.
Read the languagehost->locale_getPass a buffer of size GM_PLUGIN_LOCALE_TAG_MAX. Check the result before using the language tag.
Exit and extensionshost->app_exit、host->extension_getReturn from the current callback promptly after requesting exit. If an extension query fails, fall back or explicitly refuse startup.

Display controls: calls and values#

Functions (all under host->display_control)Parameters or results
screen_is_on() / screen_turn_on(on)Query display power; on=true turns it on, and on=false turns it off.
brightness_get() / brightness_set(level)Fixed brightness levels 1–10, using GM_PLUGIN_DISPLAY_BRIGHTNESS_LEVEL_*.
distance_get() / distance_set(level)Optical distance levels 0–8, using GM_PLUGIN_DISPLAY_DISTANCE_LEVEL_*. These are not distances in meters.
height_get() / height_set(level)Vertical display position levels 0–8, using GM_PLUGIN_DISPLAY_HEIGHT_LEVEL_*. These are not pixel coordinates.
auto_brightness_block(blocked)true temporarily blocks automatic brightness; false releases the block. The Host releases any remaining block when the plugin stops.

Reading input, IMU and message data#

  • Buttons: check both button and action in event->data.button. PRIMARY supports SINGLE, DOUBLE, LONG, VERY_LONG, and RELEASE. Direction, page, scroll, back, and home inputs use TRIGGER. Follow the constants in the header and ignore unknown combinations.
  • IMU: after enabling RAW, read accel_raw[3], gyro_raw[3], temperature_raw and pitch_degrees. The first three contain raw sensor values; do not interpret them directly as m/s², angular velocity or degrees Celsius. pitch_degrees is an integer angle.
  • Head gestures: enable GESTURES to receive GM_PLUGIN_EVENT_IMU_GESTURE, then check gesture and active. Validate recognition while wearing the physical glasses.
  • Messages: event->data.bt in GM_PLUGIN_EVENT_BT_MESSAGE contains channel, data, and length. Validate length before decoding, and do not retain a reference to data after the callback.
  • Examples: GlassSDK/examples/input, imu, and bluetooth. Use web_bridge for standard Web display and display_control_lab for custom paired messages.

Checks before using each capability#

  • At entry, check host/plugin pointers, struct_size, and GM_PLUGIN_VERSION_COMPATIBLE. Preserve the descriptor capacity supplied by the Host.
  • Check GM_PLUGIN_CAP_* flags in capabilities and validate the function pointers you use. An API's presence in a header does not guarantee that your firmware provides it.
  • After querying an extension, check the query result, table size, and version before reading its functions. Do not use casts to bypass compatibility checks.
  • Handle GM_PLUGIN_EINVAL, ENOTSUP, EBUSY, ENOMEM, EIO, EPERM, ESTATE, and EVERSION, as well as success.

Example: read the IMU in a callback after entry validation#

This is an integration snippet, not a standalone C project. Enable the IMU when you begin using it, and read it in your existing on_loop. Do not sleep in a loop waiting for samples.

< / >
/* Start raw sampling when this feature becomes active. */
gm_plugin_result_t enabled = host->imu_enable(GM_PLUGIN_IMU_ENABLE_RAW);

/* In a later on_loop call, after enabled == GM_PLUGIN_OK: */
gm_plugin_imu_sample_t sample;
gm_plugin_result_t result = host->imu_read(&sample);
if (result == GM_PLUGIN_OK) {
    /* Consume sample fields documented in gm_plugin.h. */
} else if (result == GM_PLUGIN_EBUSY) {
    /* No sample yet: return and try on a later iteration. */
}

/* When the feature stops using IMU: */
host->imu_enable(GM_PLUGIN_IMU_ENABLE_NONE);

Features not called directly through GMP hardware APIs#

Use PhoneSDK/App capabilities for network requests, user file selection, phone location, and Web audio. Do not infer unexposed camera, Flash, firmware-update, or arbitrary driver-control APIs from gm_plugin.h. Native glasses plugins must not assume a complete operating system or filesystem.

Check values and support first#

Reference files in the toolkit#

  • GlassSDK/include/gm_plugin.h
  • GlassSDK/include/gm_plugin_lvgl_api.h
  • GlassSDK/include/gm_plugin_extensions.h
  • GlassSDK/include/gm_plugin_libc.h
  • GlassSDK/docs/CAPABILITY_MATRIX.md