Skip to content

Paired development

Pair one MMPKG with one GMP as a single application when the phone needs a business page and the glasses need custom logic.

Run the existing Display Control Lab first#

Run the unified build once from the complete toolkit root. The script handles changes on both the glasses and Web sides automatically; you do not need to specify the two Display Control Lab example directories separately.

This example sends a limited set of control commands from a Web page. The GMP calls Host display-control APIs and returns status to the phone.

  1. In Studio, select Display Control Lab for both the phone and glasses, and check both selections.
  2. Adjust a value in the phone preview and confirm that a status reply arrives. The simulator does not reproduce the physical optical effect.
  3. After scanning on the phone, verify display control on the physical glasses. Check button-based recovery and the exit path after turning off the display.

macOS / Linux

< / >
./build.py

Windows PowerShell

< / >
py build.py

What to change when copying a paired example#

FileWhat to change
PhoneSDK/examples/display-control-lab/manifest.jsonYour Web id/name/version; deviceRequirements targeting the GMP's id/protocol; and device.messaging declarations for request and response channels.
GlassSDK/examples/display_control_lab/manifest.jsonYour glasses id/name/numeric version; provides.protocols matching the Web requirements.
PhoneSDK/examples/display-control-lab/display-control-protocol.jsCommand IDs, channels, field layouts, and result decoding.
GlassSDK/examples/display_control_lab/Check the corresponding command parsing, Host calls, and reply code. Do not change only one side.

The messaging path#

Web sends a request with gm.plugin.sendMessage(channel, Uint8Array). The GMP handles GM_PLUGIN_EVENT_BT_MESSAGE in on_event and replies with host->bt_send(channel, data, length). Web receives the reply through gm.plugin.onMessage(listener).

Requests reach glasses; results return to WebWeb sends a business-channel message. After App or Studio permission validation, it reaches the GMP as a BT_MESSAGE event. The GMP calls the Host API and replies through bt_send; Web handles the result in onMessage.MEMOMIND / MESSAGE ROUNDTRIPRequests reach glasses; results return to WebWeb PageApp / StudioGMP plugin① sendMessageRequest channel + payload② on_eventGM_PLUGIN_EVENT_BT_MESSAGE③ Handle therequestCall Host APIObtain the businessresult④ host->bt_sendReply Channel + requestId + State⑤ onMessageMatch the request and check the resultUpdate page after businessconfirmationAfter sending succeeds, keepwaiting for the resultThe App transfers over Bluetooth on devices; Studio forwards to the GMP simulator. Declarerequest and response channels, and correlate requests/results with requestId.
Requests reach glasses; results return to WebWeb sends a business-channel message. After App or Studio permission validation, it reaches the GMP as a BT_MESSAGE event. The GMP calls the Host API and replies through bt_send; Web handles the result in onMessage.MEMOMIND / MESSAGE ROUNDTRIPRequests reach glasses;results return to WebRequest: Web → host → GMP1. Web registers andsends the requestgm.plugin.sendMessagechannel + Binary payload2. App / StudiovalidationDeclarations, authorization, channel scopeBluetooth transfer tophysical glasses3. GMP handles therequeston_event：BT_MESSAGECall Host APIs for businesslogicResult: GMP → host → Web4. GMP sends thebusiness resulthost->bt_sendReply Channel + requestId +State5. Web handles the replygm.plugin.onMessageCheck requestId againstactual resultsThe App transfers over Bluetooth ondevices; Studio forwards to the GMPsimulator. Declare request andresponse channels, and correlaterequests/results with requestId.
Declare channels for both the outgoing request and its reply, and confirm completion using the business result.
  • A channel is a uint16 application-defined ID, not an IP port. Both request and response channels must appear in device.messaging.scope.channels.
  • Display Control Lab uses 17475 / 17476. Declaring only the request channel causes requests to be sent without receiving replies.
  • Version formats can differ: Web uses semantic versions, while glasses examples use numeric versions. Identical version numbers are not a pairing requirement.
  • Use request IDs, timeouts, and error results to avoid waiting indefinitely. Start with the example protocol; do not send low-level installation-protocol messages yourself.

Add acknowledgments and disconnection handling#

Display Control Lab uses requestId to match commands with status returned by the glasses and queries again after reconnection. Preserve this logic when copying the project. A successful send only means the message was submitted to the transport layer; you must also check the glasses' business result.

Why Studio reports a pairing mismatch#

Web deviceRequirements fieldMeaningHow to fix it
requiredPluginIdSelect the glasses plugin with this ID. An identical display name cannot substitute for an ID match.Check GMP manifest.id and update the requirements when copying a paired project.
preferredPluginIdProvides a preference for automatic selection. All other mandatory conditions still apply.With multiple candidates, check the actual selection rather than just the recommended name.
minPluginVersionSets a minimum target glasses-plugin version when requiredPluginId is specified.Build a GMP that meets the requirement. Do not copy the Web version string into the glasses' numeric version field.
protocolsThe target GMP's provides.protocols must satisfy every protocol ID and minimum version.Keep protocol implementations consistent with their declarations. Do not just delete a declaration to hide an error.

Reference files in the toolkit#

  • GlassSDK/docs/PROTOCOL_COMPATIBILITY.md
  • PhoneSDK/examples/display-control-lab/README.md
  • GlassSDK/examples/display_control_lab/manifest.json