LLRPCSharpProgrammer’s Guide GitHub ↗

LLRPCSHARP / PROGRAMMER’S GUIDE

Reader SDK Programmer’s Guide

LlrpSdk 是面向 .NET 应用的托管 LLRP 客户端。它把 TCP 会话、协议版本协商、设备能力、Reader 设置、托管盘点和标准 C1G2 标签访问收敛到 LlrpReader 门面；应用通常不需要手写 ROSpec 或 AccessSpec 消息。

1. 安装与边界

将 Reader SDK 添加到应用：

dotnet add package LlrpSdk --version 2.0.5

Impinj 与 Zebra 扩展是独立包，只有在目标设备和版本匹配时才会激活：

dotnet add package LlrpSdk.Extensions.Impinj --version 2.0.5
dotnet add package LlrpSdk.Extensions.Zebra --version 2.0.5
本指南讲应用层 Reader SDK。需要直接处理 LLRP 帧、Codec、会话传输或生成协议类型时，请转到 LlrpNet Protocol API；公开类型、方法签名和参数契约见 Reader SDK API Reference。

2. 连接读写器

LlrpReaderBuilder 用于设置地址、端口和连接超时。默认协议策略为自动协商：

using LlrpSdk;

await using var reader = LlrpReader.CreateBuilder("192.168.1.100")
    .WithPort(5084)
    .WithConnectTimeout(TimeSpan.FromSeconds(5))
    .Build();

await reader.ConnectAsync();
Console.WriteLine(reader.Identity);
策略行为适用场景
Auto先建立连接，再尝试 1.1 协商；不支持时回到 1.0.1。默认选择
Force101跳过版本探查，直接使用 LLRP 1.0.1。已知旧设备
Force11必须完成 1.1 协商，失败不会静默降级。明确要求 1.1
Force20使用当前 2.0 SDK 适配器基线；真实设备互操作仍需单独验收。2.0 实验或目标设备

连接成功后，Capabilities、Identity 和扩展激活状态才具有设备上下文。

3. 读取设备能力

LLRP 的 RF Mode、发射功率和接收灵敏度通常以 Index 表示。不要猜测数字含义，应从当前 Reader 的能力表读取：

ReaderCapabilities capabilities = reader.Capabilities!;

Console.WriteLine(capabilities.MaxNumberOfAntennas);
foreach (var mode in capabilities.RfModes)
    Console.WriteLine(mode.Description);
foreach (var power in capabilities.TransmitPowerTable)
    Console.WriteLine(power.TransmitPowerDbm / 100.0);

GetDefaultSettingsAsync() 会基于当前设备身份、协商版本和能力表生成推荐基线；它不是设备当前配置快照。需要读取设备事实时使用 QuerySettingsAsync()。

4. 配置读写器

ReaderSettings 表示应用想要的配置。常见流程是“读取能力相关默认值 → 编辑 → 应用”，应用后 Inventory 仍保持停止，直到显式启动：

ReaderSettings baseSettings = (await reader.GetDefaultSettingsAsync()).Settings;

ReaderSettings settings = baseSettings.Edit(builder => builder
    .Inventory(inventory => inventory
        .Antennas(1, 2, 3, 4)
        .Mode(modeIndex: 1000)
        .Session(2)
        .Population(128)
        .ReportEveryTag()));

await reader.ApplySettingsAsync(settings);
DEFAULT

PreserveForeign

默认只替换 SDK 自己托管的 ROSpec、AccessSpec 和临时资源，保留其他应用资源。

EXPLICIT

ReplaceAll

明确要求独占设备时才使用；它会删除全部标准 ROSpec/AccessSpec，适合专用测试设备。

配置文件、默认值和设备快照分别代表不同来源。SDK 不会把 Raw/专家接口的修改自动当成新的应用意图。

5. 托管盘点与报告

应用配置完成后，使用独立的 InventorySession 读取报告：

await using var session = await reader.StartInventoryAsync();
await foreach (TagReport tag in session.ReadReportsAsync())
{
    Console.WriteLine(tag.EpcHex);
}

InventorySession.ReadReportsAsync()、TagsReported 和连接级 ReadTagReportsAsync() 是互斥的报告出口。一次盘点中，第一个开始消费的出口取得所有权，避免同一份报告被多个消费者重复处理。

恢复边界：设备上的 ROSpec/AccessSpec 通常是易失资源。重连会同步设备现状，但不会替应用猜测并重放所有期望配置；应用应保留自己的 ReaderSettings 或 InventorySettings，必要时重新部署。

6. 标签访问

标准 C1G2 Tag Access 由 SDK 管理 AccessSpec 生命周期。下面是按 EPC 选择标签并读取 User 区的最小示例：

var selection = new TagSelection
{
    MemoryBank = TagMemoryBank.ElectronicProductCode,
    BitPointer = 32,
    BitLength = 96,
    Mask = Convert.FromHexString("FFFFFFFFFFFFFFFFFFFFFFFF"),
    Data = Convert.FromHexString("E28011910000000000000001")
};

TagAccessResult result = await reader.ReadTagMemoryAsync(new ReadTagRequest
{
    Selection = selection,
    MemoryBank = TagMemoryBank.User,
    WordPointer = 0,
    WordCount = 2
});

Console.WriteLine(result.Operation.Success);

写入、锁定、销毁和块擦除也有对应的高层请求。Kill、Lock 以及带写入的操作可能不可逆，请在专用标签和明确的应用确认流程中执行。

7. 厂商扩展

扩展注册只是声明候选能力；连接后 SDK 会根据 Reader 身份和协商版本决定是否激活。应用在使用扩展设置前应检查实际激活状态：

using LlrpSdk.Extensions.Impinj;

await using var reader = LlrpReader.CreateBuilder("192.168.1.100")
    .UseImpinj()
    .Build();

await reader.ConnectAsync();
if (reader.Extensions.Get<ImpinjReaderExtension>() is null)
    throw new NotSupportedException("Impinj extension is not active on this reader.");

当前仓库提供 Impinj 与 Zebra 的协议/SDK 扩展基线；不同型号、固件和字段仍以实机互操作证据为准。

8. 生命周期与边界

01连接后读取 Capabilities，用设备事实生成或校验设置。
02应用设置只负责部署；需要开始射频盘点时显式调用 StartInventoryAsync()。
03断开、Dispose 或使用 await using 结束 Reader 生命周期。
04LLRP 2.0、Zebra 及其他厂商扩展的“可编译”不等同于所有真实型号已验收。

下一步：Reader SDK API Reference 提供公开类型和方法索引；需要命令行操作时转到 Reader CLI User’s Guide。