1、Overview

DockLib (com.urovo.docklib) is an Android library for UROVO SP35 cradle control over the device UART. Integrators use a single public facade, IDockTool, obtained via DockTool.getInstance().

1.1、Version history

1.0.3 — 2026-08-25

Relative to 1.0.2.

1.0.2 — 2026-08-19

Relative to 1.0.1.

1.0.1 — 2026-08-17

Relative to 1.0.0. Added unlock/LED/charge/identity reads, LED test parameters, rebootCradle, and layout id range 0..32.

1.0.0 — 2026-08-07

First public IDockTool: link lifecycle, unlock, layout ids, LED enable, LED test run, firmware / hardware strings.

1.2、Key features

• Framed serial commands for cradle unlock, layout IDs, LED control, charging mode, identity reads, reboot
• Async unlock with main-thread callbacks
• MCU firmware upgrade (IAP + YMODEM) via upgradeFirmware
• Link lifecycle with optional auto-reconnect and DockLinkListener
• Consumer ProGuard rules shipped in the AAR

1.3、Use cases

• Control SP35 cradles from an Android host app over UART
• Unlock cradles and manage LED test patterns
• Read cradle identity and upgrade MCU firmware in the field

1.4、Requirements

Do not instantiate DockTool directly. Do not call SerialPortLibrary or raw UART from your app for cradle IAP; use upgradeFirmware only.

2、Integration

2.1、Obtain the SDK

Add the release AAR (or the :DockLib module) to your app. minSdk 24.

2.2、Project setup

Release builds that depend on DockLib (module or fat AAR) automatically merge consumer ProGuard rules from the AAR. Integrators do not need to copy these rules into the app.

Reference (shipped in consumer-rules.pro / AAR proguard.txt):

-keep class com.urovo.docklib.** { *; }
-keep interface com.urovo.docklib.** { *; }
-keep enum com.urovo.docklib.** { *; }

-keep class com.urovo.serial.** { *; }
-keep class com.urovo.hwserial.** { *; }
-keep class com.android.hw.SerialPort { *; }
-keepclasseswithmembernames class com.android.hw.SerialPort {
    native <methods>;
}

2.3、Lifecycle

Call open() when your UI or service needs the cradle (e.g. Activity.onStart()). Call close() when done (e.g. onStop()).

Most API calls require LinkState.ONLINE. If the port is still OPENING or LOST, synchronous methods throw DockException with PORT_NOT_OPEN. Use DockLinkListener or poll getLinkState() before business calls.

2.4、Threading

Do not call blocking SDK methods on the main thread if the UI must stay responsive—use a background Executor.

Serialize access: Only one in-flight serial transaction at a time. While upgradeFirmware runs, do not call other IDockTool methods in parallel.

2.5、Logging

import com.urovo.docklib.MLog;

MLog.setLogEnabled(true);
MLog.setMinLevel(Log.DEBUG);
dock.setSerialTraceEnabled(true); // hex TX/RX, debug builds only

Filter logcat: tag DockLib, messages prefixed with >>.

2.6、Authentication

None.

3、Quick Start

import com.urovo.docklib.DockTool;
import com.urovo.docklib.DockException;
import com.urovo.docklib.IDockTool;

IDockTool dock = DockTool.getInstance();
String sdkVer = DockTool.getLibraryVersion();

@Override protected void onStart() {
    super.onStart();
    dock.open();
}

@Override protected void onStop() {
    dock.close();
    super.onStop();
}

// On a background thread when link is ONLINE:
try {
    int wall = dock.getWallId();
    String fw = dock.getFirmwareVersion();
} catch (DockException e) {
    // e.getError() → DockError
}

API Reference

static IDockTool getInstance()

static String getLibraryVersion()

void open() throws DockException

void close()

boolean isOpen()

LinkState getLinkState()

void setAutoReconnect(boolean enable)

void addLinkListener(DockLinkListener listener)

