MikroTik KNOT (Bluetooth)

The KNOT is MikroTik's IoT gateway: a small RouterOS box with a Bluetooth scanner, connected by Ethernet, Wi-Fi or its cellular modem. It does not speak Omaya's format out of the box — RouterOS has the pieces (a Bluetooth scanner and an MQTT client), and a short script you paste in joins them: every two seconds it takes what the scanner heard and publishes it to Omaya.

It hears any Bluetooth tag, beacon or sensor, including MikroTik's own TG-BT5 tags.

What you do in Omaya

1. Create the connector and copy its host and topic — A
2. Register the gateway by its MAC — B
3. Place it on the floor plan and do the calibration walk — C
4. Register the tags and sensors it will hear — D
5. Check it end to end — E

Before you start

• Where it will hang — read gateway placement first.
• The KNOT on your network, by Ethernet, Wi-Fi or SIM, as MikroTik's quick-start guide describes, and reachable in WinBox or WebFig (its web page).
• RouterOS 7.11 or newer with the iot package — check under System → Packages. If iot is not listed, install it from the Extra packages for your exact RouterOS version on MikroTik's download page, then reboot.
• The connector topic from step A, and the KNOT's MAC: the MAC of its Ethernet port, shown under Interfaces on ether1 (and normally on the label).

On the gateway

All of this is in WinBox or WebFig. Four settings, one script and one schedule.

1. The Bluetooth scanner

IoT → Bluetooth → Scanners, open the scanner and set:

Setting	Value	Why
Disabled	no
Type	passive	Enough for nearly every tag; see the note below for buttons that put their battery in a scan response
Filter Duplicates	keep-unique	Keeps each different advertisement and drops exact repeats, so a button press is never overwritten by the idle frames around it, and the KNOT's 1,024-entry list does not overflow between sends
Filter Policy	default
PHY	1M	CODED only for long-range tags that are configured for it
Interval / Window	leave at 10 ms / 10 ms	Equal values mean the radio listens all the time

Do not set a signal-strength or address filter on the KNOT. Positioning compares what every gateway hears, weak readings included; a gateway that filters is deciding on Omaya's behalf which ones matter.

2. The MQTT broker

IoT → MQTT → Brokers → add:

Field	Enter
Name	omaya — the script refers to it by this name
Address	the Omaya host you sign in to, e.g. omaya.example.com
Port	1883
SSL	no
Client ID	KNOT- followed by the MAC without colons, e.g. KNOT-48A98A010203
Username / Password	blank
Keep Alive	60
Auto Connect	yes

The Client ID must be different on every gateway: the broker keeps one connection per Client ID, and two KNOTs sharing one keep knocking each other off. Omaya also listens on 8883 with SSL; move to it once the gateway works on 1883, since RouterOS may need the certificate authority trusted before an SSL connection succeeds.

3. The script

System → Scripts → add a script named omaya-ble, tick read, write and test under Policy, and paste this as its Source. Change only the topic line, to the topic from your connector:

# Omaya: publish this KNOT's Bluetooth scans in Omaya's gateway format.
:local broker "omaya"
:local topic "omaya/ORGANISATION/TOKEN/generic/ble"
:local perMessage 20

:local gw [/interface ethernet get [find default-name=ether1] mac-address]
:local advs [/iot bluetooth scanners advertisements print detail as-value]
/iot bluetooth scanners advertisements clear

:if ([:len $advs] = 0) do={
  /iot mqtt publish broker=$broker topic=$topic message=("{\"gateway_mac\":\"" . $gw . "\",\"devices\":[]}")
}

:local items ""
:local n 0
:foreach a in=$advs do={
  :local item ("{\"mac\":\"" . ($a->"address") . "\",\"rssi\":" . ($a->"rssi") . ",\"adv_data\":\"" . ($a->"data") . "\",\"timestamp\":" . ([:tonum ($a->"epoch")] / 1000) . "}")
  :if ($n > 0) do={ :set items ($items . ",") }
  :set items ($items . $item)
  :set n ($n + 1)
  :if ($n >= $perMessage) do={
    /iot mqtt publish broker=$broker topic=$topic message=("{\"gateway_mac\":\"" . $gw . "\",\"devices\":[" . $items . "]}")
    :set items ""
    :set n 0
  }
}
:if ($n > 0) do={
  /iot mqtt publish broker=$broker topic=$topic message=("{\"gateway_mac\":\"" . $gw . "\",\"devices\":[" . $items . "]}")
}

What it does, so you can trust it: it reads everything the scanner has heard since the last run, empties the list, and publishes it in batches of 20 — each reading with the tag's MAC, its signal strength, the raw advertisement and the time it was heard. When nothing was heard it still sends an empty message, which is what keeps the gateway online in Omaya while a room is empty.

