Tuyaopen/peripheral Printer

TuyaOpen TDL Thermal Printer

Two driver protocol families exist; the same TDL API drives both:

• ESC/POS (e.g. DP48A) — supports text (UTF-8 → GBK auto-conversion) and bitmaps; handles job framing internally, so start() / end() return OPRT_NOT_SUPPORTED (harmless — ignore).
• RAW (e.g. MTP02-DXD) — bitmap only, no text; start() / end() are required to frame a job.

Write code that tolerates OPRT_NOT_SUPPORTED from start/end/send_text so it works on either driver.

Driver Registration (TDD)

Decide by adaptation, not by whether the SDK has the driver:

• Board-adapted printer (in board-context.md) → board_register_hardware() registers it (e.g. DP48A via tdd_printer_dp48_register(PRINTER_NAME, …)); the app only uses the TDL API below.
• Externally-attached printer (the user wired their own — NOT in board-context.md) → register it yourself in usr_board (see usr-board/SKILL.md), reusing the SDK's printer driver. board_register_hardware() only wires printers the board adapted.

Headers

#include "tdl_printer_manage.h"

Usage Template

#include "tal_api.h"
#include "tkl_output.h"
#include "tdl_printer_manage.h"

static TDL_PRINTER_HANDLE s_printer_hdl = NULL;

/* Status callback — runs in the monitor thread context. */
static void app_printer_event_cb(TDL_PRINTER_HANDLE handle,
                                 TDL_PRINTER_EVENT_E event,
                                 void *data, void *arg)
{
    (void)handle; (void)data; (void)arg;
    switch (event) {
    case TDL_PRINTER_EVENT_PAPER_OUT:   PR_WARN("paper out");         break;
    case TDL_PRINTER_EVENT_PAPER_IN:    PR_NOTICE("paper loaded");    break;
    case TDL_PRINTER_EVENT_OVERHEATED:  PR_WARN("head overheated");   break;
    case TDL_PRINTER_EVENT_TEMP_NORMAL: PR_NOTICE("temp normal");     break;
    case TDL_PRINTER_EVENT_ERROR:       PR_ERR("printer error");      break;
    default: break;
    }
}

void app_printer_print_text(const char *utf8_text)
{
    if (OPRT_OK != tdl_printer_find(PRINTER_NAME, &s_printer_hdl)) {
        PR_ERR("printer '%s' not found", PRINTER_NAME);
        return;
    }

    /* Pass NULL for param to skip status monitoring. */
    TDL_PRINTER_OPEN_PARAM_T open_param = {
        .event_cb         = app_printer_event_cb,
        .event_cb_arg     = NULL,
        .poll_interval_ms = 0,   /* 0 = use Kconfig default */
    };
    if (OPRT_OK != tdl_printer_open(s_printer_hdl, &open_param)) {
        PR_ERR("printer open failed");
        return;
    }

    /* UTF-8 in; ESC/POS drivers convert to GBK automatically.
     * Returns OPRT_NOT_SUPPORTED on RAW drivers — treat as "skip". */
    OPERATE_RET rt = tdl_printer_send_text(s_printer_hdl, utf8_text);
    if (rt != OPRT_OK && rt != OPRT_NOT_SUPPORTED) {
        PR_ERR("send_text failed: %d", rt);
    }

    tdl_printer_paper_feed(s_printer_hdl, 40);   /* feed to tear position */
    tdl_printer_close(s_printer_hdl);
}

Print a bitmap

TDL_PRINTER_DEV_INFO_T info = {0};
tdl_printer_get_dev_info(s_printer_hdl, &info);   /* dots_per_line = paper width */

tdl_printer_start(s_printer_hdl);                 /* RAW needs it; ESC/POS → NOT_SUPPORTED (ignore) */
/* bmp: 1-bit, row-major, MSB first, (width+7)/8 bytes per row */
tdl_printer_send_bitmap(s_printer_hdl, 0 /*x*/, width, height, bmp);
tdl_printer_end(s_printer_hdl);                   /* mirrors start() */

Scale images to info.dots_per_line so they fit the paper width — anything past the right edge is silently clipped.

API Reference

Status Events (TDL_PRINTER_EVENT_E)

Enable Macro and NAME Macro

CONFIG_ENABLE_PRINTER=y                 # enables the printer subsystem
CONFIG_PRINTER_NAME="printer"           # device name passed to tdl_printer_find()
CONFIG_PRINTER_POLL_INTERVAL_MS=500     # status poll interval (default)

For board-adapted printers the board Kconfig already selects these — do NOT write them. Only set them when adding a custom printer via usr_board.

PRINTER_NAME is the name passed to tdl_printer_find().

Reference Example

examples/peripherals/printer/