void removeLinkListener(DockLinkListener listener)

void setSerialTraceEnabled(boolean enable)

void setUnlockTimeSeconds(int seconds) throws DockException

int getUnlockTimeSeconds() throws DockException

void unlockCradle(UnlockCallback callback)

void setLedEnabled(boolean enable) throws DockException

boolean getLedEnabled() throws DockException

void rebootCradle() throws DockException

void setLedTestOnTimeMs(int ms) throws DockException

void setLedTestOffTimeMs(int ms) throws DockException

void setLedTestCount(int count) throws DockException

void setLedTestAlternate(boolean enable) throws DockException

void runLedTest() throws DockException

void turnOffLedTest() throws DockException

void setWallId(int id) throws DockException

int getWallId() throws DockException

void setRowId(int id) throws DockException

int getRowId() throws DockException

void setColId(int id) throws DockException

int getColId() throws DockException

void setHostCharge(boolean fast) throws DockException

boolean getHostCharge() throws DockException

String getSerialNumber() throws DockException

String getCradleModel() throws DockException

int getLastErrorCode() throws DockException

String getFirmwareVersion() throws DockException

String getHardwareRevision() throws DockException

void onAck()
void onSuccess()
void onFailure(DockError error)

void onProgress(FirmwareUpgradeStage stage, int current, int total)

void onLinkStateChanged(LinkState state)

static void setLogEnabled(boolean on)

static void setMinLevel(int level)

static void d(String msg)

static void i(String msg)

static void w(String msg)

static void e(String msg)
static void e(String msg, Throwable t)

static String toHex(byte[] data)

5、Examples

5.1、Unlock

dock.setUnlockTimeSeconds(10);
dock.setLedEnabled(true);
dock.unlockCradle(new UnlockCallback() {
    @Override public void onAck() { }
    @Override public void onSuccess() { }
    @Override public void onFailure(DockError error) { }
});

5.2、Read versions

String model = dock.getCradleModel();
String hw = dock.getHardwareRevision();
String fw = dock.getFirmwareVersion();
String serial = dock.getSerialNumber();
int err = dock.getLastErrorCode();

5.3、Firmware upgrade

byte[] bin = ...; // load .bin from storage, 1..53248 bytes
FirmwareUpgradeListener progress = (stage, current, total) -> {
    // update UI on main thread
};
try {
    String newFw = dock.upgradeFirmware(bin, progress);
    // show newFw in UI — SDK already read version from device
} catch (DockException e) {
    switch (e.getError()) {
        case OTA_BOOT_TIMEOUT:
        case OTA_SETUP_FAILED:
        case OTA_ERASE_FAILED:
        case OTA_TRANSFER_FAILED:
        case OTA_VERSION_READ:
        case INVALID_ARGUMENT:
            break;
        default:
            break;
    }
}

Pick a .bin with the system file picker in your app; pass bytes to upgradeFirmware only. YMODEM file name inside the protocol is fixed as firmware.bin.

6、Notes & FAQ

6.1、Notes

Serial exclusivity — The SDK uses one worker thread and one UART. Gate UI so only one operation runs at a time. During OTA, other IDockTool calls will block or fail if invoked from another thread without your own gate.

OTA vs framed protocol — OTA temporarily leaves framed mode. Do not interleave framed commands while raw IAP is active; the SDK handles enter/exit internally.

.bin size — Valid range 1..0xD000 bytes. Validate in the app before calling the SDK.

No cancel during flash — Once upgradeFirmware starts, there is no supported cancel path; wait for success or DockException.

Do not use SerialPortLibrary for IAP — Integrators must use IDockTool.upgradeFirmware only.

Empty read strings — getFirmwareVersion, getHardwareRevision, getCradleModel, and getSerialNumber may return "" if the cradle sends no text within the SDK wait window.

1、概述

DockLib（com.urovo.docklib）是面向 UROVO SP35 座充的 Android 库，通过设备 UART 进行控制。集成方通过 DockTool.getInstance() 获取唯一公开门面 IDockTool。