Select the script and press Run Script once. If the broker is reachable, IoT → MQTT → Brokers now shows it connected.

4. The schedule

System → Scheduler → add:

Field	Enter
Name	omaya-ble
Start Time	startup
Interval	00:00:02
On Event	/system script run omaya-ble

Every two seconds is about what other Bluetooth gateways send at, and keeps each reading well inside the 30 seconds after which Omaya stops using it for positioning. Slower than five seconds and people moving between rooms will be noticeably late.

Buttons that report battery in a scan response

Some buttons (MOKO's, for example) put their battery level in a scan response, which a passive scanner never asks for. Setting the scanner's Type to active makes the KNOT ask; the response then arrives as a reading of its own. Presses and presence work either way.

Your MQTT settings

The script's topic is your connector's topic, character for character. It is built from two values Omaya generated for you:

• Organisation id — the second part. It never changes.
• Connector token — the third part: 16 characters, issued when the connector was created. It is the gateway's password, so treat the topic like one. Rotating it on the connector page stops the old topic at once, and every gateway on that connector then needs the new one in its script.

One topic per connector. Every gateway a customer owns from you publishes to the same topic; the gateway is identified inside the payload, not in the topic.

Type your organisation id, token and the KNOT's MAC — or paste the whole topic from the connector page — to get the topic and Client ID to copy. It works in the page only: nothing you type is sent or saved. The KNOT does not need the subscribe topic the box also shows.

Fill in your gateway's MQTT settings

Paste the topic from your connector page (optional — fills the next two)

Organisation idConnector tokenGateway MACOmaya host

Use SSL/TLS (port 8883)

Host	the Omaya host
Port	1883
SSL/TLS	off
Client Id	KNOT-<gateway-MAC>
Publish topic	omaya/<organisation>/<token>/generic/ble
Subscribe topic	omaya/<organisation>/<token>/generic/cmd/<gateway-MAC>
Username / Password	(blank)

Anything still in <angle brackets> needs your value. Nothing you type here leaves this page.

In Omaya

A. Create the connector

Connectors → IoT Gateway (MQTT) → add:

Field	Choose
Connector Name	e.g. MikroTik KNOTs — HQ
Vendor	Generic / Other
Protocol	BLE (Bluetooth Low Energy)
Active	on

Choose Generic / Other, not Mikrotik: the script sends Omaya's generic gateway format, and the Mikrotik vendor is for Wi-Fi client tables from MikroTik access points. Save, and copy the host and the topic into the broker and the script. The topic looks like omaya/<organisation>/<16-character token>/generic/ble.

B. Register the gateway

Device → Gateway → add, with the KNOT's ether1 MAC, Device Model Mikrotik, and its location, venue and zone. Messages from a gateway Omaya does not know are dropped, so do this before or straight after starting the schedule; one that publishes first is noted and can be registered afterwards.

C. Put it on the floor plan

Place it where it physically hangs, at its real height, and once every gateway on the floor is up, do the calibration walk. A KNOT hears tags differently from a Dusun or a MOKO gateway, so a floor that mixes makes is exactly where the walk earns its keep.

D. Register what it will hear

Under Device → Sensor, add each tag, beacon or sensor with its MAC and Device Model — and a zone for anything fixed to a wall. MikroTik's own tags are in the list as TG-BT5-IN, TG-BT5-HL and TG-BT5-Mini. Bulk Import on Device → Sensor takes a spreadsheet; New sensor types handles a model Omaya does not know yet.

E. Check it

Within a minute the gateway shows online on Device → Gateway, and the tags it hears appear on the Live Monitor and on their own pages.

When it disappoints

The broker never shows connected. The address and port first; then that the KNOT can reach the internet at all (its DNS and default route). With SSL on, go back to 1883 and SSL off to separate the two problems.

Connected, nothing in Omaya. The topic in the script, character by character — a wrong token is dropped silently, by design; paste it into the box above to check its shape. Then the MAC registered under Device → Gateway: it must be ether1's.

The gateway is online but no tags appear. The scanner is disabled, or the tags are not registered under Device → Sensor. In the terminal-free way: IoT → Bluetooth → Advertisements lists what the KNOT is hearing right now — empty means the scanner is off or out of range; full means the tags still need registering.

Two KNOTs keep going offline in turn. They share a Client ID. Give each its own, with its MAC in it.

Tags move between rooms late. The schedule is slower than two seconds, or the script is failing part-way: Log shows any script error, and running it by hand from System → Scripts shows it immediately.

A button's presses arrive but never its battery. It reports battery in a scan response — set the scanner's Type to active (above).