เชื่อมต่อเครื่อง Edge กับแอป

การจับคู่เครื่อง Edge คือการเชื่อมเครื่องเข้ากับองค์กรของคุณ ส่วนการอนุญาต (grant) ควบคุมว่าแอปใดในองค์กรนั้นใช้เครื่องได้

อนุญาตให้แอปใช้เครื่องคัดลอกลิงก์หัวข้อ

คุณอนุญาตเครื่อง Edge เครื่องเดียวกันให้หลายแอปได้ การเพิกถอนสิทธิ์จะหยุดเฉพาะแอปนั้นไม่ให้ใช้เครื่อง เครื่องยังคงจับคู่กับองค์กรของคุณอยู่

จับคู่ alias ของเครื่องพิมพ์คัดลอกลิงก์หัวข้อ

alias คือบทบาทคงที่ที่แอปใช้อ้างอิง เช่น front-counter, kitchen หรือ customer-receipt โดย alias ชี้ไปยังเครื่องพิมพ์จริง

ทำให้คุณเปลี่ยนเครื่องพิมพ์ภายหลังได้โดยไม่ต้องแก้โค้ดของแอป

หากถอดฮาร์ดแวร์ออกหรือเพิกถอนสิทธิ์ของเครื่อง Stardeck จะเก็บ alias ไว้และทำเครื่องหมายว่า broken จับคู่ alias ใหม่เพื่อให้แอปกลับมาใช้งานได้โดยไม่ต้องสร้างแอปใหม่

ปรับแต่งแบรนด์บนใบเสร็จคัดลอกลิงก์หัวข้อ

ใต้ Receipt Branding ในการตั้งค่าแอปเดียวกัน คุณทำได้ดังนี้:

• อัปโหลดโลโก้ PNG, JPEG หรือ WebP
• ดูตัวอย่างขาวดำที่ตรงกับที่จะพิมพ์จริง
• เปลี่ยนหรือลบโลโก้ปัจจุบัน
• เปิดหรือปิดเครื่องหมายท้ายใบเสร็จ Powered by Stardeck

ภาพที่เรียบง่ายและมีคอนทราสต์สูงพิมพ์ออกมาดีที่สุด Stardeck แปลงภาพเป็นรูปแบบสีเดียวของเครื่องพิมพ์ความร้อนก่อนเก็บ

ทดสอบโดยไม่มีฮาร์ดแวร์คัดลอกลิงก์หัวข้อ

เปิดเครื่องพิมพ์เสมือนเพื่อลองพิมพ์ก่อนติดตั้งเครื่องพิมพ์จริง ใน Settings → Integrations ของแอป หา Virtual printer แล้วเลือก Enable virtual printer จากนั้น จับคู่ alias กับ Virtual receipt printer ใน Printer Pairings

งานพิมพ์จาก sandbox และ preview deployment จะไปอยู่บนม้วนกระดาษในส่วนนั้น จัดวางตามความกว้างของ เครื่องพิมพ์ และมีป้ายแสดงเมื่อลิ้นชักเก็บเงินจะเปิด โลโก้แบรนด์ไม่ถูกวาด production ไม่เห็นเครื่องพิมพ์เสมือน ดังนั้นให้จับคู่เครื่องพิมพ์จริงกับ alias ก่อนเปิดใช้งานจริง

สร้างฟีเจอร์ Edge ด้วย agent ของคุณคัดลอกลิงก์หัวข้อ

เมื่อให้สิทธิ์แล้ว ให้อธิบายพฤติกรรมที่ต้องการกับ coding agent ใน repository ของแอป:

Print a receipt on the front-counter printer after a successful cash payment,
then open the attached cash drawer.

ทุกแอปมี Edge SDK คือ @stardeck-customer-apps/edge-sdk ไฟล์ SKILL.md ใน node_modules/@stardeck-customer-apps/edge-sdk/ คือเอกสารอ้างอิง API ที่ agent ใช้ทำงาน บอก agent ว่าให้ใช้ alias ไหน หากแอปมีเครื่องพิมพ์หลายบทบาท

