TiJet gRPC SDK 参考手册

版本 1.0.0 | 基于 proto 契约 tincore.TinCore 服务

API 对照表

#	功能	C	Python	Java	C#
1	创建	`ti_create()`	`TinCore()`	`new TinCore()`	`new TinCore()`
2	销毁	`ti_destroy()`	`close()` / `with`	`close()` / try-with	`Dispose()` / `using`
3	连接	`ti_connect(a)`	`connect(a)`	`connect(a)`	`Connect(a)`
4	断开	`ti_disconnect()`	`disconnect()`	`disconnect()`	`Disconnect()`
5	连接状态	`ti_is_connected()`	`is_connected`	`isConnected()`	`IsConnected`
6	网络配置	`ti_network_config()`	`network_config()`	`networkConfig()`	`NetworkConfig()`
7	设置参数	`ti_set_parameter()`	`set_parameter()`	`setParameter()`	`SetParameter()`
8	获取参数	`ti_get_parameter()`	`get_parameter()`	`getParameter()`	`GetParameter()`
9	发送打印数据	`ti_set_print_data()`	`set_print_data()`	`setPrintData()`	`SetPrintData()`
10	注册事件回调	`ti_set_event_callback()`	`set_event_callback()`	`setEventCallback()`	`SetEventCallback()`
11	启动事件订阅	`ti_start_event_subscription()`	`start_event_subscription()`	`startEventSubscription()`	`StartEventSubscription()`
12	停止事件订阅	`ti_stop_event_subscription()`	`stop_event_subscription()`	`stopEventSubscription()`	`StopEventSubscription()`
13	注册日志回调	`ti_set_log_callback()`	`set_log_callback()`	`setLogCallback()`	`SetLogCallback()`
14	启动日志订阅	`ti_start_log_subscription()`	`start_log_subscription()`	`startLogSubscription()`	`StartLogSubscription()`
15	停止日志订阅	`ti_stop_log_subscription()`	`stop_log_subscription()`	`stopLogSubscription()`	`StopLogSubscription()`
16	错误信息	`ti_last_error()`	`last_error`	`getLastError()`	`LastError`
17	SDK 版本	`ti_version()`	`version()`	`version()`	`Version`

驱动板参数无独立接口：通过 board.N.key 命名约定 + 通用参数读写接口实现（如 ti_set_parameter(cli, "board.0.print_speed", "80")）。

语言惯用差异（不影响语义）

特性	C	Python	Java	C#
错误处理	`int` 返回码	异常 `TiJetError`	异常 `TiJetError`	异常 `TiJetError`
空参数	`NULL` / `""`	`None` / `""`	`null` / `""`	`null` / `""`
二进制数据	`const uint8_t*` + `size_t`	`bytes`	`byte[]`	`byte[]`
回调类型	函数指针 + `void*`	`Callable[[str], None]`	`Consumer<String>`	`Action<string>`
命名风格	`snake_case`	`snake_case`	`camelCase`	`PascalCase`

C SDK

快速开始

#include "tijet_core.h"

int main(void) {
    ti_client_t *cli = ti_create();

    if (ti_connect(cli, NULL) != TI_OK) {
        fprintf(stderr, "连接失败: %s\n", ti_last_error(cli));
        ti_destroy(cli);
        return 1;
    }

    // 设置参数
    ti_set_parameter(cli, "print_speed", "100");

    // 获取参数 — 预分配缓冲区，一次调用
    char buf[TI_MAX_PARAM_VALUE];
    ti_get_parameter(cli, "print_speed", buf, sizeof(buf));
    printf("print_speed = %s\n", buf);

    // 发送打印数据
    uint8_t data[] = { 0x1B, 0x40 };
    ti_set_print_data(cli, data, sizeof(data), 0, 0);

    ti_disconnect(cli);
    ti_destroy(cli);
    return 0;
}

构建

cmake .. -DBUILD_C_SDK=ON
make tijet_c
# 产物: build/sdk/c/libtijet_c.so.1.0.0

头文件

#include "tijet_core.h" — 19 个 C 函数，零语言依赖（仅需 stddef.h + stdint.h）。

Doxygen 文档：doxygen Doxyfile → 含 @mainpage、@defgroup 分组、@code 示例。

Python SDK

安装

pip install grpcio protobuf
# 从源码:
#   PYTHONPATH=sdk/python python3 -c "from tijet_grpc import TinCore"

快速开始

from tijet_grpc import TinCore

with TinCore() as client:
    client.connect()
    client.set_parameter("print_speed", "100")
    speed = client.get_parameter("print_speed")
    print(f"print_speed = {speed}")

    checksum = client.set_print_data(b"\x1B\x40", index=0)
    print(f"SHA-256: {checksum}")

事件订阅

def on_event(event_json: str):
    print(f"事件: {event_json}")

client.set_event_callback(on_event)
client.start_event_subscription()
# 事件在后台线程异步回调...
client.stop_event_subscription()

异常层次

$$TiJetError (基类, code 属性) ├── InvalidArgumentError (code = -1) ├── NotConnectedError (code = -2) ├── TimeoutError (code = -3) ├── ServerError (code = -5) └── InternalError (code = -6)$$

类型别名

EventCallback = Callable[[str], None]
LogCallback   = Callable[[str], None]

Java SDK

依赖

// build.gradle
dependencies {
    implementation 'io.grpc:grpc-netty-shaded:1.82.0'
    implementation 'io.grpc:grpc-protobuf:1.82.0'
    implementation 'com.google.protobuf:protobuf-java:4.35.1'
    implementation 'com.google.protobuf:protobuf-java-util:4.35.1'
}

快速开始

import com.tijet.grpc.TinCore;

