# Fichero / AiYin D11 Thermal Label Printer
# Copyright 2026 Pigs Can Fly Labs LLC
# SPDX-License-Identifier: Apache-2.0

device:
  name: "Fichero / AiYin D11 Thermal Label Printer"
  manufacturer: "Xiamen Print Future Technology Co., Ltd"
  manufacturer_status: "unsupported"
  protocol: "ble"
  notes: >
    Compact thermal label printer sold as Fichero D11s / AiYin D11.
    Price $15-20. 96px printhead at 203 DPI. Li-Ion battery with USB-C
    charging. Also supports Classic Bluetooth SPP, but BLE is the
    preferred transport.

    PROTOCOL: uses 4 BLE UART services that are functionally identical.
    Primary service 0x18F0 with write characteristic 0x2AF1 and notify
    characteristic 0x2AF0. Info and config commands use the AiYin command
    format (10 FF prefix). Raster printing uses standard ESC/POS GS v 0
    (1D 76 30) header with 1-bit BMP data, MSB first, 12 bytes/row.

    DEVICE CLASS: this is AiYin class — enable/stop commands are
    10 FF FE 01 / 10 FF FE 45. The SDK also supports Lujiang-class devices
    that use 10 FF F1 03 / 10 FF F1 45. Using the wrong class = silent
    failure (printer accepts data but never prints).

    PRINT SEQUENCE: set_density → set_paper_type → wake_up (12 null bytes)
    → enable_printer → raster_header + pixel_data → form_feed → stop_print.
    Stop print waits for 0xAA or "OK" response (60s timeout).

    STATUS BITMASK (response to 10 FF 40): Bit0=printing, Bit1=cover open,
    Bit2=no paper, Bit3=low battery, Bit4=overheated(alt), Bit5=charging,
    Bit6=overheated. 0x00 = ready.

    SUPPORTED: Any of the 4 UART services works. The 0x18F0 service is
    recommended for cross-model compatibility.

    CONFIDENCE: HIGH for all info/config commands (verified against D11s
    hardware with firmware 2.4.6), the print sequence, raster format, and
    status bitmask. Sourced from 0xMH/fichero-printer — reverse-engineered
    from the Fichero APK v1.1.5 via jadx decompilation.

  identification:
    local_name_prefix: "FICHERO"
    service_uuids:
      - "000018f0-0000-1000-8000-00805f9b34fb"

  discovery:
    methods:
      - type: "ble_scan"
        ble:
          local_name:
            match: "prefix"
            value: "FICHERO"
          service_uuids:
            - "000018f0-0000-1000-8000-00805f9b34fb"
    identity:
      stable_keys: ["address"]
      display: "local_name"
    static_ip_required: false

  setup:
    required: false
    confidence: "high"
    notes: >
      No provisioning. Device advertises when powered on. No pairing or
      bonding required. The 0x18F0 service is the primary BLE UART service.
    methods:
      - type: "ble_direct"
        verified: true
        description: >
          Scan for "FICHERO" or "D11s_" BLE advertisement, connect, and
          follow the documented print sequence.
        ble:
          pairing_required: false
        steps:
          - action: "Power the printer and scan for its advertisement."
            actor: "client"
            request:
              protocol: "ble_gatt"
          - action: "Connect to service 0x18F0 (or any of the 4 UART services)."
            actor: "client"
          - action: "Subscribe to notifications on 0x2AF0."
            actor: "client"
    factory_reset:
      confidence: "high"
      effect: >
        Send factory reset command 10 FF 04. Returns "OK". Power-cycling
        also resets the connection.
      procedures:
        - name: "Command reset"
          steps:
            - action: "Send 10 FF 04 to write characteristic 0x2AF1."
              actor: "client"
              expect: "Device responds with OK."
        - name: "Power cycle"
          steps:
            - action: "Turn printer off and on."
              actor: "user"
              expect: "Printer powers on and advertises."
    rejoin:
      in_place_supported: true
      requires_factory_reset: false
      notes: "No persistent bonding. Any central can connect."
    credentials:
      wifi_passphrase_protection: "not_applicable"
      stored_on_device: []
      issued_to_client: []
      notes: "BLE-only. No auth."

  variants:
    - model: "D11s (Fichero)"
      identification:
        local_name_prefix: "FICHERO"
    - model: "D11s (generic)"
      identification:
        local_name_prefix: "D11s_"

  features:
    - type: "image_upload"
      max_width: 96
      max_height: 65535
      format: "1bit-bitmap"

  protocol_handler: "fichero_d11"

services:
  - uuid: "000018f0-0000-1000-8000-00805f9b34fb"
    name: "Fichero UART Service (Primary)"
    notes: >
      Primary BLE UART service. All commands are written to 0x2AF1;
      responses arrive as notifications on 0x2AF0. Use the AiYin-class
      enable/stop commands: 10 FF FE 01 / 10 FF FE 45.
    characteristics:
      - uuid: "00002af1-0000-1000-8000-00805f9b34fb"
        name: "Write"
        properties: ["write", "write_without_response"]
        notes: >
          Write channel for info/config commands and raster print data.
          Raster data is sent in 200-byte chunks with 20ms delay between
          chunks.

      - uuid: "00002af0-0000-1000-8000-00805f9b34fb"
        name: "Notify"
        properties: ["notify"]
        notes: >
          Notification channel for responses. Subscribe before sending
          commands. Responses are ASCII strings or binary status bytes.

  - uuid: "0000ff00-0000-1000-8000-00805f9b34fb"
    name: "Fichero UART Service (Alternate 1)"
    characteristics:
      - uuid: "0000ff02-0000-1000-8000-00805f9b34fb"
        name: "Write"
        properties: ["write"]
      - uuid: "0000ff01-0000-1000-8000-00805f9b34fb"
        name: "Notify"
        properties: ["notify"]

  - uuid: "e7810a71-73ae-499d-8c15-faa9aef0c3f2"
    name: "Fichero UART Service (Alternate 2)"
    characteristics:
      - uuid: "bef8d6c9-9c21-4c9e-b632-bd58c1009f9f"
        name: "Write/Notify"
        properties: ["write", "notify"]

  - uuid: "49535343-fe7d-4ae5-8fa9-9fafd205e455"
    name: "Fichero UART Service (Alternate 3)"
    characteristics:
      - uuid: "49535343-8841-43f4-a8d4-ecbe34729bb3"
        name: "Write"
        properties: ["write"]
      - uuid: "49535343-4c8a-39b3-2f49-511cff073b7e"
        name: "Notify"
        properties: ["notify"]

entities:
  - platform: "cover"
    name: "Print Feed"
    state_characteristic: "00002af0-0000-1000-8000-00805f9b34fb"
  - platform: "sensor"
    name: "Battery Level"
    state_characteristic: "00002af0-0000-1000-8000-00805f9b34fb"