Motherboard X iOS URL scheme

Use the URL scheme to send plain text to a board through the Motherboard X iOS app.

Before you start

Motherboard X must be installed and signed in. A board must be connected, or the app must have a known auto-connect target it can try to reconnect to.

The base scheme is motherboardX://. Although URL schemes are case-insensitive on iOS, generate URLs using motherboardX exactly.

Use lowercase query parameter names for the Motherboard X request. The send host and type value are matched case-insensitively.

Send text

motherboardX://send?type=text&data=Hello%20World&orientation=portrait

Parameter	Required	Description
type	Yes	Must be text.
data	Yes	Text to send, encoded as a URL query value. The URL handler accepts an empty value; it does not enforce the Web API’s non-empty-text rule.
orientation	No	landscape or portrait, case-insensitive. Defaults to landscape when omitted. An empty or unsupported value returns invalid_parameters.
x-success	No	URL to open after the operation succeeds. Must be URL-encoded.
x-error	No	URL to open after the operation fails. Must be URL-encoded.

Literal \n sequences in decoded data are converted to line breaks. For example, data=Hello%5CnWorld sends two lines, and the success callback contains that normalized text. Actual line breaks encoded as %0A also work.

Include callbacks

Encode each callback URL as a query value, including its own scheme and query parameters. Existing query parameters on the callback are preserved.

For example, your app could use source=motherboard-x to identify the integration and a custom requestID parameter to match callbacks to requests. The 123 below is just an example value; both parameters are optional and defined by your app:

partnerapp://motherboard/success?source=motherboard-x&requestID=123
partnerapp://motherboard/error?source=motherboard-x&requestID=123

Your app supplies these values when building the request, and Motherboard X returns them unchanged on both success and failure. The source value is a routing hint; it does not authenticate the app opening the callback.

Replace partnerapp with your app’s registered scheme and handle those callback routes. The complete encoded request is a single URL:

motherboardX://send?type=text&data=Hello%20World&orientation=portrait&x-success=partnerapp%3A%2F%2Fmotherboard%2Fsuccess%3Fsource%3Dmotherboard-x%26requestID%3D123&x-error=partnerapp%3A%2F%2Fmotherboard%2Ferror%3Fsource%3Dmotherboard-x%26requestID%3D123

Build and open a URL in Swift

This example includes whichever callback URLs you provide and appends requestID when supplied. Existing callback parameters are preserved.

Pass raw text and request IDs; URLQueryItem handles the encoding.

import UIKit

@MainActor
func sendTextToMotherboard(
    _ text: String,
    orientation: String = "landscape",
    successURL: URL? = nil,
    errorURL: URL? = nil,
    requestID: String? = nil
) async -> Bool {
    var queryItems = [
        URLQueryItem(name: "type", value: "text"),
        URLQueryItem(name: "data", value: text),
        URLQueryItem(name: "orientation", value: orientation),
    ]

    for (name, callbackURL) in [("x-success", successURL), ("x-error", errorURL)] {
        guard var callbackURL else { continue }
        if let requestID {
            callbackURL.append(queryItems: [URLQueryItem(name: "requestID", value: requestID)])
        }
        queryItems.append(URLQueryItem(name: name, value: callbackURL.absoluteString))
    }

    var url = URL(string: "motherboardX://send")!
    url.append(queryItems: queryItems)
    return await UIApplication.shared.open(url)
}

For example, call it from a button action. Choose URLs your app already handles; the routes, source parameter, and request ID below are example choices:

Task { @MainActor in
    let opened = await sendTextToMotherboard(
        "Hello World",
        orientation: "portrait",
        successURL: URL(string: "partnerapp://motherboard/success?source=motherboard-x"),
        errorURL: URL(string: "partnerapp://motherboard/error?source=motherboard-x"),
        requestID: "123"
    )
    if !opened {
        print("Could not open Motherboard X. Check that it is installed.")
    }
}

The returned Boolean reports whether iOS opened the request URL. Send results arrive at the callback URLs you supply, with their preserved parameters and requestID, when present.

Success callback

Motherboard X opens x-success after the operation succeeds and appends text, containing the normalized text sent to the board.

partnerapp://motherboard/success?source=motherboard-x&requestID=123&text=Hello%20World

Success means the app’s send operation completed; it is not a separate check that the text is visibly rendered.

Error callback

Motherboard X opens x-error after failure and appends errorMessage, a machine-readable reason. Read that query parameter when handling the callback.

errorMessage	Meaning
invalid_parameters	A required parameter is missing, or the send-text orientation is invalid.
unsupported_request	The host or type is not implemented.
not_authenticated	Motherboard X is not signed in.
not_connected	No board is connected and no auto-connect target is available.
auto_connect_failed	The app tried to reconnect to a known board and failed.
send_failed	Sending text failed after connecting.

For example, a failure to connect can return:

partnerapp://motherboard/error?source=motherboard-x&requestID=123&errorMessage=not_connected

Connection and callback timing

• The app communicates with the board over BLE or WebSocket, reconnecting to a known board when needed.
• A send failure does not prove that the board did nothing; avoid blindly retrying a send.
• Connection and command handling share a 10-second deadline for sending text. This is an internal time budget, not a guarantee that the callback will open within that time.
• Callbacks are deferred until the app and its scene are active. An omitted or unusable callback URL gives the caller no callback for that outcome.
• Submit one URL request at a time and wait for its callback. A new request cancels the previous in-flight task, and only the newest deferred callback is retained; overlapping requests may leave an earlier caller without a callback.

Unsupported operations

Sending drawing paths and reading raw drawing paths are not supported by this public interface.

For HTTP integration and display zones, use the Web API.