try (TinCore client = new TinCore()) {
    client.connect(null);  // 默认 UDS

    client.setParameter("print_speed", "100");
    String speed = client.getParameter("print_speed");
    System.out.println("print_speed = " + speed);

    byte[] data = { 0x1B, 0x40 };
    String checksum = client.setPrintData(data, 0, false);
    System.out.println("SHA-256: " + checksum);
}

事件订阅

client.setEventCallback(json -> {
    System.out.println("事件: " + json);
});
client.startEventSubscription();
// 事件在后台 daemon 线程异步回调...
client.stopEventSubscription();

异常层次

$$TiJetError (RuntimeException, int code) ├── InvalidArgumentError ├── NotConnectedError ├── TimeoutError ├── ServerError └── InternalError$$

构建

./gradlew build          # 需要 Gradle Wrapper
# 或直接生成 proto:
scripts/gen_proto.sh java

C# SDK

依赖

<!-- TiJet.Grpc.csproj -->
<PackageReference Include="Google.Protobuf" Version="3.28.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.66.0" />
<PackageReference Include="Grpc.Tools" Version="2.66.0" />

快速开始

using TiJet.Grpc;

using var client = new TinCore();
client.Connect(null);  // 默认 UDS

client.SetParameter("print_speed", "100");
string speed = client.GetParameter("print_speed");
Console.WriteLine($"print_speed = {speed}");

byte[] data = { 0x1B, 0x40 };
string checksum = client.SetPrintData(data, index: 0);
Console.WriteLine($"SHA-256: {checksum}");

事件订阅

client.SetEventCallback(json => Console.WriteLine($"事件: {json}"));
client.StartEventSubscription();
// 事件在后台 Task 异步回调...
client.StopEventSubscription();

异常层次

$$TiJetError (Exception, int Code) ├── InvalidArgumentError ├── NotConnectedError ├── TimeoutError ├── ServerError └── InternalError$$

构建

dotnet build                                        # 需要 .NET 8 SDK
# 或先独立生成 proto:
scripts/gen_proto.sh csharp    # 需要 grpc_csharp_plugin

C++ 轻封装

使用

// header-only RAII 封装（sdk/cpp/include/tijet_core.h 提供），
// 所有实现委托给 C API，无额外 ABI 维护负担
#include "tijet_core.h"

tijet::TinCore cli;
if (!cli.connectToServer()) {   // 默认 unix:/var/run/tincore.sock
    return 1;
}
cli.setParameter("print_speed", "100");
auto speed = cli.getParameter("print_speed");   // std::optional<std::string>

或直接调用 C API：

#include "tijet_core.h"  // C ABI 头文件

auto *cli = ti_create();
ti_connect(cli, nullptr);
ti_set_parameter(cli, "key", "value");
ti_destroy(cli);

Qt 集成示例

// Qt 调用 C API — 仅需 QString ↔ const char* 转换
bool MyWidget::connectToDevice() {
    handle_ = ti_create();
    QByteArray addr = ui->addressEdit->text().toUtf8();
    return ti_connect(handle_, addr.constData()) == TI_OK;
}

错误码

所有语言共享同一套错误码语义（C 返回 int，其他语言映射为异常）：

宏	值	含义
`TI_OK`	0	成功
`TI_ERR_INVALID_ARG`	-1	参数无效（NULL、越界、非法格式）
`TI_ERR_NOT_CONNECTED`	-2	尚未连接到服务器
`TI_ERR_TIMEOUT`	-3	操作超时
`TI_ERR_BUFFER_TOO_SMALL`	-4	缓冲区不足（仅 C API 使用）
`TI_ERR_SERVER`	-5	服务端返回错误
`TI_ERR_INTERNAL`	-6	内部错误（内存不足、线程错误）

构建与生成

代码生成

# 生成所有语言的 proto/gRPC 代码
./scripts/gen_proto.sh all

# 生成单个语言
./scripts/gen_proto.sh cpp
./scripts/gen_proto.sh python
./scripts/gen_proto.sh java
./scripts/gen_proto.sh csharp    # 需要 grpc_csharp_plugin

# 支持的平台:
#   cpp, csharp, python, go, java, rust, nodejs

C SDK 构建

cmake .. -DBUILD_C_SDK=ON
make tijet_c
# 产物: build/sdk/c/libtijet_c.so.1.0.0
# 导出: 19 个 ti_* 符号，零 C++ 符号泄露

Java 构建

cd sdk/java
./gradlew build

C# 构建

cd sdk/csharp/TiJet.Grpc
dotnet build

当前状态

SDK	实现	测试	文档
C	✅ 完整 gRPC 对接	—	Doxygen (tijet_core.h)
Python	✅ 完整 gRPC 对接	—	docstring + 本文档
Java	✅ 完整源码	—	Javadoc + 本文档
C#	✅ 完整源码	—	XML doc + 本文档
C++ wrapper	✅ header-only 示范	—	—

待完成

WatchLogs RPC：proto 尚无 rpc WatchLogs 定义，所有 SDK 的日志订阅为存根
TLS 支持：当前使用明文连接（InsecureChannelCredentials）
单元测试：需要 mock gRPC 服务端或真实设备

TiJet gRPC SDK 参考手册

目录

API 对照表

语言惯用差异（不影响语义）

C SDK

快速开始

构建

头文件

Python SDK

安装

快速开始

事件订阅

异常层次

类型别名

Java SDK

依赖

快速开始

事件订阅

异常层次

构建

C# SDK

依赖

快速开始

事件订阅

异常层次

构建

C++ 轻封装

使用

Qt 集成示例

错误码

构建与生成

代码生成

C SDK 构建

Java 构建

C# 构建

当前状态

待完成