ผ่านการเชื่อมต่อ MCP ขององค์กร agent ยังอนุญาตเครื่อง จับคู่ alias ตั้งค่าจอแสดงผล และเปิดเครื่องพิมพ์เสมือนได้ด้วย ทุกการเปลี่ยนแปลงจะแสดงตัวอย่างให้คุณยืนยันก่อน ดู เครื่องมือและสิทธิ์

สร้างบนเบราว์เซอร์อยู่ใช่ไหม ให้ส่งคำขอเดียวกันนี้ให้ Starcat Developer ในแท็บ Build ของแอป

พิมพ์จากโค้ดฝั่งเซิร์ฟเวอร์คัดลอกลิงก์หัวข้อ

โค้ดฝั่งเซิร์ฟเวอร์ของแอปใช้ @stardeck-customer-apps/edge-sdk Stardeck ใส่ค่าการเชื่อมต่อที่จำเป็น ให้ sandbox และ deployment เอง จึงไม่ต้องคัดลอก device secret ไปใส่ในแอป

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,
});

print() จะล้มเหลวหากเครื่องพิมพ์ออฟไลน์ชั่วครู่ สำหรับใบเสร็จที่ห้ามสูญหาย ให้ใช้ enqueueReceipt() Stardeck จะลองส่งซ้ำต่อเนื่องได้นานสูงสุด 10 นาที กฎของมันอยู่ใน SKILL.md ของ SDK

ใช้ listPeripherals() และ testPrint() เพื่อสร้างหน้าจับคู่ในแอปสำหรับพนักงานหน้าร้าน จัดการข้อผิดพลาดแบบออฟไลน์และ binding เสียด้วยการแสดงปุ่มลองใหม่หรือจับคู่ใหม่ แทนข้อความล้มเหลวทั่วไป

กำหนดรูปแบบใบเสร็จคัดลอกลิงก์หัวข้อ

หากต้องการจัดตำแหน่ง ตัวหนา ขนาดตัวอักษร เส้นคั่น ระยะห่าง หรือเรียงส่วนต่างๆ ใหม่ ให้ส่งรายการ block ที่เรียงลำดับ แทนฟิลด์แบบตายตัว:

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 },
    ],
  },
});

block ที่ใช้ได้: text, columns, separator, spacer, items และ barcode ตั้ง paperWidth ในใบเสร็จเพื่อจัดวางสำหรับ 58mm หรือ 80mm โดยไม่ขึ้นกับเครื่องพิมพ์

QR จะพิมพ์ที่ขนาดเริ่มต้นของเครื่องพิมพ์ เว้นแต่ block จะตั้ง widthPercent (5–100) ซึ่งคือสัดส่วนของ ความกว้างกระดาษที่ QR ควรใช้ ความกว้างที่พิมพ์จริงจะถูกปรับเป็นจำนวนเต็มของจุดต่อเซลล์ และปัดลง ดังนั้นโค้ดจะได้ขนาดที่ใกล้ที่สุดซึ่งไม่เกินที่ขอ ตัวอย่างจะวาดตามขนาดนั้น ไม่ใช่ตามที่ขอ ข้อมูลยิ่งมากสัญลักษณ์ยิ่งแน่นที่ความกว้างเท่าเดิม ดังนั้นให้ย่อ URL ที่ยาวแทนการย่อโค้ดให้เล็กลงอีก

แสดงตัวอย่างที่ตรงกับของจริงในแอปคัดลอกลิงก์หัวข้อ

getCapabilities() รายงานว่าเครื่องพิมพ์เป้าหมายทำอะไรได้บ้าง ได้แก่ ความกว้างกระดาษและจำนวนตัวอักษรต่อบรรทัด ข้อความพิมพ์เป็นตัวอักษรหรือเป็นภาพ การรองรับภาษาไทยและ Unicode บาร์โค้ดที่รองรับ ที่ตัดกระดาษ และลิ้นชักเก็บเงิน renderReceiptPreviewHtml() จัดวางใบเสร็จด้วยโค้ดเดียวกับที่ เครื่องพิมพ์ใช้ ตัวอย่างบนหน้าจอจึงตรงกับกระดาษ

import { renderReceiptPreviewHtml } from "@stardeck-customer-apps/edge-sdk";

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

Capabilities ใช้ได้แม้เครื่องออฟไลน์ ตัวอย่างจึงทำงานต่อได้ขณะที่ ฮาร์ดแวร์ใช้งานไม่ได้