TG-LR82 / TG-LR92 User Manual

Quickstart Guide

• Register device on LoRaWAN network server. Use tg-lrx2-2.0-ul-dec.js payload decoder script if device model not supported.

• Activate the device: new devices start in SHUTDOWN. Hold the magnet near the switch for about 1.5 s to enter digit 2, then remove it. The device confirms the command with short LED blinks and restarts in RUN mode.

• Wait for network join. Default profile 0 sends current-state and device-orientation every 5 minutes. The first uplink after join can also contain version, serial-number, cfg-state, and dev-health frames.

• Decode the first uplink to verify temperature, humidity, orientation, battery, and device identity data. See Magnet Switch for command input details.

Functionality

note

New device is in SHUTDOWN mode. To activate use magnet switch commands.

Models

Model	Description	Sensors
TG-LR82	LoRaWAN 1.0.4 Class A, B, 863.0 - 869.0 MHz band.	TMP116N, HDC2010, LIS2DW12
TG-LR92	LoRaWAN 1.0.4 Class A, B, 900.0 - 928.0 MHz band.	TMP116N, HDC2010, LIS2DW12

note

For safety warnings, hardware specifications, installation, and regulatory information, see the TG-LR82 hardware page and TG-LR92 hardware page.

Bands

Numeric code	Name	Description
1	BAND_1GHz	Sub-GHz operating band. Frequency range is based on device Model.
2	BAND_2GHz	2.4GHz ISM band. Supported by both models; uses the LoRaWAN ISM2400 region automatically when active.

Operating modes

Numeric code	Mode	Description
0	SHUTDOWN	Device in low power mode. Network and data services are stopped, but all magnet switch commands remain available. Settings can be changed in this mode and the device activated afterwards.
1	RUN	Device joins network and sends uplinks based on current profile and configuration.

Supported regions

X-Y Code	downlink	Common Name	TG-LR82	TG-LR92
1-1	1	EU868	Yes
2-1	2	AS923_GRP1		Yes
3-1	3	US915		Yes
4-1	4	AU915		Yes
		ISM2400	Yes	Yes
6-1	7	AS923_GRP2		Yes
7-1	8	AS923_GRP3		Yes
8-1	9	IN865	Yes
9-1	10	KR920		Yes

The X-Y code is the magnet switch sequence. The numeric downlink value is used by lora set-region.

ISM2400 is the LoRaWAN 2.4 GHz region. It is supported by both models and is used automatically whenever BAND_2GHz is active. BAND_2GHz can be the primary or secondary band (lora primary-band, lora second-band).

lora set-region configures only the sub-GHz region. It cannot select ISM2400, and ISM2400 is not available while only BAND_1GHz is active. There is currently no independent ISM2400 region selection or runtime region switch; change the active band to use it.

LoRaWAN

Device supports Class A and B, and can operate in two frequency bands: BAND_1GHz and BAND_2GHz. User can configure periodic link check, MAC time synchronization (DeviceTimeReq) and network ADR.

Join Procedure

Once activated (RUN) device will attempt to join network. Device sends Join-Request on primary band and if Join-Accept is not received it will wait back-off interval and send next Join-Request on secondary band if enabled, otherwise primary-band again.

note

Join attempt interval depends on time on air for last Join-Request and total join time. See 1 section 7. If last join request used slower data rate - expect longer interval.

Join configuration commands: lora primary-band, lora second-band, lora join-cfg. See Command Encoding on how to convert text commands to binary encoding for downlink.

Link Check

Link check lets the end device verify that the network is still reachable. Most uplinks can be non-confirmed, so they do not prove that the network received them. Use periodic link check or confirmed uplinks when the device must detect a lost network.

Link check can be configured specifically for each band using lora link-chk. If link check fails, the device leaves the network and restarts the join procedure. A failed confirmed uplink has the same effect.

note

Any network downlink will restart link check timer to prevent unnecessary LinkCheckReq.

Time Synchronization

Time synchronization gives stored events absolute timestamps instead of device uptime. Events and telemetry can be stored locally and sent later, so absolute time lets the application know when an event actually occurred. This is useful when the device is outside network coverage and reports the collected data after it returns to coverage.

Device supports optional time synchronization using DeviceTimeReq MAC command. See command lora clk-sync for configuration parameters or to request immediate synchronization.

Class B

Device supports Class B operation. Class B operation can be either manually requested using lora class or device can be configured to automatically switch to class B on network join using lora cfg-class-b.

ADR Configuration

It is possible to disable network ADR and set fixed data rate using lora adr-cfg.

warning

In FW 2.0.1, ADR changes made while the device is joined may not take effect until the device rejoins or restarts (LORA-281). With network ADR disabled, only DR0 works as a fixed data rate (LORA-282). Reset the device after changing ADR; when network ADR is disabled, use DR0.

Leaving Network

In case of Link Check or confirmed uplink failure device leaves network and restarts join procedure.

Credentials

Device has factory configured default credentials that come with each device: DevEUI, JoinEUI, AppKey.

DevEUI and JoinEUI are IEEE 64-bit EUI (2) written MSB first. On air byte order is LSB first. See 1 section 6.2.5.

AppKey is 16 byte AES128 encryption key and is written as stored in device memory. AppKey must be kept secret!

To change JoinEUI and AppKey use commands: lora join-eui, lora net-key and lora cred. Commands lora join-eui and lora net-key can be issued in any order and multiple times to write new pending join credentials.

Once new pending credentials are written “lora cred 600,1” or “app reset 0” can be executed to attempt join with new credentials. If new credentials are not confirmed by join accept device will revert to previous. See LORA-275, LORA-276 for known issues!

Example sequence where JoinEUI and AppKey are written and join is attempted:

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 from previous example can be copy/pasted as is 00 16 C0 01 FF FE 00 00 to register new device. lora join-eui parameters are MSB first.

warning

Executing lora cred <confirm-timeout-s>,87904163 will force confirm credentials without verification join attempt! You may lose access to device!

Uplink Messages

Each LoRaWAN uplink can carry one or more pending Data Frames. Frames are added in ascending frame-ID order. The first frame-type delta is encoded in the FPort field; additional type deltas are encoded at the start of FRMPayload, followed by the frame contents. The FPort value therefore depends on the first frame type and is not a fixed application port.

The device packs only frames that fit in the current payload. Frames that do not fit remain pending for the next uplink. If any packed frame is configured as confirmed, the whole uplink is sent as confirmed. A failed confirmed uplink causes the device to leave the network and restart the join procedure.

note

See tg-lrx2-2.0-ul-dec.js script for frame encoding details. This script can be used as is in application server payload decoders.

Telemetry

Device Profiles

Device has 6 configurable profiles. Each profile stores independent sensor and uplink send configuration. This allows device to quickly change operating characteristics without requiring costly downlink configuration messages. Profile can be switched using Device Commands, magnet or even based on evaluated Data Rules. For instance switching between periodic keepalive mode with uplinks few times per day to more rapid telemetry every few minutes.

note

MikroTik can support your specific use case, new devices with custom default configuration are available.

Devices come preconfigured with evaluation configuration to showcase some of possible use case:

Default profile configuration

Profile Number	Name	Description
0	Sensor Telemetry	Send current-state, device-orientation every 5 minutes. Send remaining telemetry every 60 minutes.
1	Activity Monitor	Send activity, full-activity, current-state every 60 min and generate activity_state events on LOW and IDLE state changes.
2	Magnet Switch	Send mag-switch, current-state, device-events every 60 minutes and generate a mag_sw_cnt event when the magnet has been removed for at least 20 seconds. Save up to 10 events.
3	Orientation	Send current-state, device-events, device-orientation every 60 minutes. Generate a device-orientation frame when the rotation angle exceeds 30 degrees. Generate angle_1 and meta_rule_id events when the device is close to reference vector V=(0,1,1). Save up to 3 events.
4	Asset Monitor	Send dev-health, device-orientation, histograms, ema-temp, ema-humid, motion-events, impact-count, and device-events every 3 hours. Additional frames and events are generated by the factory rules for orientation, impact, free fall, temperature, humidity, and magnet removal. Save up to 10 events.
5	Empty

See default-cfg.txt for exact factory default configuration commands.

Configuring Sensors

Sampling Intervals

Periodic temperature, humidity and battery voltage sampling can be configured for specific use cases using data poll-cfg command. Device can sample data at a higher rate than uplink frames are sent. This gives opportunity to send average values or to perform rule based decisions. Since sampling interval influences device power consumption this can be leveraged to improve lifetime.

Averaging

Device also tracks average of sampled values in: temperature_ema, humidity_ema, battery_mv_ema, angle_ema. Command data ema-cfg configures exponential moving average (EMA) period and optionally can send EMA values in current-state, dev-health, device-orientation if send-ema-* is enabled.

Count parameters temp-cnt, humid-cnt, bat-cnt, orient-cnt in data ema-cfg determine coefficient a used for moving average calculation. Moving EMA is calculated based on previous value ema and new value sample as:

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

To get approximate time constant t of EMA you need to use sampling intervals configured by data poll-cfg and data orient-cfg (interval) and respective count parameter (N):

t ~ (N + 1) * interval / 2

To get required count parameter value for data ema-cfg:

N ~ 2 * t / interval - 1

Example:

Temperature sampling interval th-poll-int is configured to 30s using data poll-cfg. To configure EMA with time constant t ~ 60 minutes:

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

Assuming profile #0 is used and we don’t want to change other parameters we need to send command:

data ema-cfg 1,239

Histogram

All periodic samples are added to temperature and humidity histograms. Histograms can be used in addition to regular telemetry or simply stand alone to monitor temperature and humidity distribution. Configure bins and epoch intervals using data temp-histo-cfg, data humid-histo-cfg commands and/or enable temp-histogram, humid-histogram frames. All histogram frames contain epoch number to detect histogram counter reset. Since frame size is limited to 1B per bin, if internal bin counter value is above 255 histogram will be normalized (probability type) for uplink.

Example configuration:

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

Orientation

Device accelerometer axis.

Periodic device 3D orientation sampling relative to Earth can be configured using command: data orient-cfg. In addition 3 user orientation vectors ref-1, ref-2, ref-3 can be configured to detect specific device orientations. User variables angle_1, angle_2, angle_3 contain current angle between device last sampled orientation and user defined vector. These variables can be used in Data Rules to trigger on specific orientation. angle_ema is angle between last sampled device orientation and EMA value of samples. In addition coarse orientation is also available with major_axis_orientation variable.

major_axis_orientation description

Value	Numeric code	Description
XH	0	X up
HL	1	X down
YH	2	Y up
YL	3	Y down
ZH	4	Z up
ZL	5	Z down
DISABLED	7	sensor disabled

Coarse orientation has advantage that it is sent in current-state frame.

Activity Monitor

Device has activity monitoring service based on accelerometer. This service will automatically manage simple state machine that determines movement/activity. activity_s, high_activity_s, total_activity_s count accumulated time in each state activity_state, activity_state_etm hold state information.

Command data activity-cfg can be used to configure mode and thresholds for activity monitoring. data activity-cal can be used to automatically perform calibration for specific mode.

level1-th and level2-th units are 1/64 * 2G irrespective of other accelerometer settings (like in data acc-cfg). level2-cnt is internally computed and not user configurable. level2-cnt is always in range 7..15 and calculated as:

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

activity_state description

Numeric code	Value
0	IDLE
1	LOW
2	HIGH
3	DISABLED

Single Mode

Mode in data activity-cfg is set to single.

• If accelerometer sample value in any axis is above level1-th device transitions from IDLE to LOW state.

• If all samples for at least 1.3s are below level1-th device transitions from LOW to IDLE state.

note

The 1.3 s LOW-to-IDLE timing applies to single-level mode. In dual mode the accelerometer and state machine use different timing; use the 5 s transitions in the Dual Mode table only for dual mode.

Example to set profile #0 single mode with threshold 0.25G:

data activity-cfg 1,1,8,63

Dual Mode

Mode in data activity-cfg is set to dual.

In dual mode LOW state has two sub states: LOW1 and LOW2 that both represent LOW. Device will report LOW state during both of these and actvity counter values are incremented as if in LOW state. Only difference is transition logic between these states.

activity_state dual mode state transitions

Current	Next	Condition
IDLE	LOW2	sample > level1-th
LOW2	LOW1	sample < level2-th at least 5s
LOW1	LOW2	sample > level1-th
LOW2	HIGH	sample > level2-th at least level2-cnt times
LOW1	IDLE	sample < level1-th at least 5s
HIGH	LOW1	sample < level2-th at least 5s

Example to set profile #0 dual mode with thresholds 0.25G and 0.5G:

data activity-cfg 1,2,8,16

Calibration

In addition to manually configuring level1-th and level2-th there is activity calibration functionality. Executing command data activity-cal will perform auto calibration of cal-level. level-one will calibrate level1-th and level-two will calibrate level2-th for all profiles selected in profile-mask. For dual mode you can run level-one and level-two in sequence. Calibration time is 15s. This functionality is mostly suited for periodic motion/vibration.

note

It may be useful to enable LED during calibration procedure or activity monitor testing to ensure correct operation.

Example to calibrate profile #0 with single level activity monitor:

warning

Activity calibration with orientation enabled causes fault and device reboot. Disable using data orient-cfg before calibration and re-enable after finished. See LORA-279.

1. Place device in environment with periodic motion/activity to calibrate.

2. Send commands:

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

3. Observe LED periodic blink 2x/1.5s for ~ 15s.

4. Test motion detection. During LOW activity device will blink LED 3x/1s.

5. If calibration results are acceptable send command to disable LED:

   data activity-cfg 1,,,,0

Example to calibrate profile #0 with dual level activity monitor:

1. Place device in environment with periodic motion/activity for level 1 calibration.

2. Send commands:

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

3. Observe LED periodic blink 2x/1.5s for ~ 15s.

4. Place device in environment for level 2 calibration.

5. Send commands to calibrate level 2:

   data activity-cal 1,2,1

6. Observe LED periodic blink 2x/1.5s for ~ 15s.

7. Test motion detection. During HIGH activity device will blink LED 6x/1s.

8. If calibration results are acceptable send command to disable LED:

   data activity-cfg 1,,,,0

note

After calibration level1-th and level2-th can be manually changed using command data activity-cfg.

Impact and Free fall

Command data acc-cfg can be used to configure device accelerometer for basic impact and free-fall detection. Frames: motion-events, impact-count contain relevant data fields. current-state contains impact_evnt, free_fall_evnt flags that indicate new event. These can be used if explicit read is preferred.

Variables impact_cnt, impact_cnt_x, impact_cnt_y, impact_cnt_z, impact_etm, free_fall_cnt, free_fall_etm allow rule based logic.

warning

If Activity Monitor is enabled impact and free fall detection can’t be used and will be ignored.

Data Rules

Up to 32 user rules can be stored using data set-rule and data del-rule. A rule contains a test expression, optional input expressions, and optional actions. If <rule-num> is omitted, the first free rule slot is used. data del-rule without a rule number deletes all rules; with a rule number it deletes one rule. Rule configuration persists across reboots; rule evaluation state is reset on reboot.

Command syntax to add or override rules:

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>]

Rule Model

The test expression is evaluated against one value from User Variables and produces the rule local state. The local state combined with optional input rules produces the rule combined state.

An action is executed only when combined state changes from false to true. While it remains true, actions are not repeated. When it changes back to false, no action is executed.

Rules are evaluated in dependency order. Rules without inputs are evaluated first, then rules whose input rules have already been evaluated. Rule numbers identify rules and input references; they do not define evaluation order. A rule that depends on itself directly or through other rules is not evaluated.

Test Expression

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

Element	Description
[^]	use the absolute value of the variable in the expression
variable-type	variable name or numeric ID from User Variables
<operator>	>, >=, <, <=, ==, !=, %
<argument>	numeric value

The % operator is true when the integer part of abs(variable) % abs(argument) is zero. <argument> must not be zero.

Fractional arguments are supported and use fixed-point encoding. Prefer integer arguments where possible because fractional values increase rule encoding size. Use == and != only for exact-value variables; for measured analog values, prefer threshold comparisons.

Time values such as mag_sw_etm, impact_etm, timer_1, profile_etm, and activity_state_etm are in seconds. daytime_tm and unix_time are only useful after Time Synchronization.

Example:

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

Use variable names in rule commands. The tg-lrx2-encode utility converts variable and frame names to numeric IDs and encodes the commands into the compact binary downlink format.

Input Expression

Input expression is used if a rule needs to depend on the result of other rules. This allows constructing logic based on multiple test expressions.

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

Term	Description
[&]	AND input with the current combined value
[|]	OR input with the current combined value
[!]	invert the input value
<input-rule>	rule number whose state is used
[<]	use the input rule combined state, otherwise its local state.

The first input term is combined with the rule local state. Each additional term is applied to the result. There are no parentheses and no operator precedence.

warning

Terms are applied in ascending input-rule number order, regardless of the order written in the command. This is easy to miss when composing expressions.

Following configuration will send current-state data frame if magnet switch changed state less than 15s ago and temperature or humidity are out of range (-5..55 and 10..90%):

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

Rule 3 combines its own result with rules 0, 1, and 2 using OR. Rule 4 combines its own result with the combined state of rule 3 using AND. The action of rule 4 therefore runs when the magnet switch changed recently and any temperature or humidity threshold is true.

warning

Rule numbers are not evaluation order. Rules are evaluated in dependency order. Avoid circular dependencies: rules in a cycle are not evaluated. Input rules must be enabled; disabled input rules are not part of the evaluation order.

Actions

If combined state changes to true, actions are executed once for that transition. Actions execute in this order: generate events, schedule frames, reset user timers. The optional profile switch is applied after all rules in the current evaluation pass. Rules in the same pass therefore still see the previous profile; the new profile is used from the next evaluation pass.

If <switch-profile> parameter is given, the active profile is changed. The value range is 0..5. This does not make the profile the default; use app profile with make-default or a magnet profile command to persist it. For example if temperature drops below 15 C device will switch to profile 5 (Device Profiles):

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

Up to 4 different Data Frames can be scheduled per rule. Scheduled frames are sent as soon as the network stack has air time; they do not wait for the configured periodic uplink interval:

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

note

Rule chaining can be used if more than 4 frames should be sent.

Up to 4 different events can be generated per rule. Events are captured when the action executes and are described in Events:

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

The optional <clr-timer-mask> resets user timers when the action executes. See Timers and Rule ID Events.

Events

Actions can optionally generate events. Events are stored in device memory and sent in the device-events frame. Event storage is configured per profile using data event-cfg:

Option	Description
max-count	Maximum stored events (0 disables event storage, range 1..100).
send-th	Schedule device-events when the pending count is at least this value. 0 schedules a frame after every new event.
discard	Select oldest or newest event when storage is full.
send-all	After a device-events frame is sent, schedule another frame while events remain.

Events are sent when the device-events frame is scheduled periodically using frame set-cfg, immediately using frame send, by a rule send-frame action, or automatically by the send-th threshold. Use data erase-events to erase all events or a selected number of oldest events.

Each event record in the device-events frame contains:

• a length byte; bit 7 set means more records follow;

• a 4-byte timestamp;

• a 1-byte event code;

• an optional value.

The timestamp is UNIX time after Time Synchronization, otherwise device uptime. Event codes 0..99 are user-variable events and carry the variable value. Event codes 100..229 are reserved for rule events; meta_rule_id uses code 100 + rule-number and carries no value. The supplied payload decoder interprets these records.

Example commands:

data event-cfg 1,50,10,0,1
data erase-events
data erase-events 10

The first command configures profile 0 to store at most 50 events, schedule device-events when at least 10 events are pending, discard the oldest event when full, and keep sending while events remain. The second command erases all events; the third erases the 10 oldest events.

Timers and Rule ID Events

timer_1, timer_2, timer_3, and timer_4 are free-running user timers. They count seconds from the last reset and are reset on device reboot.

data timer sets the elapsed value of selected timers. Omitted parameters are left unchanged:

data timer 0
data timer ,0
data timer ,,,0

The first command resets timer_1, the second resets timer_2, and the third resets timer_4.

The <clr-timer-mask> action parameter is a 4-bit mask: bit 0 resets timer_1, bit 1 resets timer_2, bit 2 resets timer_3, and bit 3 resets timer_4.

meta_rule_id is a special event-action value. It cannot be used as a normal test variable. When an action generates an event for meta_rule_id, the event code is 100 + rule-number and the event has no value. The decoder reports this event as data_rule. This identifies which rule fired when several rules send the same frame. For example:

data set-rule 0,temperature > 30,,,temperature,meta_rule_id,,,current-state
data set-rule 1,humidity > 90,,,humidity,meta_rule_id,,,current-state

When either rule fires, current-state is scheduled and the event identifies the rule that triggered it.

Magnet Switch

Device has magnet switch that can be used for command input or as magnetic field sensor. If unused, command input can be completely disabled or PIN protected using mag svc command.

note

Unique PIN code comes with each device.

Command Input

User must apply command sequence of 1 to 4 digits. Each digit is entered consecutively. After 2.5s idle, valid input command is executed and device indicates result using LED. Successfully executed command is indicated with 3x 0.2s LED blinks and failure is 1s long LED pulse. Invalid commands are ignored.

When magnetic field is applied to device, LED starts blinking with interval 500ms ON, 500ms OFF (or according to mag cfg configured blink-mode). When LED is switched on, internal counter is incremented starting from 0. When magnetic field is removed counter value is latched as user input digit. If magnetic field is applied again, next digit in input sequence is started. If interval after applying digit is larger than 2.5s, sequence is evaluated.

note

When applying input code based on time, ensure to follow this equation: T = N - 0.5, where N is input digit from 1 to 9 and T is time in seconds to apply magnetic field. The interval between digits must be less than 2.5s, but more than 200ms.

Some commands require PIN mode to be entered and some can be optionally protected by PIN mode. See table Magnet switch commands. To enter PIN mode, user must apply sequence of PIN digits provided with the device. Once PIN mode is entered it will expire after configurable time and device will return back to normal mode.

warning

It is also possible to completely disable magnet commands. Only way to re-enable is using LoRaWAN downlink command. This can be useful if magnet sensor is used only for detecting external signals and no user commands are expected or allowed.

Magnet switch commands

Sequence	PIN mode	Command description
2	optional	Activate - enable RUN mode.
3-1	optional	Trigger current-state frame uplink.
4-1-X	optional	Switch device profile, where X is Profile Number + 1 [1..6].
4-2-1	optional	Set primary band to BAND_1GHz.
4-2-2	optional	Set primary band to BAND_2GHz.
4-3-1	optional	Enable secondary band.
4-3-9	optional	Disable secondary band.
6-1	optional	Device restart.
6-2-9	optional	Deactivate device - SHUTDOWN mode.
9-X-Y	optional	Set region for sub GHz band as per Supported regions.
6-9-9	mandatory	Device factory reset.
3-1-5	mandatory	Exit PIN mode.
A-B-C-D	–	Enter PIN mode. A-B-C-D are digits of device factory PIN code.
5-3-1	optional	Reserved.

note

LED indications during digit input can be changed based on device configuration. It is possible to change or completely disable LED indications using mag cfg.

Magnet Sensor

Magnetic sensor is always operational (even when commands are applied). This sensor can be utilized to detect switching events mag_sw_flag or to count number of these events mag_sw_cnt. Device can report current switch state, number of state changes and last time stamp (UNIX/uptime) mag_switch_ts. Additionally you can create rules based on these attributes.

Command Encoding

Device commands are binary encoded to reduce downlink message size. We provide Python utilities to verify, encode and publish commands as LoRaWAN binary downlink messages.

Install from PyPI with pip install tg-lrx2-utils.

Downlink Ports

Port	Purpose
2	Binary command message. After the commands are processed, the device schedules a cfg-state uplink with the current configuration checksums.
3	Binary command message.

tg-lrx2-encode places all encoded messages on the command port except the last message, which is placed on the configuration port to trigger the cfg-state response. Send all generated messages in file order. If –max-len splits a script into several messages, the order is required.

Example configuration to set current-state and activity frame uplink every 600 seconds and mag-switch every 43200 seconds as confirmed message:

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

We can use tg-lrx2-encode to convert text commands to binary messages for downlink:

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

note

tg-lrx2-utils includes a device descriptor and uses it by default. Pass –dev-desc only when you need to override it, for example to use the 2.0 descriptor supplied with this manual. Make sure the descriptor matches the device and FW version.

lora-pub.yml will contain serialized binary payloads to use for downlink. You can either manually schedule them using available web tools or use tg-lrx2-pub to schedule them on The Things Network:

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

Example TTN credential file:

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

warning

ttn-app.yml contains an access key. Keep it out of source control and do not publish it.

tg-lrx2-encode accepts command strings on CLI as well. This can be used for single or few lines of commands:

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

Device Commands

All device commands consist of group-name and cmd-name. Optional parameters are given in square brackets. Parameters must be comma separated for tg-lrx2-encode script. group-name and cmd-name can also be comma separated but spaces are also accepted.

Example:

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

Parameters <key> and <delay-ms> are mandatory, but <fw-def> is optional and can be omitted:

app factory-reset 984651411,,2500

Each parameter has a valid input range and format. Some parameters allow only a specific choice between values or a choice between ranges.

Most parameters accept integer values. %f indicates that parameter accepts fractional value. Use of these values results in larger downlink payload so if possible integer values should be preferred. variable-type indicates that parameter accepts either user variable name or respective integer ID. frame-type indicates that parameter accepts either data frame name or integer ID. tg-lrx2-encode automatically converts these names to numeric ID.

The reference includes advanced manual commands such as data sample and data next-epoch. See Advanced Operations.

app set-mode

Set device operating mode

Syntax

app set-mode <mode>

Parameter	Range	Description
mode	0	SHUTDOWN
	1	RUN

app profile

Switch active profile and optionally make default

Syntax

app profile <profile-num>,<make-default>

Parameter	Range	Description
profile-num	0..5
make-default	0	no
	1	yes

app reset

System reset

Syntax

app reset <type>

Parameter	Range	Description
type	0	board
	1	app only

app factory-reset

Reboot device, clear saved configuration and set to defaults (optional)

Syntax

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

Parameter	Range	Description
key	984651411
fw-def	784565141	don’t apply default configuration
delay-ms	0..65535

app led

Configure application LED signals

Syntax

app led [<enable>]

Parameter	Range	Description
enable	0	no
	1	yes

app set-time

Set UNIX time relative to device uptime

Syntax

app set-time [<unix-time-s>],<uptime-s>

Parameter	Range	Description
unix-time-s	0..4294967295
uptime-s	0..4294967295

lora set-region

Set LoRaWAN region for sub GHz band

Syntax

lora set-region <region-code>

Parameter	Range	Description
region-code	1	EU868
	2	AS923-1
	3	US915
	4	AU915
	7	AS923-2
	8	AS923-3
	9	IN865
	10	KR920

lora primary-band

Select primary band

Syntax

lora primary-band <band>

Parameter	Range	Description
band	1	<1GHz
	2	2.45GHz

lora second-band

Enable or disable secondary band

Syntax

lora second-band <mode>

Parameter	Range	Description
mode	0	off
	1	on

lora join-cfg

Configure join duty cycle for band

Syntax

lora join-cfg <band>,<duty>

Parameter	Range	Description
band	1	<1GHz
	2	2.45GHz
duty	0	0.1%
	1..254
	255	1%

lora link-chk

Set band specific link check interval and timeout

Syntax

lora link-chk <band>,<int-minutes>

Parameter	Range	Description
band	1	<1GHz
	2	2.45GHz
int-minutes	0	off
	5..500000

lora adr-cfg

Enable network ADR or configure fixed data rate

Syntax

lora adr-cfg <en-netw-adr>,[<fixed-data-rate>]

Parameter	Range	Description
en-netw-adr	0	off
	1	on
fixed-data-rate	0..6

lora clk-sync

Absolute time synchronization

Syntax

lora clk-sync [<int-minutes>],[<leap-sec>],<sync-now>,[<retry-s>],[<retry-cnt>]

Parameter	Range	Description
int-minutes	0	off
	1..65535
leap-sec	-128..127
sync-now	0	no
	1	yes
retry-s	0..255
retry-cnt	0..255

lora cfg-class-b

Configure LoRaWAN Class B

Syntax

lora cfg-class-b [<auto-en>],[<ping-slot-int-s>]

Parameter	Range	Description
auto-en	0	off
	1	on
ping-slot-int-s	1
	2
	4
	8
	16
	32
	64
	128

lora class

Switch LoRaWAN class

Syntax

lora class <class>

Parameter	Range	Description
class	0	A
	1	B

lora join-eui

Override network JoinEUI

Syntax

lora join-eui <cred-ch-key>,<eui-0>,<eui-1>,<eui-2>,<eui-3>,<eui-4>,<eui-5>,<eui-6>,<eui-7>

Parameter	Range	Description
cred-ch-key	87904163
eui-0	0..255
eui-1	0..255
eui-2	0..255
eui-3	0..255
eui-4	0..255
eui-5	0..255
eui-6	0..255
eui-7	0..255

lora net-key

Override network AppKey

Syntax

lora net-key <cred-ch-key>,<key-0>,<key-1>,<key-2>,<key-3>,<key-4>,<key-5>,<key-6>,<key-7>,<key-8>,<key-9>,<key-10>,<key-11>,<key-12>,<key-13>,<key-14>,<key-15>

Parameter	Range	Description
cred-ch-key	87904163
key-0	0..255
key-1	0..255
key-2	0..255
key-3	0..255
key-4	0..255
key-5	0..255
key-6	0..255
key-7	0..255
key-8	0..255
key-9	0..255
key-10	0..255
key-11	0..255
key-12	0..255
key-13	0..255
key-14	0..255
key-15	0..255

lora cred

User network credential management

Syntax

lora cred [<confirm-timeout-s>],[<action>]

Parameter	Range	Description
confirm-timeout-s	60..65535	revert if not joined
action	0	clear pending
	1	try now
	87904163	force confirm

frame send

Schedule uplink frames

Syntax

frame send <frame-id>,...

Parameter	Range	Description
frame-id	frame-type

frame set-cfg

Set uplink frame configuration

Syntax

frame set-cfg <profile-mask>,[<ul-period-s>],[<confirmed>],[<on-join>],<frame-id>,...

Parameter	Range	Description
profile-mask	1..63	bitfield
ul-period-s	0	off
	1..65535
confirmed	0	no
	1	yes
on-join	0	no
	1	yes
frame-id	frame-type

frame clear-cfg

Clear all frame config for specified profiles (as if ‘set-cfg profile-mask,0,0,0,…’)

Syntax

frame clear-cfg <profile-mask>

Parameter	Range	Description
profile-mask	1..63	bitfield

mag cfg

Set configuration

Syntax

mag cfg [<pin-timeout>],[<pin-protect>],[<blink-mode>]

Parameter	Range	Description
pin-timeout	0..65535
pin-protect	0	off
	1	on
blink-mode	0	half duty
	1	pulse
	2	off

mag svc

Enable or disable magnet command interface

Syntax

mag svc <new-state>,<key>

Parameter	Range	Description
new-state	0	off
	1	on
key	649864801

data sample

Force sensor polling

Syntax

data sample

data next-epoch

Manually start next histogram epoch

Syntax

data next-epoch <type>

Parameter	Range	Description
type	all
	temp
	humid

data poll-cfg

Set data polling configuration

Syntax

data poll-cfg <profile-mask>,[<th-poll-int>],[<sync-period>],[<on-mag-switch>],[<on-activity-change>],[<on-impact>],[<on-free-fall>],[<on-ul-stale>],[<bat-poll-int>]

Parameter	Range	Description
profile-mask	1..63	bitfield
th-poll-int	1..4294967295	temperature and humidity
sync-period	0	no
	1	yes
on-mag-switch	0	no
	1	yes
on-activity-change	0	no
	1	yes
on-impact	0	no
	1	yes
on-free-fall	0	no
	1	yes
on-ul-stale	0	no
	1	yes
bat-poll-int	1..4294967295	battery voltage

data temp-histo-cfg

Set temperature histogram configuration

Syntax

data temp-histo-cfg <profile-mask>,[<epoch-interval-s>],[<epoch-interval-cnt>],[<epoch-max-bin-cnt>],[<frame-on-new-epoch>],[<lim-divider>],[<bin-limit-0>],[<bin-limit-1>],[<bin-limit-2>],[<bin-limit-3>],[<bin-limit-4>],[<bin-limit-5>],[<bin-limit-6>],[<bin-limit-7>],[<bin-limit-8>]

Parameter	Range	Description
profile-mask	1..63	bitfield
epoch-interval-s	0	off
	1..4294967295
epoch-interval-cnt	0	off
	1..4294967295
epoch-max-bin-cnt	0	off
	1..4294967295
frame-on-new-epoch	0	no
	1	yes
lim-divider	1..4294967295
bin-limit-0	-128..127	°C
	%f
bin-limit-1	-128..127	°C
	%f
bin-limit-2	-128..127	°C
	%f
bin-limit-3	-128..127	°C
	%f
bin-limit-4	-128..127	°C
	%f
bin-limit-5	-128..127	°C
	%f
bin-limit-6	-128..127	°C
	%f
bin-limit-7	-128..127	°C
	%f
bin-limit-8	-128..127	°C
	%f

data humid-histo-cfg

Set humidity histogram configuration

Syntax

data humid-histo-cfg <profile-mask>,[<epoch-interval-s>],[<epoch-interval-cnt>],[<epoch-max-bin-cnt>],[<frame-on-new-epoch>],[<lim-divider>],[<bin-limit-0>],[<bin-limit-1>],[<bin-limit-2>],[<bin-limit-3>],[<bin-limit-4>],[<bin-limit-5>],[<bin-limit-6>],[<bin-limit-7>],[<bin-limit-8>]

Parameter	Range	Description
profile-mask	1..63	bitfield
epoch-interval-s	0	off
	1..4294967295
epoch-interval-cnt	0	off
	1..4294967295
epoch-max-bin-cnt	0	off
	1..4294967295
frame-on-new-epoch	0	no
	1	yes
lim-divider	1..4294967295
bin-limit-0	0..99	RH%
	%f
bin-limit-1	0..99	RH%
	%f
bin-limit-2	0..99	RH%
	%f
bin-limit-3	0..99	RH%
	%f
bin-limit-4	0..99	RH%
	%f
bin-limit-5	0..99	RH%
	%f
bin-limit-6	0..99	RH%
	%f
bin-limit-7	0..99	RH%
	%f
bin-limit-8	0..99	RH%
	%f

data ema-cfg

Set exponential moving average (EMA) configuration

Syntax

data ema-cfg <profile-mask>,[<temp-cnt>],[<humid-cnt>],[<bat-cnt>],[<orient-cnt>],[<send-ema-temp>],[<send-ema-humid>],[<send-ema-bat>],[<send-ema-orient>]

Parameter	Range	Description
profile-mask	1..63	bitfield
temp-cnt	1..32766	a = 2 / (temp-cnt + 1)
humid-cnt	1..32766	a = 2 / (humid-cnt + 1)
bat-cnt	1..32766	a = 2 / (bat-cnt + 1)
orient-cnt	1..32766	a = 2 / (orient-cnt + 1)
send-ema-temp	0	no
	1	yes
send-ema-humid	0	no
	1	yes
send-ema-bat	0	no
	1	yes
send-ema-orient	0	no
	1	yes

data activity-cfg

Set activity monitor configuration

Syntax

data activity-cfg <profile-mask>,[<mode>],[<level1-th>],[<level2-th>],[<en-led>]

Parameter	Range	Description
profile-mask	1..63	bitfield
mode	0	off
	1	single
	2	dual
level1-th	1..63
level2-th	1..63
en-led	0	off
	1	on

data acc-cfg

Set accelerometer configuration

Syntax

data acc-cfg <profile-mask>,[<full-scale>],[<en-impact-x>],[<en-impact-y>],[<en-impact-z>],[<impact-th>],[<impact-dur>],[<en-ff>],[<ff-th>],[<ff-dur>],[<data-rate>],[<filter>],[<lp-mode>],[<low-noise>]

Parameter	Range	Description
profile-mask	1..63	bitfield
full-scale	0	2G
	1	4G
	2	8G
	3	16G
en-impact-x	0	off
	1	on
en-impact-y	0	off
	1	on
en-impact-z	0	off
	1	on
impact-th	1..63	impact-th * full-scale / 64
impact-dur	0..3
en-ff	0	off
	1	on
ff-th	0..7
ff-dur	0..63
data-rate	2	Hz
	13
	25
	50
	100
	200
filter	2	cutoff = data-rate/filter
	4
	10
	20
lp-mode	0..3
low-noise	0	no
	1	yes

data orient-cfg

Set orientation sense configuration

Syntax

data orient-cfg <profile-mask>,[<enable>],[<max-1G-offset>],[<poll-interval-s>],[<ref-1-x>],[<ref-1-y>],[<ref-1-z>],[<ref-2-x>],[<ref-2-y>],[<ref-2-z>],[<ref-3-x>],[<ref-3-y>],[<ref-3-z>]

Parameter	Range	Description
profile-mask	1..63	bitfield
enable	0	off
	1	on
max-1G-offset	1..20
poll-interval-s	1..4294967295
ref-1-x	-32768..32767
ref-1-y	-32768..32767
ref-1-z	-32768..32767
ref-2-x	-32768..32767
ref-2-y	-32768..32767
ref-2-z	-32768..32767
ref-3-x	-32768..32767
ref-3-y	-32768..32767
ref-3-z	-32768..32767

data event-cfg

Set event storage configuration

Syntax

data event-cfg <profile-mask>,[<max-count>],[<send-th>],[<discard>],[<send-all>]

Parameter	Range	Description
profile-mask	1..63	bitfield
max-count	0	disabled
	1..100
send-th	0..65535	if count >= send-th: send(device-events); 0 sends on every event
discard	0	oldest (if no free space)
	1	newest
send-all	0	off (send remaining events after device-events frame)
	1	on

data erase-events

Erase <num-oldest> events if provided, otherwise all

Syntax

data erase-events [<num-oldest>]

Parameter	Range	Description
num-oldest	0..65535

data del-rule

Delete <rule-num> rules if provided, otherwise delete all

Syntax

data del-rule [<rule-num>]

Parameter	Range	Description
rule-num	0..31

data set-rule

Set data rule <rule-num>

Syntax

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>]

Parameter	Range	Description
rule-num	0..31
test-expr	test expression
input-expr	input expression
switch-profile	0..5
make-event-0	variable-type
make-event-1	variable-type
make-event-2	variable-type
make-event-3	variable-type
send-frame-0	frame-type
send-frame-1	frame-type
send-frame-2	frame-type
send-frame-3	frame-type
clr-timer-mask	0..15	bit0=timer_1 bit1=timer_2 bit2=timer_3 bit3=timer_4

data timer

Set user timer value

Syntax

data timer [<timer_1>],[<timer_2>],[<timer_3>],[<timer_4>]

Parameter	Range	Description
timer_1	0..4294967295	timer_1
timer_2	0..4294967295	timer_2
timer_3	0..4294967295	timer_3
timer_4	0..4294967295	timer_4

data activity-cal

Run activity monitor calibration and apply result to profiles

Syntax

data activity-cal <profile-mask>,<cal-level>,<cal-led>

Parameter	Range	Description
profile-mask	1..63	bitfield
cal-level	1	level-one
	2	level-two
cal-led	0	no
	1	yes

Data Frames

Frames are packed into LoRaWAN uplinks as described in Uplink Messages. Configuration export frames 25-30 are described in Advanced Operations.

