TG-LR

• Quickstart Guide

• Functionality

  • LoRaWAN

  • Uplink Messages

  • Telemetry

  • Magnet Switch

  • Command Encoding

  • Device Commands

  • Data Frames

  • User Variables

  • Frame Data Fields

  • Known Issues

• Related Documents

Quickstart Guide

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

• Optionally deploy Grafana + Influx (telemetry_hub.zip) docker services for device capability evaluation.

• Activate device by holding magnet near reed switch and wait for 2x LED blinks (~1.5s).

Functionality

Table 1 Models

Table 2 Bands

Table 3 Operating modes

Table 4 Supported regions

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.

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

Once device has joined network optional periodic link check can be performed. Link check can be configured specifically for each band using lora link-chk. If link check fails device leaves network and restarts join procedure.

Time Synchronization

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.

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 know 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.

Uplink Messages

Each LoRaWAN uplink message is formed by placing pending Data Frames ID and its contents in FPort and FRMPayload fields. All pending frames are packed in ascending order and differential encoding is used for IDs.

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.

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

Table 5 Default profile configuration

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

Fig. 1 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.

Table 6 major_axis_orientation description

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)

Table 7 activity_state description

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.

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.

Table 8 activity_state dual mode state transitions

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.

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

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

• Send commands:

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

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

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

• 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:

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

• Send commands:

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

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

• Place device in environment for level 2 calibration.

• Send commands to calibrate level 2:

  data activity-cal 1,2,1

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

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

• If calibration results are acceptable send command to disable LED:

  data activity-cfg 1,,,,0

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.

Data Rules

Up to 32 custom user rules are configurable using commands: data set-rule, data del-rule. Rules have test expression, optional input rules and actions to perform.

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

Test Expression

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

Example:

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

Same rules can be given using User Variables numeric IDs:

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

Input Expression

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

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

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

Actions

Rule Test Expression evaluated value represents data rule local state. Local state evaluated with optional input rules represents combined state.

If combined state changes to TRUE state optional rule actions are performed: profile switching, event generation, frame scheduling, user timer reset.

If <switch-profile> parameter is given, current profile will be changed. 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:

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

Up to 4 different events can be generated per rule:

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

Events

Actions can optionally generate events. Events are time stamped User Variables that are sent in device-events frame. Event storage can be configured using data event-cfg command. If device has received absolute time using Time Synchronization events will have POSIX time stamp. This allows collecting specific historic data to report later. Event uplink can be triggered periodically, based on some rule or manually using downlink command.

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.

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.

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.

Table 9 Magnet switch commands

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.

tg-lrx2-utils.zip or install with pip install tg-lrx2-utils

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 --dev-desc ./tg-lrx2-2.0-desc.yml --max-len=50 --out ./lora-pub.yml

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..."

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

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 parameters has valid input range and format. Some parameters allow only specific choice between parameters or 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.

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

Known Issues

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.

Related Documents