Introduction
In this guide, we will show a quick step-by-step on how you can set up your KNOT to send an e-mail notification, whenever it detects a "triggered" condition reported by the TG-BT5-IN or TG-BT5-OUT tag.
As per tag's guides for iOS and Android, the tags have a built-in accelerometer that is able to detect free-falling, wakeup/movement, and tilted states. When the tag is set up to broadcast MikroTik format payloads and accelerometer triggers are enabled (using the MikroTik Beacon Manager app) → the tag will instantly broadcast an advertising payload/report whenever the trigger is going to be detected.
For iOS, the trigger setting looks like this (in a disabled state/default settings):
To active trigger detection, just enable the corresponding "checkbox".
After the Bluetooth payload is broadcasted by the tag → the payload's 21st octet will indicate which exact trigger was detected. You can view the payloads under the IoT>Bluetooth>Advertisng reports tab:
As per the screenshot above, the 21st octet is "04", which indicates, that the payload was sent when a freefalling condition was detected by the tag (these payloads were broadcasted when we "accidentally" dropped or threw the tag).
You can find more information about MikroTik format octet values by following the link.
Once everything is configured the following is going to happen:
- The KNOT will run a script on a schedule.
- The script will "read/scan" the payloads that are shown in the IoT>Bluetooth>Advertising reports tab.
- If the stored/captured payload's 21st octet value equals to any "triggered" value → email notification is going to be sent.
In other words, when the KNOT scans through the payloads and finds one where the 21st octet indicates that the trigger was activated → you will get an email notification that the trigger was detected.
TG-BT5 tag configuration
In this specific example, we need to set up our tags to work in the MikroTik format. In the MikroTik format, the 21st octet of each payload will indicate the reason it was triggered.
You can find a manual on how to enable the triggers by following the iOS and/or Android guides ("Advertisement"/Beacon settings sections).
To easier "activate" the trigger, we can also alter the trigger's settings as per the iOS and/or Android guides (Free Fall Threshold and Duration sections). For the purpose of the test and to, basically, just "trigger" the detection much faster, we can change the "Free Fall Duration" parameter to "0" seconds (this will make sure that any acceleration that is within the threshold on all axis will be instantly detected as a "freefalling" event).
RouterOS configuration
note: iot package is required. You can get it from our download page - under "Extra packages".
The configuration can be completed in 4 steps:
- enable scanner (and, preferably, confirm that the tag is broadcasting payloads when the trigger is detected);
- set up an email server;
- import the script (and alter a few script lines depending on the requirement);
- set up the scheduler.
IoT>Bluetooth>Scanners
Go to the IoT>Bluetooth>Scanners tab and make sure that it is enabled:
Go to the Advertising reports tab and filter the list using the MAC address filtering option (you can find the MAC address of the MikroTik tag printed on the label on the tag itself).
Try to "trigger" the configured detection and confirm it by checking the 21 octet's value.
In our example, we configured the "freefalling" detection for our tag and we dropped it. We got reports from the tag indicating the "falling" state (21st octet = 04):
We have confirmed, that the tag is reporting the trigger properly.
Tools>Email
Navigate to the Tools>Email section and set up an email server of your choice.
You can find our Email configuration example by following the link. We will be using shown GMAIL example in this guide.
Try sending a test email to make sure that it is set up correctly.
System>Scripts
Option (a)
Navigate to System>Scripts menu and add a new script there.
You can copy the script below. Copy the script below into a "notepad" and copy it again into the script "Source:" field.
# Input MAC address of the tag within ""
:local addressRegex "2C:C8:1B:E2:15:29"#enter the subject for the email within the ""
:local emailsubject "RouterOS report!"#enter the email address wthin the ""
:local emailaddress "YOUR_EMAIL@gmail.com"#Script:
################################## Bluetooth ##################################
:local flagStr do={
:local str "":if ($1 & 0x01) do={ :set $str " switch" }
:if ($1 & 0x02) do={ :set $str "$str tilt" }
:if ($1 & 0x04) do={ :set $str "$str free_fall" }
:if ($1 & 0x08) do={ :set $str "$str impact_x" }
:if ($1 & 0x10) do={ :set $str "$str impact_y" }
:if ($1 & 0x20) do={ :set $str "$str impact_z" }:if ([:len $str] = 0) do={ :return "" }
:return [:pick $str 1 [:len $str]]
}:local triggernameF "free_fall"
:local triggernameT "tilt"
:local triggernameX "impact_x"
:local triggernameY "impact_y"
:local triggernameZ "impact_z"
:local triggernameS "switch"# Find fresh Bluetooth advertisements
:global btOldestAdvertisementTimestamp
:if ([:typeof $btOldestAdvertisementTimestamp] = "nothing") do={
# First time this script has been run since booting, need to initialize
# persistent variables
:set $btOldestAdvertisementTimestamp 0
}
:local advertisements [/iot bluetooth scanners advertisements print detail \
as-value where \
epoch > $btOldestAdvertisementTimestamp and \
address ~ $addressRegex
]
:local advCount 0
:local lastAdvTimestamp 0
:local triggerlist "":local triggerF
:local triggerT
:local triggerX
:local triggerY
:local triggerZ
:local triggerS:local messageF ""
:local messageT ""
:local messageX ""
:local messageY ""
:local messageZ ""
:local messageS "":local 21st ""
:foreach adv in=$advertisements do={
:local address ($adv->"address")
:local rssi ($adv->"rssi")
:local epoch ($adv->"epoch")
:local rtime ($adv->"time")
:local ad ($adv->"data")
:local flags [:tonum "0x$[:pick $ad 40 42]"]
:local obj "$[$flagStr $flags]":set $advCount ($advCount + 1)
:set $lastAdvTimestamp $epoch
:set $triggerlist "$triggerlist$obj":set triggerF [:pick $triggerlist ([find $triggerlist "free_fall"]-0) ([find $triggerlist "free_fall"]+9)]
:if ($triggerF=$triggernameF) do={:set messageF "$triggernameF";:set 21st "not00";}
:set triggerT [:pick $triggerlist ([find $triggerlist "tilt"]-0) ([find $triggerlist "tilt"]+4)]
:if ($triggerT=$triggernameT) do={:set messageT "$triggernameT";:set 21st "not00";}
:set triggerX [:pick $triggerlist ([find $triggerlist "impact_x"]-0) ([find $triggerlist "impact_x"]+8)]
:if ($triggerX=$triggernameX) do={:set messageX "$triggernameX";:set 21st "not00";}
:set triggerY [:pick $triggerlist ([find $triggerlist "impact_y"]-0) ([find $triggerlist "impact_y"]+8)]
:if ($triggerY=$triggernameY) do={:set messageY "$triggernameY";:set 21st "not00";}
:set triggerZ [:pick $triggerlist ([find $triggerlist "impact_z"]-0) ([find $triggerlist "impact_z"]+8)]
:if ($triggerZ=$triggernameZ) do={:set messageZ "$triggernameZ";:set 21st "not00";}
:set triggerS [:pick $triggerlist ([find $triggerlist "switch"]-0) ([find $triggerlist "switch"]+6)]
:if ($triggerS=$triggernameS) do={:set messageS "$triggernameS";:set 21st "not00";}}
:if ($advCount > 0) do={
:set $btOldestAdvertisementTimestamp $lastAdvTimestamp
}#Message structure:
:local message "$messageF
$messageT
$messageX
$messageY
$messageZ
$messageS
--trigger(s) reported by the tag!":if ($21st="not00") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$message"} else={:put "21st octet does not have triggers detected!"}
The following 3 lines need to be taken into account:
:local addressRegex "2C:C8:1B:E2:15:29"
line, where we input the MAC address of the tag that you wish to monitor;
:local emailsubject "RouterOS report!"
line, where you can alter the subject for the email;
:local emailaddress "YOUR_EMAIL@gmail.com"
the email address line, where you need to input the email address. To where do you want to send the report?
You can also change the structure of the e-mail message using the lines:
#Message structure:
:local message "$messageF
$messageT
$messageX
$messageY
$messageZ
$messageS
--trigger(s) reported by the tag!"
Name the script however you like, for example, triggernotification. Click on Apply and OK.
Additionally
In this example, we are specifically showcasing an e-mail notification scenario. But! in case you want to use other methods for sending a notification, you can just alter the line below:
:if ($21st="not00") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$message"}
You can change the "do={/tool e-mail..." part of the line to, for example, "do={/tool fetch..." or "do={/iot mqtt publish...". That way, you can send out an HTTP post or MQTT publish message instead.
If you would like to get a phone notification when the trigger is detected, you can also utilize IFTTT services (HTTP post to IFTTT webhook) as described in our other guide over here.
You can run the script manually via the command "/system script run triggernotification" or by clicking on the "Run Script" button under the Script List section.
You should make sure that the e-mail notification was received after manually initiating the script.
When the script (a) is initiated, RouterOS is going to check every received/stored Bluetooth payload, and if any trigger is found in the payload's list → an e-mail message is structured and sent. This e-mail message will simply indicate which triggers were detected in the list with no additional information.
Option (b)
Script (a) will send a message indicating whether all possible triggers were
#User configuration:
#input the tag's mac address that you wish to monitor within the ""
:local addressRegex "2C:C8:1B:4B:BB:0A"
#enter trigger value, for example "04" for freefalling trigger and "02" for tilt trigger detection
:local triggervalueF "04"
:local triggervalueT "02"
:local triggervalueX "08"
:local triggervalueXY "18"
:local triggervalueXZ "28"
:local triggervalueXYZ "38"
:local triggervalueY "10"
:local triggervalueYZ "30"
:local triggervalueZ "20"
#name the trigger accordingly
:local triggernameF "freefalling"
:local triggernameT "tilt"
:local triggernameX "Xmovement"
:local triggernameXY "XYmovement"
:local triggernameXZ "XZmovement"
:local triggernameXYZ "XYZmovement"
:local triggernameY "Ymovement"
:local triggernameYZ "YZmovement"
:local triggernameZ "Zmovement"
#enter the message for the email body that you wish to receive within the ""
:local emailmessageF "Our tag fell down!"
:local emailmessageT "Our tag tilted!"
:local emailmessageX "Our tag moved against X axis!"
:local emailmessageXY "Our tag moved against X and Y axis!"
:local emailmessageXZ "Our tag moved against X and Z axis!"
:local emailmessageXYZ "Our tag moved against X,Y and Z axis!"
:local emailmessageY "Our tag moved against Y axis!"
:local emailmessageYZ "Our tag moved against Y and Z axis!"
:local emailmessageZ "Our tag moved against Z axis!"#enter the subject for the email within the ""
:local emailsubject "RouterOS report!"#enter the email address wthin the ""
:local emailaddress "YOUR_EMAIL@gmail.com"###Bluetooth scanner
:local triggerF
:local triggerT
:local triggerX
:local triggerXY
:local triggerXZ
:local triggerXYZ
:local triggerY
:local triggerYZ
:local triggerZ:put ("[*] Gathering Bluetooth info...")
:global btOldestAdvertisementTimestamp
:if ([:typeof $btOldestAdvertisementTimestamp] = "nothing") do={:set $btOldestAdvertisementTimestamp 0}
:local btProcessingStart [/system clock get time]
:local advertisements [/iot bluetooth scanners advertisements print detail \
as-value where \
epoch > $btOldestAdvertisementTimestamp and \
address ~ $addressRegex]
:local advCount 0
:local lastAdvTimestamp 0:foreach adv in=$advertisements do={
:local address ($adv->"address")
:local ad ($adv->"data")
:local ts ($adv->"epoch")
:local trig [:pick ($adv->"data") 40 42]
:set $advCount ($advCount + 1)
:set $lastAdvTimestamp $ts
:if ($trig="$triggervalueF") do={:set triggerF "$triggernameF"}
:if ($trig="$triggervalueT") do={:set triggerT "$triggernameT"}
:if ($trig="$triggervalueX") do={:set triggerX "$triggernameX"}
:if ($trig="$triggervalueXY") do={:set triggerXY "$triggernameXY"}
:if ($trig="$triggervalueXZ") do={:set triggerXZ "$triggernameXZ"}
:if ($trig="$triggervalueXYZ") do={:set triggerXYZ "$triggernameXYZ"}
:if ($trig="$triggervalueY") do={:set triggerY "$triggernameY"}
:if ($trig="$triggervalueYZ") do={:set triggerYZ "$triggernameYZ"}
:if ($trig="$triggervalueZ") do={:set triggerZ "$triggernameZ"}:if ($advCount > 0) do={:set $btOldestAdvertisementTimestamp $lastAdvTimestamp}}
:put ("[*] Found $advCount new advertisements \
(processing time: $[([/system clock get time] - $btProcessingStart)])")###Result
:if ($triggerF="$triggernameF") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageF"}
:if ($triggerT="$triggernameT") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageT"}
:if ($triggerX="$triggernameX") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageX"}
:if ($triggerXY="$triggernameXY") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageXY"}
:if ($triggerXZ="$triggernameXZ") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageXZ"}
:if ($triggerXYZ="$triggernameXYZ") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageXYZ"}
:if ($triggerY="$triggernameY") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageY"}
:if ($triggerYZ="$triggernameYZ") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageYZ"}
:if ($triggerZ="$triggernameZ") do={/tool e-mail send to=$emailaddress subject="$emailsubject" body="$emailmessageZ"}
note
System>Scheduler
To automate the process add a new scheduler under the System>Scheduler tab:
Type in "/system script run triggernotification" under the "On Event:" field and set up an interval with which you wish to run the script to check/scan advertising reports (to, for example, 10 seconds).
Click on Apply and OK.
Result verification
a) Confirm that the tag broadcasts advertising reports and that the tag's triggers get detected:
b) Confirm that your email server is set up correctly and that you are able to send emails from the KNOT (RouterOS).
c) After you manually run the script or apply a scheduler to the script, an email notification should go through, like so:
