本页面是 MikroTik TG-LR82 和 TG-LR92 LoRaWAN 传感器标签的设置指南，涵盖激活、入网、遥测和传感器配置、磁铁开关命令、下行链路命令编码、数据帧以及已知问题。

TG-LR 设置指南

快速入门指南

• 在 LoRaWAN network server 上注册设备。如果设备型号不受支持，请使用 tg-lrx2-2.0-ul-dec.js payload decoder 脚本。

• 可选地部署 Grafana + Influx（telemetry_hub.zip）docker 服务以评估设备能力。

• 将磁铁靠近簧片开关以激活设备，并等待 2 次 LED 闪烁（约 1.5 秒）。

功能

新设备处于 SHUTDOWN 模式。要激活，请使用磁铁开关命令。

表 1 型号

表 2 频段

表 3 工作模式

表 4 支持的区域

LoRaWAN

设备支持 Class A 和 B，并且可以在两个频段中运行：BAND_1GHz 和 BAND_2GHz。用户可以配置周期性链路检查、MAC 时间同步（DeviceTimeReq）和网络 ADR。

入网过程

一旦激活（RUN），设备将尝试入网。设备在主频段上发送 Join-Request，如果未收到 Join-Accept，它将等待退避间隔，然后在启用的情况下在次频段上发送下一个 Join-Request，否则再次在主频段上发送。

Join 尝试间隔取决于最后一个 Join-Request 的空中时间以及总 join 时间。参见 1 section 7。如果最后一个 join 请求使用了较慢的数据速率 - 预期间隔会更长。

Join 配置命令：lora primary-band、lora second-band、lora join-cfg。参见 Command Encoding 了解如何为下行链路将文本命令转换为二进制编码。

Link Check

设备入网后，可以执行可选的周期性链路检查。可以使用 lora link-chk 为每个频段专门配置链路检查。如果链路检查失败，设备将离开网络并重新启动入网过程。

任何网络下行链路都将重启链路检查计时器，以防止不必要的 LinkCheckReq。

时间同步

设备支持使用 DeviceTimeReq MAC 命令的可选时间同步。参见命令 lora clk-sync 了解配置参数或请求立即同步。

Class B

设备支持 Class B 操作。Class B 操作可以使用 lora class 手动请求，也可以将设备配置为在入网时使用 lora cfg-class-b 自动切换到 class B。

ADR 配置

可以禁用网络 ADR 并使用 lora adr-cfg 设置固定数据速率。

离开网络

在链路检查或确认上行链路失败的情况下，设备将离开网络并重新启动入网过程。

凭据

设备具有随每个设备提供的出厂配置默认凭据：DevEUI、JoinEUI、AppKey。

DevEUI 和 JoinEUI 是 IEEE 64 位 EUI（2），以 MSB 优先写入。空中字节序为 LSB 优先。参见 1 section 6.2.5。

AppKey 是 16 字节 AES128 加密密钥，按设备内存中的存储方式写入。AppKey 必须保密！

要更改 JoinEUI 和 AppKey，请使用命令：lora join-eui、lora net-key 和 lora cred。命令 lora join-eui 和 lora net-key 可以按任意顺序签发多次，以写入新的待处理 join 凭据。

一旦写入了新的待处理凭据，可以执行 "lora cred 600,1" 或 "app reset 0" 以使用新凭据尝试加入。如果新凭据未被 join accept 确认，设备将恢复到之前的凭据。关于已知问题请参见 LORA-275、LORA-276！

写入 JoinEUI 和 AppKey 并尝试加入的示例序列：

lora join-eui 87904163,0x00,0x16,0xC0,0x01,0xFF,0xFE,0x00,0x00
lora net-key 87904163,0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,0x0E,0x0F
lora cred 600
app reset 0
// device reboots and attempts join using new credentials with 600s timeout

上一个示例中的 JoinEUI 可以原样复制/粘贴为 00 16 C0 01 FF FE 00 00 以注册新设备。lora join-eui 参数为 MSB 优先。

警告

执行 lora cred <confirm-timeout-s>,87904163 将强制确认凭据而不进行验证 join 尝试！你可能会失去对设备的访问权限！

上行消息

每个 LoRaWAN 上行消息通过将待处理 Data Frames ID 及其内容放入 FPort 和 FRMPayload 字段来形成。所有待处理帧按升序打包，并且 ID 使用差分编码。

参见 tg-lrx2-2.0-ul-dec.js 脚本了解帧编码细节。此脚本可以原样用于 application server payload decoders。

遥测

设备配置文件

设备有 6 个可配置的配置文件。每个配置文件存储独立的传感器和上行发送配置。这允许设备快速更改运行特性，而无需代价高昂的下行配置消息。配置文件可以使用 Device Commands、磁铁或基于评估的 Data Rules 进行切换。例如在每天几次上行链路的周期性 keepalive 模式与每隔几分钟的更快速遥测之间切换。

MikroTik 可以支持你的特定用例，提供具有自定义默认配置的新设备。

设备预配置了评估配置，以展示一些可能的用例：

表 5 默认配置文件配置

参见 default-cfg.txt 了解确切的出厂默认配置命令。

配置传感器

采样间隔

可以使用 data poll-cfg 命令为特定用例配置周期性温度、湿度和电池电压采样。设备可以以高于上行帧发送速率的速率采样数据。这提供了发送平均值或执行基于规则的决策的机会。由于采样间隔会影响设备功耗，因此可以利用这一点来延长寿命。

平均

设备还跟踪采样值的平均值，位于：temperature_ema、humidity_ema、battery_mv_ema、angle_ema。命令 data ema-cfg 配置指数移动平均（EMA）周期，并且如果启用 *send-ema-**，可以选择在 current-state、dev-health、device-orientation 中发送 EMA 值。

data ema-cfg 中的计数参数 temp-cnt、humid-cnt、bat-cnt、orient-cnt 确定用于移动平均计算的系数 a。移动 EMA 基于先前的值 ema 和新的值 sample 计算如下：

ema(t) = sample(t) * a + ema(t-1) * (1 - a)

要获得 EMA 的近似时间常数 t，你需要使用 data poll-cfg 和 data orient-cfg 配置的采样间隔（interval）以及各自的计数参数（N）：

t ~ (N + 1) * interval / 2

要获得 data ema-cfg 所需的计数参数值：

N ~ 2 * t / interval - 1

示例：

使用 data poll-cfg 将温度采样间隔 th-poll-int 配置为 30s。要配置时间常数 t ~ 60 分钟的 EMA：

temp-cnt = 2 * 3600 / 30 - 1 = 239

假设使用配置文件 #0 且我们不想更改其他参数，我们需要发送命令：

data ema-cfg 1,239

直方图

所有周期性采样都会添加到温度和湿度直方图中。直方图可以配合常规遥测使用，也可以单独用于监控温度和湿度分布。使用 data temp-histo-cfg、data humid-histo-cfg 命令配置 bin 和 epoch 间隔，和/或启用 temp-histogram、humid-histogram 帧。所有直方图帧都包含 epoch 编号，以检测直方图计数器重置。由于每帧每 bin 大小限制为 1B，如果内部 bin 计数值超过 255，直方图将针对上行链路进行归一化（概率类型）。

示例配置：

data temp-histo-cfg 1,86400,0,0,1,1,-10,0,10,15,17.5,20,22.5,25.0,30
data humid-histo-cfg 1,86400,0,0,1,1,10,20,30,40,50,60,70,80,90

方向

图 1 设备加速度计轴。

可以使用命令配置相对于地球的周期性设备 3D 方向采样：data orient-cfg。此外，可以配置 3 个用户方向向量 ref-1、ref-2、ref-3 来检测特定的设备方向。用户变量 angle_1、angle_2、angle_3 包含设备最后采样的方向与用户定义向量之间的当前角度。这些变量可以在 Data Rules 中使用，以在特定方向时触发。angle_ema 是最后采样的设备方向与样本 EMA 值之间的角度。此外，还可以使用 major_axis_orientation 变量获得粗略方向。

表 6 major_axis_orientation 描述

粗略方向的优点是它会在 current-state 帧中发送。

活动监控

设备具有基于加速度计的活动监控服务。此服务将自动管理一个确定移动/活动的简单状态机。activity_s、high_activity_s、total_activity_s 统计每个状态累积的时间，activity_state、activity_state_etm 保存状态信息。

命令 data activity-cfg 可用于配置活动监控的模式和阈值。data activity-cal 可用于为特定模式自动执行校准。

level1-th 和 level2-th 的单位是 1/64 * 2G，与其他加速度计设置无关（如 data acc-cfg 中）。level2-cnt 是内部计算的，用户不可配置。level2-cnt 始终在 7..15 范围内，计算如下：

level2-cnt = 7 + round((1 - ((level2-th - level1-th - 1) / 61)) * 8)

表 7 activity_state 描述

单一模式

data activity-cfg 中的模式设置为 single。

• 如果任意轴上的加速度计采样值高于 level1-th，设备将从 IDLE 转变为 LOW 状态。

• 如果所有采样在至少 1.3s 内都低于 level1-th，设备将从 LOW 转变为 IDLE 状态。

设置配置文件 #0 单一模式且阈值为 0.25G 的示例：

data activity-cfg 1,1,8,63

双模式

data activity-cfg 中的模式设置为 dual。

在双模式下，LOW 状态有两个子状态：LOW1 和 LOW2，二者都表示 LOW。设备在这两种状态下都会报告 LOW 状态，活动计数器值会像在 LOW 状态中一样递增。唯一的区别是这些状态之间的转换逻辑。

表 8 activity_state 双模式状态转换

设置配置文件 #0 双模式且阈值为 0.25G 和 0.5G 的示例：

data activity-cfg 1,2,8,16

校准

除了手动配置 level1-th 和 level2-th 之外，还有活动校准功能。执行命令 data activity-cal 将执行 cal-level 的自动校准。level-one 将校准 level1-th，level-two 将校准 profile-mask 中选择的所有配置文件的 level2-th。对于双模式，你可以依次运行 level-one 和 level-two。校准时间为 15s。此功能最适用于周期性运动/振动。

在校准过程或活动监控测试期间启用 LED 可能有助于确保正确操作。

使用单级活动监控校准配置文件 #0 的示例：

警告

在启用方向的情况下进行活动校准会导致故障和设备重启。在校准前使用 data orient-cfg 禁用，并在完成后重新启用。参见 LORA-279。

• 将设备放置在具有周期性运动/活动的环境中进行校准。

• 发送命令：

data activity-cfg 1,1,,,1
data activity-cal 1,1,1

• 观察 LED 约 15 秒内周期性闪烁 2 次/1.5 秒。

• 测试运动检测。在 LOW 活动期间，设备将闪烁 LED 3 次/1 秒。

• 如果校准结果可接受，发送命令以禁用 LED：

data activity-cfg 1,,,,0

使用双级活动监控校准配置文件 #0 的示例：

• 将设备放置在具有周期性运动/活动的环境中进行级别 1 校准。

• 发送命令：

data activity-cfg 1,2,,,1
data activity-cal 1,1,1

• 观察 LED 约 15 秒内周期性闪烁 2 次/1.5 秒。

• 将设备放置在环境中进行级别 2 校准。

• 发送命令以校准级别 2：

data activity-cal 1,2,1

• 观察 LED 约 15 秒内周期性闪烁 2 次/1.5 秒。

• 测试运动检测。在 HIGH 活动期间，设备将闪烁 LED 6 次/1 秒。

• 如果校准结果可接受，发送命令以禁用 LED：

data activity-cfg 1,,,,0

校准后，可以使用命令 data activity-cfg 手动更改 level1-th 和 level2-th。

冲击和自由落体

命令 data acc-cfg 可用于为基本冲击和自由落体检测配置设备加速度计。帧：motion-events、impact-count 包含相关数据字段。current-state 包含 impact_evnt、free_fall_evnt 标志，表示新事件。如果偏好显式读取，可以使用这些。

变量 impact_cnt、impact_cnt_x、impact_cnt_y、impact_cnt_z、impact_etm、free_fall_cnt、free_fall_etm 允许基于规则的逻辑。

如果启用了活动监控，则不能使用冲击和自由落体检测，它们将被忽略。

数据规则

最多可使用命令配置 32 条自定义用户规则：data set-rule、data del-rule。规则具有测试表达式、可选的输入规则和要执行的操作。

添加或覆盖规则的命令语法：

data set-rule [<rule-num>],<test-expr>,[<input-expr>],[<switch-profile>],[<make-event-0>],[<make-event-1>], [<make-event-2>],[<make-event-3>],[<send-frame-0>],[<send-frame-1>],[<send-frame-2>],[<send-frame-3>],[<clr-timer-mask>]

测试表达式

<test-expr>: [^] variable-type <operator> <argument>

示例：

data set-rule 0,profile == 0
data set-rule 1,^temperature > 30.55
data set-rule 2,impact_etm < 60

使用 User Variables 数字 ID 可以给出相同的规则：

data set-rule 0,0 == 0
data set-rule 1,^8 > 30.55
data set-rule 2,24 < 60

输入表达式

如果规则需要依赖其他规则的结果，则使用输入表达式。这允许基于多个测试表达式构造复杂的逻辑。

<input-expr>: [&][|][!]<input-rule>[<]

以下配置将在磁铁开关在不到 15 秒前改变状态且温度或湿度超出范围（-5..55 和 10..90%）时发送 current-state 数据帧：

data del-rule
data set-rule 0,temperature < -5
data set-rule 1,temperature > 55
data set-rule 2,humidity < 10
data set-rule 3,humidity > 90,|0|1|2
data set-rule 4,mag_sw_etm < 15,&3<,,,,,,current-state

无论 set-rule 命令中的顺序如何，输入规则都按数字顺序评估。

操作

规则测试表达式的评估值表示数据规则本地状态。使用可选输入规则评估的本地状态表示组合状态。

如果组合状态变为 TRUE 状态，则执行可选规则操作：配置文件切换、事件生成、帧调度、用户计时器重置。

如果给定了 <switch-profile> 参数，当前配置文件将被更改。例如，如果温度降至 15 C 以下，设备将切换到配置文件 5（Device Profiles）：

data set-rule 1,temperature < 15,,5

每条规则最多可以调度 4 个不同的 Data Frames：

data set-rule 0,impact_cnt % 10,,,,,,,current-state,device-orientation,dev-health,ema-temp

如果需要发送超过 4 个帧，可以使用规则链。

每条规则最多可以生成 4 个不同的事件：

data set-rule 0,impact_cnt % 10,,,temperature_ema,humidity_ema,activity_state,timer_1

事件

操作可以选择性地生成事件。事件是带时间戳的 User Variables，在 device-events 帧中发送。可以使用 data event-cfg 命令配置事件存储。如果设备已使用 Time Synchronization 接收到绝对时间，事件将具有 POSIX 时间戳。这允许收集特定的历史数据以供稍后报告。事件上行可以周期性触发、基于某些规则触发，或使用下行命令手动触发。

磁铁开关

设备具有磁铁开关，可用于命令输入或作为磁场传感器。如果不使用，可以使用 mag svc 命令完全禁用命令输入或进行 PIN 保护。

每个设备都带有唯一的 PIN 码。

命令输入

用户必须施加 1 到 4 位数字的命令序列。每位数字连续输入。在空闲 2.5s 后，执行有效的输入命令，设备使用 LED 指示结果。成功执行的命令以 3 次 0.2s LED 闪烁指示，失败则为 1s 长的 LED 脉冲。无效命令将被忽略。

当磁场施加到设备时，LED 开始以 500ms 亮、500ms 灭的间隔闪烁（或根据 mag cfg 配置的 blink-mode）。当 LED 打开时，内部计数器从 0 开始递增。当磁场移除时，计数值被锁存为用户输入数字。如果再次施加磁场，则开始输入序列中的下一位数字。如果施加数字后的间隔大于 2.5s，则评估序列。

基于时间施加输入码时，请确保遵循此公式：T = N - 0.5，其中 N 是 1 到 9 的输入数字，T 是施加磁场的时间（秒）。数字之间的间隔必须小于 2.5s，但大于 200ms。

某些命令需要进入 PIN 模式，某些可以选择性地由 PIN 模式保护。参见表 Magnet switch commands。要进入 PIN 模式，用户必须施加随设备提供的 PIN 数字序列。一旦进入 PIN 模式，它将在可配置时间后过期，设备将返回正常模式。

也可以完全禁用磁铁命令。重新启用的唯一方法是使用 LoRaWAN 下行命令。如果磁铁传感器仅用于检测外部信号且不期望或不允许用户命令，这会很有用。

表 9 磁铁开关命令

数字输入期间的 LED 指示可以根据设备配置进行更改。可以使用 mag cfg 更改或完全禁用 LED 指示。

磁铁传感器

磁传感器始终工作（即使施加命令时也如此）。此传感器可用于检测切换事件 mag_sw_flag 或计数这些事件的数量 mag_sw_cnt。设备可以报告当前开关状态、状态变化次数和最后时间戳（UNIX/uptime）mag_switch_ts。此外，你可以基于这些属性创建规则。

命令编码

设备命令采用二进制编码以减小下行消息大小。我们提供 Python 实用程序来验证、编码和发布命令作为 LoRaWAN 二进制下行消息。

tg-lrx2-utils.zip 或使用 pip install tg-lrx2-utils 安装

示例配置，将 current-state 和 activity 帧上行设置为每 600 秒一次，将 mag-switch 设置为每 43200 秒一次，作为已确认消息：

# lora-script.txt
frame set-cfg 1,601,0,0,current-state,activity
frame set-cfg 1,43200,1,0,mag-switch

我们可以使用 tg-lrx2-encode 将文本命令转换为用于下行链路的二进制消息：

tg-lrx2-encode --script ./lora-script.txt --dev-desc ./tg-lrx2-2.0-desc.yml --max-len=50 --out ./lora-pub.yml

tg-lrx2-2.0-desc.yml 包含完整的设备特征描述，并被其他工具使用。请确保为特定设备和 FW 版本使用正确的文件！

lora-pub.yml 将包含用于下行链路的序列化二进制负载。你可以使用可用的 Web 工具手动调度它们，或使用 tg-lrx2-pub 在 The Things Network 上调度它们：

tg-lrx2-pub --host ./ttn-app.yml --dl-msg ./lora-pub.yml device-id

示例 TTN 凭据文件：

# ttn-app.yml
app-id: "ttn-tag-demo@ttn"
host: "eu1.cloud.thethings.industries"
port: 1883
user: "ttn-tag-demo@ttn"
password: "NNSXS.5G..."

tg-lrx2-encode 也接受 CLI 上的命令字符串。这可用于单行或几行命令：

tg-lrx2-encode --cmd $'frame send device-orientation\napp profile 1,0' --dev-desc ./tg-lrx2-2.0-desc.yml --max-len=50 --out ./lora-pub.yml
tg-lrx2-pub --host ./ttn-app.yml --dl-msg ./lora-pub.yml device-id

设备命令

所有设备命令都由 group-name 和 cmd-name 组成。可选参数在方括号中给出。对于 tg-lrx2-encode 脚本，参数必须用逗号分隔。group-name 和 cmd-name 也可以用逗号分隔，但空格也被接受。

示例：

app factory-reset <key>,[<fw-def>],<delay-ms>

参数 <key> 和 <delay-ms> 是必需的，但 <fw-def> 是可选的，可以省略：

app factory-reset 984651411,,2500

每个参数都有有效的输入范围和格式。某些参数只允许特定选择或范围之间的选择。

大多数参数接受整数值。%f 表示参数接受小数值。使用这些值会导致更大的下行负载，因此如果可能，应优先使用整数值。variable-type 表示参数接受用户变量名称或相应的整数 ID。frame-type 表示参数接受数据帧名称或整数 ID。tg-lrx2-encode 会自动将这些名称转换为数字 ID。

app set-mode

app profile

app reset

app factory-reset

app led

app set-time

lora set-region

lora primary-band

lora second-band

lora join-cfg

lora link-chk

lora adr-cfg

lora clk-sync

lora cfg-class-b

lora class

lora join-eui

lora net-key

lora cred

frame send

frame set-cfg

frame clear-cfg

mag cfg

mag svc

data sample

data next-epoch

data poll-cfg

data temp-histo-cfg

data humid-histo-cfg

data ema-cfg

data activity-cfg

data acc-cfg

data orient-cfg

data event-cfg

data erase-events

data del-rule

data set-rule

data timer

data activity-cal

Data Frames

User Variables

Frame Data Fields

已知问题

LORA-275

描述： 如果在禁用次频段的情况下启动凭据更改 - 设备将不会超时 join。设备将一直卡在尝试 join 的状态，直到成功或重新启动。

解决方法： 如果新凭据无效，请使用磁铁开关命令物理重启设备。

LORA-276

描述： 执行 lora cred 时，设备将在下一次 join 尝试时基于总运行时间而非命令执行时间使 join 过程超时。如果运行时间长于 confirm-timeout-s 参数，设备将正好在一次失败的 join 尝试后超时。

解决方法： 在尝试更改凭据之前签发设备重置命令 app reset。或者手动多次重试凭据更改。

LORA-279

描述： 如果在启用方向检测的情况下执行活动校准，设备可能会发生故障并重启。

解决方法： 在执行活动校准之前使用 data orient-cfg 禁用方向检测，并在之后重新启用。

相关文档