ID	Size [B]	Name	Data Fields
1	5	current-state	temperature, humidity, mag_sw_cnt_u8, major_axis_orientation, activity_state, free_fall_evnt, impact_evnt, pending_evnt
2	variable	device-events	event-list
3	11	temp-histogram	temp_histo_epoch, temp_histo_bin[10]
4	11	humid-histogram	humid_histo_epoch, humid_histo_bin[10]
5	3	device-orientation	orientation_x, orientation_y, orientation_z
6	9	full-activity	activity_state, activity_s, high_activity_s
7	8	motion-events	impact_cnt, free_fall_cnt
8	8	mag-switch	mag_sw_cnt, mag_switch_ts
9	8	impact-count	impact_cnt_u16, impact_cnt_x_u16, impact_cnt_y_u16, impact_cnt_z_u16
10	2	last-temp	temperature
11	2	ema-temp	temperature_ema
12	1	last-humid	humidity
13	1	ema-humid	humidity_ema
14	5	activity	activity_state, total_activity_s
20	8	dev-time	uptime_s, unix_time
21	2	dev-health	battery_mv
22	11	version	version_pid, version_maj, version_min, version_rev, version_hash[6]
23	11	serial-number	serial_number[11]
24	10	cfg-state	cfg_app_crc, cfg_net_crc, cfg_frames_crc, cfg_data_crc, cfg_rules_crc
25	variable	full-cfg	content-offset, content-final, content-len, content-binary-blob
26	variable	app-cfg	content-offset, content-final, content-len, content-binary-blob
27	variable	net-cfg	content-offset, content-final, content-len, content-binary-blob
28	variable	frame-cfg	content-offset, content-final, content-len, content-binary-blob
29	variable	data-cfg	content-offset, content-final, content-len, content-binary-blob
30	variable	rules-cfg	content-offset, content-final, content-len, content-binary-blob

User Variables

ID	Size [B]	Encoding	Name	Description
0	1	u8	profile	current data profile (0..5)
1	4	u32	profile_etm	elapsed time [s] since last profile switch
2	4	u32	daytime_tm	seconds since midnight 00:00 GMT or 0 if unknown
3	4	u32	unix_time	current UNIX time or device uptime if unknown
4	4	u32	net_frame_etm	elapsed time since last network uplink
5	1	bool	net_joined_flag	network join state
6	1	u8	net_class	currently selected LoRaWAN class
7	1	u8	net_region	currently used LoRaWAN region code
8	2	f8.8	temperature	last measured temperature
9	2	f8.8	temperature_ema	EMA of measured temperature
10	1	u8	humidity	last measured humidity
11	1	u8	humidity_ema	EMA of measured humidity
12	4	u32	mag_sw_cnt	magnetic switch state change counter
13	4	u32	mag_sw_etm	elapsed time since last magnetic switch change [s]
14	1	bool	mag_sw_flag	current state of magnetic switch
15	1	activity	activity_state	current device activity state
16	4	u32	activity_s	low activity (level 1) state counter [s]
17	4	u32	high_activity_s	high activity (level 2) state counter [s]
18	1	orient	major_axis_orientation	coarse device orientation
19	4	u32	impact_cnt_x	X axis impact event counter
20	4	u32	impact_cnt_y	Y axis impact event counter
21	4	u32	impact_cnt_z	Z axis impact event counter
22	4	u32	impact_cnt	impact event counter
23	1	bool	impact_evnt	impact event flag, cleared by current-state, motion-events, impact-count frames
24	4	u32	impact_etm	elapsed time since last impact event [s]
25	4	u32	free_fall_cnt	free-fall event counter
26	1	bool	free_fall_evnt	free-fall event flag, cleared by current-state, motion-events frames
27	4	u32	free_fall_etm	elapsed time since last free-fall event [s]
28	1	u8	angle_1	angle between current orientation and user ref-1 vector, see data orient-cfg
29	1	u8	angle_2	angle between current orientation and user ref-2 vector, see data orient-cfg
30	1	u8	angle_3	angle between current orientation and user ref-3 vector, see data orient-cfg
31	1	u8	angle_ema	angle between current orientation and EMA of device orientation
32	2	u16	battery_mv	last measured battery voltage [mV]
33	2	u16	battery_mv_ema	EMA of battery voltage [mV]
34	2	u16	meta_rule_id	special event action value: emits rule number as event code 100 + rule ID
35	4	u32	timer_1	user timer elapsed time [s], reset by rule action or data timer
36	4	u32	timer_2	user timer elapsed time [s], reset by rule action or data timer
37	4	u32	timer_3	user timer elapsed time [s], reset by rule action or data timer
38	4	u32	timer_4	user timer elapsed time [s], reset by rule action or data timer
39	4	u32	activity_state_etm	time since activity_state state change [s]

Frame Data Fields

Size [B]	Encoding	Name	Description
1	u8	mag_sw_cnt_u8	LSB of internal magnet switch counter mag_sw_cnt
1/8	bool	pending_evnt	indicates device has stored events
0		event-list	variable length list of: event time stamp, code and optional value
1	u8	temp_histo_epoch	temperature histogram epoch number
10	u8[10]	temp_histo_bin[10]	temperature histogram bin counter values
1	u8	humid_histo_epoch	humidity histogram epoch number
10	u8[10]	humid_histo_bin[10]	humidity histogram bin counter values
1	i8	orientation_x	device orientation normal vector X axis
1	i8	orientation_y	device orientation normal vector Y axis
1	i8	orientation_z	device orientation normal vector Z axis
4	u32	mag_switch_ts	time stamp of last time magnetic switch state change
2	u16	impact_cnt_u16	impact event counter
2	u16	impact_cnt_x_u16	X axis impact event counter
2	u16	impact_cnt_y_u16	Y axis impact event counter
2	u16	impact_cnt_z_u16	Z axis impact event counter
4	u32	total_activity_s	total activity state time (level 1 + level 2)
4	u32	uptime_s	device FW uptime
2	u16	version_pid	TG-LR82:0x0000, TG-LR92:0x0001
1	u8	version_maj	FW version major number
1	u8	version_min	FW version minor number
1	u8	version_rev	FW version patch number
6	u8[6]	version_hash[6]	FW version hash
11	u8[11]	serial_number[11]	last 11 characters of device serial number
2	u16	cfg_app_crc	app & mag configuration group 16 bit checksum
2	u16	cfg_net_crc	net configuration group 16 bit checksum
2	u16	cfg_frames_crc	frame configuration group 16 bit checksum
2	u16	cfg_data_crc	data configuration group 16 bit checksum
2	u16	cfg_rules_crc	data rule configuration 16 bit checksum
1/8	bool	content-final	flag indicating last chunk of content
15/8	u15	content-offset	byte offset of content data
1	u8	content-len	length of content
0		content-binary-blob	binary data of content chunk

Example Configurations

The examples below are downlink configuration scripts and assume the device is joined. Most examples use profile 5, which is empty by default, so existing profile settings remain unchanged.

