> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an Edge machine to an app

> Grant an app access to Edge hardware, select a default machine, pair printer aliases, and customize receipts.

Pairing an Edge machine connects it to your organization. Granting controls which apps in that
organization may use it.

## Grant the machine

<Steps>
  <Step title="Open the app's integrations">
    Open the app in Stardeck, go to **Settings**, and select **Integrations**.
  </Step>

  <Step title="Grant an Edge machine">
    Under **Edge Devices**, choose the paired machine and select **Grant**.

    Only machines in the same organization are available.
  </Step>

  <Step title="Choose a default">
    If the app can use more than one Edge machine, select the star beside the machine it should use
    by default.

    The default is used when the app sends a job without naming a particular machine or printer.
  </Step>
</Steps>

You can grant the same Edge machine to multiple apps. Removing a grant stops only that app from
using it; the machine remains paired to your organization.

## Pair a printer alias

An alias is a stable role used by the app, such as `front-counter`, `kitchen`, or
`customer-receipt`. The alias points to a physical printer.

This lets you replace a printer later without changing app code.

<Steps>
  <Step title="Open Printer Pairings">
    In the app's **Settings → Integrations**, find **Printer Pairings**.
  </Step>

  <Step title="Enter an alias">
    Use lowercase letters, numbers, hyphens, or underscores. Keep the name tied to the printer's
    job, not its model.
  </Step>

  <Step title="Choose the physical printer">
    Select a configured printer on one of the machines granted to this app, then select **Pair**.
  </Step>

  <Step title="Test the app flow">
    Run the app action that prints to this alias and confirm the job reaches the expected printer.
  </Step>
</Steps>

If hardware is removed or the machine grant is revoked, Stardeck keeps the alias and marks it as
broken. Re-pair the alias to restore the app without rebuilding it.

## Customize receipt branding

Under **Receipt Branding** in the same app settings:

* upload a PNG, JPEG, or WebP logo
* review the exact black-and-white print preview
* replace or remove the current logo
* turn the **Powered by Stardeck** footer mark on or off

Simple, high-contrast artwork prints best. Stardeck converts the image to a one-color thermal
printer format before storing it.

## Ask the agent to build an Edge feature

Once the grant exists, describe the behavior you want in the app's project chat:

```text theme={null}
Print a receipt on the front-counter printer after a successful cash payment,
then open the attached cash drawer.
```

The agent uses the Edge SDK and the granted connection automatically. Tell it which alias to use
if the app has more than one printer role.

## For developers

Server-side app code can use `@stardeck-customer-apps/edge-sdk`. Stardeck injects the required
connection settings into sandboxes and deployments, so no device secret needs to be copied into
the app.

```ts theme={null}
import { createEdgeClient } from "@stardeck-customer-apps/edge-sdk/server";

const edge = createEdgeClient();

await edge.print({
  alias: "front-counter",
  receipt: {
    header: { lines: ["My Shop"] },
    items: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }],
    total: 80,
    footer: { lines: ["Thank you"] },
  },
  openDrawer: true,
});
```

Use `listPeripherals()` and `testPrint()` to build an in-app pairing screen for location staff.
Handle offline and broken-binding errors by showing a retry or re-pairing action instead of a
generic failure.

## Control the receipt layout

For alignment, bold, text size, rules, spacing, or a different section order, send an ordered list
of blocks instead of the fixed fields:

```ts theme={null}
await edge.print({
  alias: "front-counter",
  receipt: {
    blocks: [
      { type: "text", text: "MY SHOP", align: "center", bold: true, size: "large" },
      { type: "separator" },
      { type: "items", rows: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }] },
      { type: "separator" },
      { type: "columns", left: "TOTAL", right: "80.00", bold: true, size: "large" },
      { type: "barcode", format: "qr", data: "https://example.com/r/1234", widthPercent: 50 },
    ],
  },
});
```

Available blocks: `text`, `columns`, `separator`, `spacer`, `items`, and `barcode`. Set
`paperWidth` on the receipt to lay out for 58mm or 80mm regardless of the printer.

A QR prints at the printer's default size unless the block sets `widthPercent` (5–100), the share
of the paper width it should take. The printed width is quantised to whole dots per cell and
rounded down, so the code lands on the nearest size at or below the request — and the preview
draws that size, not the request. More data means a denser symbol at the same width, so shorten a
long URL rather than shrinking the code further.

## Show an accurate preview in the app

`getCapabilities()` reports what the target printer can do — paper width and characters per line,
whether text prints as characters or as an image, Thai and Unicode coverage, supported barcodes,
cutter, and cash drawer. `renderReceiptPreviewHtml()` lays the receipt out with the same code the
printer uses, so an on-screen preview matches the paper.

```ts theme={null}
import { renderReceiptPreviewHtml } from "@stardeck-customer-apps/edge-sdk";

const capabilities = await edge.getCapabilities({ alias: "front-counter" });
const html = renderReceiptPreviewHtml(receipt, capabilities, { widthPx: 320 });
```

Capabilities are available even when the machine is offline, so previews keep working while the
hardware is down.

<Card title="Set up an Edge display" icon="display" href="/stardeck-edge/displays" horizontal>
  Show a fixed page or let the app change a screen live.
</Card>