1.1、版本变更

1.0.3 — 2026-08-25

相对 1.0.2。

1.0.2 — 2026-08-19

相对 1.0.1。

1.0.1 — 2026-08-17

相对 1.0.0。新增解锁/LED/充电/身份读取、LED 测试参数、rebootCradle，以及布局 ID 范围 0..32。

1.0.0 — 2026-08-07

首个公开 IDockTool：链路生命周期、解锁、布局 ID、LED 使能、LED 测试启动、固件/硬件字符串。

1.2、核心能力

• 帧协议串口命令：座充解锁、布局 ID、LED、充电模式、身份读取、重启
• 异步解锁（主线程回调）
• MCU 固件升级（IAP + YMODEM）：upgradeFirmware
• 链路生命周期、可选自动重连与 DockLinkListener
• AAR 自带 consumer ProGuard 规则

1.3、典型场景

• Android 主机通过 UART 控制 SP35 座充
• 解锁座充并管理 LED 测试闪烁
• 读取座充身份并在现场升级 MCU 固件

1.4、依赖与环境

请勿直接构造 DockTool。请勿在应用中直接调用 SerialPortLibrary 或原始 UART 做座充 IAP；仅使用 upgradeFirmware。

2、接入

2.1、获取 SDK

将 release AAR（或 :DockLib 模块）加入应用。minSdk 24。

2.2、工程配置

依赖 DockLib（模块或 fat AAR）的 Release 构建会自动合并 AAR 中的 consumer ProGuard 规则，集成方无需再抄规则。

参考（已写入 consumer-rules.pro / AAR proguard.txt）：

-keep class com.urovo.docklib.** { *; }
-keep interface com.urovo.docklib.** { *; }
-keep enum com.urovo.docklib.** { *; }

-keep class com.urovo.serial.** { *; }
-keep class com.urovo.hwserial.** { *; }
-keep class com.android.hw.SerialPort { *; }
-keepclasseswithmembernames class com.android.hw.SerialPort {
    native <methods>;
}

2.3、生命周期

在需要座充时调用 open()（例如 Activity.onStart()），结束时调用 close()（例如 onStop()）。

多数 API 要求 LinkState.ONLINE。若仍为 OPENING 或 LOST，同步方法抛出 DockException，错误码 PORT_NOT_OPEN。业务调用前请使用 DockLinkListener 或轮询 getLinkState()。

2.4、线程模型

若 UI 需保持响应，不要在主线程调用阻塞 SDK 方法——使用后台 Executor。

串行访问： 同一时刻仅允许一笔串口事务。执行 upgradeFirmware 时不要并行调用其他 IDockTool 方法。

2.5、日志

import com.urovo.docklib.MLog;

MLog.setLogEnabled(true);
MLog.setMinLevel(Log.DEBUG);
dock.setSerialTraceEnabled(true); // hex TX/RX，建议仅调试构建

logcat 过滤：tag DockLib，消息前缀 >>。

2.6、鉴权

无

3、快速开始

import com.urovo.docklib.DockTool;
import com.urovo.docklib.DockException;
import com.urovo.docklib.IDockTool;

IDockTool dock = DockTool.getInstance();
String sdkVer = DockTool.getLibraryVersion();

@Override protected void onStart() {
    super.onStart();
    dock.open();
}

@Override protected void onStop() {
    dock.close();
    super.onStop();
}

// 链路 ONLINE 时在后台线程：
try {
    int wall = dock.getWallId();
    String fw = dock.getFirmwareVersion();
} catch (DockException e) {
    // e.getError() → DockError
}

API 参考

static IDockTool getInstance()

static String getLibraryVersion()

void open() throws DockException

void close()

boolean isOpen()

LinkState getLinkState()

void setAutoReconnect(boolean enable)

void addLinkListener(DockLinkListener listener)