Temperature and Humidity Reporting

Configure profile 5 to report temperature and humidity every 15 minutes and battery voltage every 6 hours:

data poll-cfg 32,900,0,0,0,0,0,0,21600
frame set-cfg 32,900,0,0,current-state
frame set-cfg 32,21600,0,0,dev-health
app profile 5,1

The current-state frame carries temperature, humidity, and the remaining device state fields. Battery voltage is sent in the dev-health frame. Profile 5 is empty by default, so orientation and activity monitoring are not needed.

Door/Window Switch

Use profile 5. The device sends current-state every 6 hours and reports immediately when the magnet switch changes state:

mag cfg 600,1,1
frame set-cfg 32,21600,0,0,current-state
data del-rule
data set-rule 0,mag_sw_etm < 2,,,,,,,current-state,mag-switch
app profile 5,1

mag cfg 600,1,1 enables PIN protection for normal magnet commands with a 600-second PIN-mode timeout and selects pulse LED blink mode. Magnet switch events continue to work normally; the PIN is supplied with the device.

The rule uses the elapsed time since the last magnet switch change, so either opening or closing triggers current-state and mag-switch. The latter contains the full counter and last-change timestamp. Bit 0 of mag_sw_cnt_u8 is the current switch state.

Threshold Alarm With Cooldown

Use profile 5. Rule 0 is a five-minute cooldown gate. Rule 1 sends an alarm and resets the gate when temperature exceeds 30 C. The event contains both the temperature value and the rule ID:

data poll-cfg 32,30
data event-cfg 32,20,0,0,1
data timer 300
data del-rule
data set-rule 0,timer_1 >= 300
data set-rule 1,temperature > 30,&0,,temperature,meta_rule_id,,,current-state,,,,1
app profile 5,1

The timer is preset so the first alarm can trigger immediately. After each alarm, timer_1 is reset and the gate closes for five minutes. The expected uplink is current-state plus a device-events frame containing the temperature and data_rule 1.

Impact and Free Fall Profile Switch

Use profile 5 and configure impact and free-fall detection for it. The app profile 5,1 command at the end activates profile 5 and makes it the default:

data acc-cfg 32,0,1,1,1,8,0,1,7,0,13,2,0,1
data del-rule
data set-rule 0,impact_etm < 20,,,meta_rule_id,,,,impact-count
data set-rule 1,free_fall_etm < 15,,,meta_rule_id,,,,motion-events
app profile 5,1

The expected uplink is impact-count or motion-events plus a device-events frame that identifies rule 0 or 1.

warning

Impact and free-fall detection cannot be used while Activity Monitor is enabled.

Orientation Change Event

Use the last profile, profile 5, and orientation EMA; no reference vectors are needed. A change of at least 20 degrees relative to the orientation EMA generates an event:

data orient-cfg 32,1,2,3
data ema-cfg 32,6,6,6,20
data del-rule
data set-rule 0,angle_ema >= 20,,,angle_ema,meta_rule_id,,,device-orientation
app profile 5,1

The expected uplink is device-orientation plus a device-events frame with the measured angle_ema and data_rule 1. orient-cnt 20 sets the EMA time constant to approximately 30 seconds at the 3-second orientation polling interval. The example makes profile 5 the default.

Magnet-Only Setup

Use case: prepare a TG-LR device for a door/window installation without any downlinks. The device starts in SHUTDOWN, so the settings are applied first and the device is activated last.

Magnet-only setup for profile 2

Step	Sequence	Action
1	4-3-9	Disable the secondary band (2.4 GHz). The device will use the 1 GHz band only.
2	4-1-3	Switch to profile 2 (Magnet Switch) and make it the default.
3	2	Activate the device and start it in RUN mode. The device restarts and joins the network.

After the device joins, it uses profile 2 by default and sends current-state, mag-switch, and device-events every 60 minutes. A mag_sw_cnt event is generated when the magnet has been removed for at least 20 seconds. The secondary band remains disabled and profile 2 remains the default after reboot.

Known Issues

Issue IDs are internal support references. The description and workaround are the user-facing contract.

ID	FW	Description
LORA-275	2.0.0	No timeout changing credentials with secondary band disabled.
LORA-276	2.0.0	Incorrect credential change command timeout.
LORA-279	2.0.0	Activity calibration with orientation enabled causes fault.
LORA-281	2.0.0 - 2.0.1	New ADR configuration is not applied until device rejoins or restarts.
LORA-282	2.0.0 - 2.0.1	Only DR0 works as a configured fixed data rate.

LORA-275

Description: If credential changes are initiated with secondary band disabled - device will not timeout join. Device will be stuck attempting join until either it succeeds or is restarted.

Workaround: If new credentials are invalid restart device physically with magnet switch command.

LORA-276

Description: When lora cred is executed device will timeout join procedure on next join attempt based on total uptime instead of command execution time. If uptime is longer than confirm-timeout-s parameter device will timeout exactly after single failed join attempt.

Workaround: Issue device reset command app reset before attempting to change credentials. Or manually retry credential change multiple times.

LORA-279

Description: If activity calibration is performed while orientation detection is enabled device may fault and restart.

Workaround: Disable orientation detection with data orient-cfg before performing activity calibration and re-enable after.

LORA-281

Description: Changing the ADR setting with lora adr-cfg while the device is joined may not take effect until the device rejoins or restarts. Uplinks may continue using the previous ADR mode and data rate.

Workaround: Reset the device with app reset after changing the ADR setting.

LORA-282

Description: When network ADR is disabled, only DR0 works as a configured fixed data rate. Configuring any other fixed data rate may not take effect.

Workaround: Enable network ADR with lora adr-cfg.

Related Documents

No	Name
1	TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification
2	Guidelines for 64-bit Global Identifier (EUI-64)

Advanced Operations

The operations below are public but not required for normal end-device operation.

Manual Sampling

data sample forces one temperature, humidity, battery, and orientation sampling cycle. Forced samples update the last measured values and event flags, but do not update EMA or histogram counters except for the first sample. Use it for diagnostics or to refresh data before a manual read.

Manual Histogram Epoch

data next-epoch immediately starts a new temperature and humidity histogram epoch. Use data next-epoch temp or data next-epoch humid to reset only one histogram. The next histogram frame reports the new epoch number.

Configuration Export Frames

Frames full-cfg, app-cfg, net-cfg, frame-cfg, data-cfg, and rules-cfg carry fragmented configuration data. They are intended for configuration backup and verification tooling, not for normal telemetry. The cfg-state frame is the normal automatic checksum response after a configuration downlink.

Optional Evaluation Stack

telemetry_hub.zip contains optional Grafana and Influx docker services for device capability evaluation. It is not required for device operation. Follow the instructions included in the archive.