RongtaBleSdk 0.2.1

<div align="center">

🖨️ RongtaBleSdk

Unofficial .NET MAUI SDK for printing labels over Bluetooth Low Energy on the Rongta RPP30

There is no official BLE UUID documentation for Rongta printers anywhere. This repo exists because someone needed to print a label on an RPP30 over BLE — and had to reverse-engineer it the hard way.

🇺🇸 English (you are here) · 🇧🇷 Ler em Português

Why · Confirmed UUIDs · Install · Usage · Discovery tool · Contributing

</div>

📖 Why this project exists

The Rongta RPP30 is a portable thermal label printer with "dual mode" Bluetooth (classic + BLE). If you want to print on it from:

• iOS → Apple doesn't allow classic Bluetooth (SPP) in third-party apps. BLE is the only option.
• An app already built on a BLE stack (Shiny.BluetoothLE, Plugin.BLE, CoreBluetooth, Web Bluetooth, ESP32...) → without depending on Rongta's native SDK.

...you hit a wall: Rongta does not publish the BLE service/characteristic UUIDs anywhere. Their official SDK (Android/iOS/Windows/Linux) only documents the classic Bluetooth flow (BluetoothEdrConfigBean, standard SPP UUID 00001101-...). The BLE classes (BleDriver, BleConfigBean) exist inside the .jar and use the open-source FastBLE library under the hood — but there is no documented example anywhere in the official manual.

So we connected to a real RPP30, enumerated its actual GATT table, and confirmed everything by printing a real label. This repo is the result.

✅ Confirmed for real (not a guess)

Unlike "probable" UUIDs copied from forum threads, the values below were validated on physical hardware:

1. Scanned via Windows.Devices.Bluetooth.Advertisement → device RPP30-C860 found.
2. Connected and enumerated every real service/characteristic over GATT (GetGattServicesAsync + GetCharacteristicsAsync).
3. Sent a test CPCL command, chunked into 20-byte blocks, through the write characteristic.
4. The printer printed the label. ✔️

🔌 Confirmed UUIDs (RPP30, "BLE-TX" firmware)

⚠️ These may vary by batch/firmware revision. Before blindly trusting these values on your unit, run the discovery tool included in this repo — it takes under a minute.

<details> <summary><strong>Other services exposed by the tested RPP30 (not used by this SDK, documented for completeness)</strong></summary>

0000ff80-0000-1000-8000-00805f9b34fb
  0000ff82  [WRITE, WRITE_NO_RESPONSE]
  0000ff81  [NOTIFY]

0000ff00-0000-1000-8000-00805f9b34fb
  0000ff02  [WRITE, WRITE_NO_RESPONSE]
  0000ff01  [NOTIFY]
  0000ff03  [NOTIFY]

0000ff10-0000-1000-8000-00805f9b34fb
  0000ff11  [WRITE_NO_RESPONSE, NOTIFY]
  0000ff12  [WRITE_NO_RESPONSE, NOTIFY]

Likely variations/duplicates of the same serial transport, exposed for compatibility with different apps. Not investigated further.

</details>

🆕 What's new in 0.2.0

Field-tested improvements ported from a production CPCL/BLE printing pipeline (a livestock-weighing MAUI app that prints thousands of labels a day):

• MTU negotiation — requests a 512-byte MTU on connect (Android), auto-sizing the write chunk instead of a fixed 20 bytes. Falls back safely when negotiation isn't supported (iOS/Windows negotiate on their own).
• Write retries — each chunk gets up to 3 attempts with backoff before the send fails, and a disconnect mid-print now throws a clear IOException instead of hanging.
• Multi-UUID discovery — RongtaBlePrinter now tries a list of known UUID pairs (the confirmed RPP30 one plus a few common UART-BLE variants seen on similar Chinese printer chips) and falls back to "first writable characteristic" if none match — more likely to work out of the box on a different batch or a different Rongta model.
• Auto label height — CpclLabelBuilder.CreateAutoHeightMm(width, ...) calculates the label height from the content you add (text/barcode/QR/image Y positions) instead of requiring you to know it up front.
• Image printing — AddImage(...) converts any PNG/JPG (via SkiaSharp) to the CPCL EG monochrome command, so you can print logos or graphics, not just text/barcodes/QR.
• Diacritics stripping — accented characters are automatically stripped before sending, since CPCL on these printers is effectively ASCII-only.

🧾 Print command language: CPCL

The RPP30 accepts both CPCL and ESC/POS (switchable from the physical menu: hold Power + Feed → Cmd Mode: CPCL/ESC). This SDK generates CPCL — confirmed by printing a real label over BLE. TSPL and ZPL have not been tested (see Known limitations).

📦 Installation

dotnet add package RongtaBleSdk

or in your .csproj:

<PackageReference Include="RongtaBleSdk" Version="0.2.1" />
<PackageReference Include="Shiny.BluetoothLE" Version="4.0.1" />
<PackageReference Include="SkiaSharp" Version="3.119.4" />