void removeLinkListener(DockLinkListener listener)

void setSerialTraceEnabled(boolean enable)

void setUnlockTimeSeconds(int seconds) throws DockException

int getUnlockTimeSeconds() throws DockException

void unlockCradle(UnlockCallback callback)

void setLedEnabled(boolean enable) throws DockException

boolean getLedEnabled() throws DockException

void rebootCradle() throws DockException

void setLedTestOnTimeMs(int ms) throws DockException

void setLedTestOffTimeMs(int ms) throws DockException

void setLedTestCount(int count) throws DockException

void setLedTestAlternate(boolean enable) throws DockException

void runLedTest() throws DockException

void turnOffLedTest() throws DockException

void setWallId(int id) throws DockException

int getWallId() throws DockException

void setRowId(int id) throws DockException

int getRowId() throws DockException

void setColId(int id) throws DockException

int getColId() throws DockException

void setHostCharge(boolean fast) throws DockException

boolean getHostCharge() throws DockException

String getSerialNumber() throws DockException

String getCradleModel() throws DockException

int getLastErrorCode() throws DockException

String getFirmwareVersion() throws DockException

String getHardwareRevision() throws DockException

void onAck()
void onSuccess()
void onFailure(DockError error)

void onProgress(FirmwareUpgradeStage stage, int current, int total)

void onLinkStateChanged(LinkState state)

static void setLogEnabled(boolean on)

static void setMinLevel(int level)

static void d(String msg)

static void i(String msg)

static void w(String msg)

static void e(String msg)
static void e(String msg, Throwable t)

static String toHex(byte[] data)

5、示例

5.1、Unlock

dock.setUnlockTimeSeconds(10);
dock.setLedEnabled(true);
dock.unlockCradle(new UnlockCallback() {
    @Override public void onAck() { }
    @Override public void onSuccess() { }
    @Override public void onFailure(DockError error) { }
});

5.2、Read versions

String model = dock.getCradleModel();
String hw = dock.getHardwareRevision();
String fw = dock.getFirmwareVersion();
String serial = dock.getSerialNumber();
int err = dock.getLastErrorCode();

5.3、Firmware upgrade

byte[] bin = ...; // 从存储加载 .bin，1..53248 字节
FirmwareUpgradeListener progress = (stage, current, total) -> {
    // 在主线程更新 UI
};
try {
    String newFw = dock.upgradeFirmware(bin, progress);
    // UI 展示 newFw — SDK 已从设备读取版本
} catch (DockException e) {
    switch (e.getError()) {
        case OTA_BOOT_TIMEOUT:
        case OTA_SETUP_FAILED:
        case OTA_ERASE_FAILED:
        case OTA_TRANSFER_FAILED:
        case OTA_VERSION_READ:
        case INVALID_ARGUMENT:
            break;
        default:
            break;
    }
}

请在应用中用系统文件选择器选取 .bin，仅将字节传给 upgradeFirmware。协议内 YMODEM 文件名固定为 firmware.bin。

6、注意事项与 FAQ

6.1、Notes

串口独占 — SDK 使用单工作线程与单一 UART。请在 UI 侧门控，保证同一时刻仅一笔操作。OTA 期间若另一线程无门控地调用其他 IDockTool 方法，可能阻塞或失败。

OTA 与帧协议 — OTA 期间会暂时离开帧模式。原始 IAP 进行时不要穿插帧命令；进入/退出由 SDK 内部处理。

.bin 大小 — 有效范围 1..0xD000 字节。调用 SDK 前请在应用侧校验。

烧录不可取消 — upgradeFirmware 启动后无支持的取消路径；等待成功或 DockException。

勿用 SerialPortLibrary 做 IAP — 集成方必须仅使用 IDockTool.upgradeFirmware。

空读字符串 — 若座充在 SDK 等待窗口内未返回文本，getFirmwareVersion、getHardwareRevision、getCradleModel、getSerialNumber 可能返回 ""。