Daemon REST API

🌿 papermintd HTTP REST API Specification

papermintd is a lightweight native HTTP microservice daemon built on Tokio and Axum. It allows web applications, mobile devices, local Electron POS systems, and microservices to print receipts, check real-time sensor status, and trigger cash drawers via standard JSON HTTP requests.

---

1. Running the Daemon

Launch the daemon locally:

# Run with default port (8080)
cargo run --package papermint-daemon

# Run on a custom port and host
PORT=9101 HOST=0.0.0.0 cargo run --package papermint-daemon

Output:

🌿 papermintd daemon listening on http://127.0.0.1:8080

---

2. API Endpoints

2.1 Health Check: GET /health

Returns daemon health and uptime.

• Request: GET /health
• Response (200 OK):

  {
    "status": "ok",
    "version": "0.1.0",
    "uptime_secs": 42
  }

---

2.2 Enumerate Devices: GET /api/devices

Discovers connected USB Class 7 printers and available serial/COM ports.

• Request: GET /api/devices
• Response (200 OK):

  {
    "serial_ports": ["/dev/ttyUSB0", "/dev/ttyS0"],
    "usb_printers": [
      {
        "vendor_id": 1208,
        "product_id": 514,
        "serial_number": "12345678",
        "manufacturer": "EPSON",
        "product_name": "TM-T20III"
      }
    ]
  }

---

2.3 Print Receipt: POST /api/print

Prints a structured JSON ticket or raw binary wire bytes to a target printer.

Targets:

• TCP: {"type": "tcp", "address": "192.168.1.200:9100"}
• USB: {"type": "usb", "vendor_id": 1208, "product_id": 514}
• Serial: {"type": "serial", "port": "/dev/ttyUSB0", "baud": 115200}
• Mock: {"type": "mock"} (Returns simulated receipt preview in ASCII)

Dialects:

• "escpos" (Epson, Bixolon, Citizen, Xprinter)
• "star" (StarPRNT TSP100, TSP650II, mC-Print)

Example 1: Printing a Structured Restaurant Ticket

curl -X POST http://localhost:8080/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"type": "mock"},
    "dialect": "escpos",
    "paper_width": "80mm",
    "ticket": {
      "title": "MINT BISTRO",
      "subtitle": "Table #4 - Order #1042",
      "address": "123 Market St, San Francisco",
      "metadata": [
        {"label": "Server", "value": "Luffy"},
        {"label": "Time", "value": "17:30"}
      ],
      "items": [
        {"qty": "2", "description": "Smashburger", "price": "$9.50", "total": "$19.00"},
        {"qty": "1", "description": "Truffle Fries", "price": "$5.00", "total": "$5.00"},
        {"qty": "2", "description": "Mint Iced Tea", "price": "$3.50", "total": "$7.00"}
      ],
      "totals": [
        {"label": "Subtotal", "value": "$31.00"},
        {"label": "Tax (8.5%)", "value": "$2.64"},
        {"label": "TOTAL", "value": "$33.64"}
      ],
      "qr": "https://mintbistro.com/pay/1042",
      "barcode": "10423364",
      "footer": "Thank you! Please visit us again.",
      "cut_mode": "full",
      "open_drawer": true,
      "beep": 1
    }
  }'

• Response (200 OK):

  {
    "success": true,
    "bytes_sent": 384,
    "mock_preview": "      MINT BISTRO      \nTable #4 - Order #1042\n..."
  }

Example 2: Sending Raw Wire Bytes

curl -X POST http://localhost:8080/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"type": "tcp", "address": "192.168.1.200:9100"},
    "dialect": "escpos",
    "raw_bytes": [27, 64, 72, 101, 108, 108, 111, 10, 29, 86, 0]
  }'

---

2.4 Query Hardware Sensor Telemetry: POST /api/status

Queries real-time printer sensors (paper roll, cover open, drawer state, head overheat, and cutter jam).

• Request:

  curl -X POST http://localhost:8080/api/status \
    -H "Content-Type: application/json" \
    -d '{
      "target": {"type": "tcp", "address": "192.168.1.200:9100"},
      "dialect": "escpos"
    }'

• Response (200 OK):

  {
    "is_online": true,
    "is_ready": true,
    "paper": "Adequate",
    "cover": "Closed",
    "drawer": "Closed",
    "cutter_error": false,
    "head_overheated": false
  }

---

2.5 Trigger Cash Drawer: POST /api/drawer

Sends an electrical solenoid kick pulse to open the cash drawer.

• Request:

  curl -X POST http://localhost:8080/api/drawer \
    -H "Content-Type: application/json" \
    -d '{
      "target": {"type": "tcp", "address": "192.168.1.200:9100"},
      "dialect": "escpos",
      "pin": 2
    }'

• Response (200 OK):

  {
    "success": true,
    "message": "Cash drawer kick command sent to Pin 2"
  }