Shiny.BluetoothLE and SkiaSharp come in transitively, but pinning your own versions avoids surprises across MAUI upgrades.

Register in MauiProgram.cs:

var builder = MauiApp.CreateBuilder();

builder.Services.AddBluetoothLE();      // BLE transport (Shiny.BluetoothLE)
builder.Services.AddRongtaBlePrinter(); // RongtaBlePrinter as a singleton

🚀 Usage

public class LabelService(RongtaBlePrinter printer)
{
    public async Task PrintWeighingAsync(string identifier, double weightKg)
    {
        // Scans until it finds an "RPP30-XXXX" device and connects
        await printer.ScanAndConnectAsync();

        var label = CpclLabelBuilder
            .CreateMm(widthMm: 120, heightMm: 80)
            .AddText(30, 30, "CELMI", font: 5)
            .AddText(30, 80, $"ID: {identifier}")
            .AddText(30, 120, $"Weight: {weightKg:F2} kg")
            .AddQrCode(30, 160, identifier);

        await printer.PrintAsync(label);
        await printer.DisconnectAsync();
    }
}

Connecting to a peripheral already scanned by your own UI

// if you already have your own scan/pairing screen (e.g. reusing IBleManager directly)
await printer.ConnectAsync(chosenPeripheral);
await printer.PrintAsync(label);

Sending raw bytes (e.g. a different command dialect)

byte[] rawCommand = Encoding.ASCII.GetBytes("! 0 200 200 210 1\r\nTEXT 4 0 30 30 HELLO\r\nFORM\r\nPRINT\r\n");
await printer.SendAsync(rawCommand);

🧩 CpclLabelBuilder API

RongtaBlePrinter also exposes DetectedWriteEndpoint after connecting, so you can log/inspect which service/characteristic pair actually worked on your unit.

🔍 Discovery tool

A Windows console app (Windows.Devices.Bluetooth) that scans BLE, connects to the printer and lists every real service/characteristic with its properties (WRITE / WRITE_NO_RESPONSE / NOTIFY / READ) — the exact process used to confirm the UUIDs in this README. Run it if:

• Your RPP30 is a different batch/firmware and the UUIDs above didn't match;
• You want to adapt this SDK to another Rongta model.

cd tools/RongtaBleDiscovery
dotnet run -c Release

It scans for 15s, connects to the first device whose name contains RPP/RONGTA/Printer (or lets you type the address manually) and prints the full GATT tree to the console — optionally also sending a CPCL test label to validate the write characteristic it found.

🗺️ Architecture

┌─────────────────────────┐
│   Your MAUI App            │
│   (Android / iOS / Mac)   │
└────────────┬───────────┘
             │ DI: RongtaBlePrinter
             ▼
┌─────────────────────────┐
│   RongtaBleSdk             │
│  ┌───────────────────┐  │
│  │ CpclLabelBuilder    │  │   text, barcode, QR → CPCL bytes
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ RongtaBlePrinter    │  │   scan, connect, chunk & write
│  └─────────┬─────────┘  │
└────────────┼───────────┘
             │ IBleManager / IPeripheral
             ▼
┌─────────────────────────┐
│   Shiny.BluetoothLE        │   abstracts Android/iOS/Windows
└────────────┬───────────┘
             │ GATT write (service 49535343-fe7d-...)
             ▼
┌─────────────────────────┐
│   Rongta RPP30 (BLE)       │
└─────────────────────────┘

⚠️ Known limitations / next steps

• ✅ Tested printing in CPCL. ❌ TSPL/ESC/ZPL not tested in this project (the RPP30 supports all four, switchable from the physical menu).
• Tested on a single physical unit only ("BLE-TX" firmware, name RPP30-C860). Contributions confirming/correcting UUIDs on other batches are welcome.
• iOS: the API is abstracted by Shiny.BluetoothLE and the package builds and ships for net10.0-ios/net10.0-maccatalyst, but the BLE flow itself hasn't been validated on a real iPhone/Mac yet.
• Diacritics are stripped and CPCL is sent as ASCII — good enough for Latin-script labels, but the printer's own codepage settings (CP850/CP1252/etc) aren't configurable from the SDK yet.

📦 Releasing

Publishing to NuGet.org uses Trusted Publishing — no API key is stored anywhere. .github/workflows/publish.yml requests a short-lived OIDC token from GitHub Actions, exchanges it for a temporary NuGet API key, and pushes the package. It runs on workflow_dispatch or on pushing a v* tag.

🤝 Contributing

Tested on another Rongta model or a different RPP30 batch? Please open an issue with:

1. The full output of the discovery tool run against your unit;
2. The exact device name advertised (RPP30-XXXX);
3. Whether the UUIDs in this README matched or not.

PRs for TSPL/ESC/ZPL support, MTU negotiation, or iOS testing are very welcome.

📄 License

MIT — see LICENSE.

<div align="center">

Built by reverse-engineering what Rongta never documented, for anyone else who also needs to print on an RPP30 over BLE.

</div>