Badge settings and commands

Omaya can change a badge's settings and tell it to do things, from the badge's page in Omaya, without anyone holding the badge or opening the MKLoRa app. Today this works for the MOKO PS101-M badge (setting it up); other devices can be added later the same way.

You can:

• read and change every setting: when the badge reports, how it finds its position, what the red button does, man-down, the buzzer and lights, Bluetooth scanning, and its network connection;
• send it actions: locate now, find (make it beep), start or stop an alarm, restart, power off, factory reset, upload or clear the reports it stored, update its firmware;
• let a rule do it: locate a badge, sound it, or stop its alarm when something happens.

A command only reaches the badge if the badge's Subscribe topic is exactly the command topic shown at the top of Badge settings. The answer comes back the same way the badge's reports do, so a badge that reports to Omaya can always answer.

Where to find it

Open Device → Sensor, select the badge's row and press View. A badge that Omaya can command has a Badge settings card with three buttons: Locate now, Find (beep) and Badge settings, which opens the full panel.

At the top of the panel, Commands are sent to shows the badge's command topic: the address on Omaya's MQTT broker where Omaya sends this badge its commands. The badge only hears them if its Subscribe topic (MKLoRa app → Network Settings) is exactly this text. Copy it with the copy button when you set the badge up. Omaya works it out by itself in this order:

1. a topic someone set with Change on this panel (needs the Manage devices permission);
2. from the topic the badge reports on: MOKO's …/send becomes …/receive; an Omaya topic gives omaya/<organisation>/<token>/device/<MAC>/cmd;
3. the same Omaya form, with your organisation's MQTT connector token.

Each badge has its own command topic, so a command for one badge never reaches another.

Reading and changing settings

Settings are grouped in sections. Each section shows the values as the badge last reported them, with when and by whom they were read.

1. Click Read all settings (or Read this section). The badge answers within a few seconds if it is connected; the values fill in as they arrive.
2. Change what you need.
3. Click Save to badge. The status next to the section turns to Sent, waiting, then Done when the badge confirms it, or Failed with the badge's reason.

Save to badge stays greyed out until the section has been read once. The badge replaces a whole section on every save, so Omaya needs the current values of the fields you did not touch.

Passwords (the Bluetooth app password and the MQTT password) are never shown. Leave the field empty to keep the current one; Omaya re-sends it from its last reading, kept encrypted.

What each section does

Section	What you set	Notes
Working mode & reporting	Standby, Timing, Periodic or Motion mode; the report interval of each; the heartbeat; how hard the badge must move to count as moving	MOKO's default is Periodic, every 30 minutes, heartbeat every 12 hours.
How it finds its position	The method for "Locate now"; GPS give-up time and precision; Wi-Fi and Bluetooth scan length and count	GPS only works outdoors. Wi-Fi and Bluetooth "positions" are lists of what the badge heard; Omaya turns them into a room only where anchors are set up.
Alarm button (Alert / SOS)	Alarm type; the press that starts it; how often an SOS reports; how long to hold the button to stop it	Alert: one press, one report, then back to normal. SOS: the badge keeps reporting until the alarm is stopped. Keep "Send an event when it starts" on — Omaya pages from that event.
Man-down	On/off; how long without movement before the alarm; report interval during it	An inactivity timer, not a fall detector. Off by default.
Buzzer, vibration & lights	Alarm sound, vibration strength, each light on or off	A silent buzzer makes Find useless.
Power, battery, clock & Bluetooth	Whether the wearer can switch it off; the low-battery warning; the clock's time zone; the Bluetooth set-up window and its app password; storing reports while offline	Saving the clock sets the badge to Omaya's time. Change MOKO's default app password.
Bluetooth scanning & filters	Which beacons count for a Bluetooth position: signal threshold, MAC list, name list, beacon types	Leave "Which filters apply" on None unless other beacons nearby confuse it.
Network, MQTT & time server	APN and network type; broker, port, topics, security; time server; message format	See the warning below. Omaya reads JSON only: switching the badge to HEX is refused.
Stored data	Upload what the badge stored, pause or resume an upload, clear the store	Clearing cannot be undone.
Firmware & certificates	Update status; firmware update from an address; TLS certificates	Only use files MOKO supplied for the PS101-M.

Network and MQTT settings can disconnect the badge

A wrong broker, port, topic, password, APN or network type cuts the badge off from Omaya, and only the MKLoRa app over Bluetooth, next to the badge, can bring it back. Omaya asks you to type CHANGE MQTT before it sends MQTT settings. The badge keeps using its old MQTT settings until it restarts: read them back, check every value, then Restart.

Actions

Action	What happens	Asks first
Locate now	The badge looks for its position with the "Locate now" method; the position arrives as a normal report a little later (up to the GPS give-up time).	No
Find (beep)	The badge sounds its alarm — buzzer, vibration, red light — for 10 seconds, then Omaya stops it.	Yes
Trigger alarm	Starts the badge's alarm (Alert or SOS, whichever is set), as if the wearer pressed the button.	Yes
Exit alarm	Stops the alarm on the badge, as if the wearer held the SOS button.	No
Open Bluetooth window	The badge advertises for a few minutes so the MKLoRa app can connect without anyone pressing a button.	No
Restart	The badge reboots; it is offline for about a minute.	Yes
Power off	The badge switches off. Nobody can switch it back on from Omaya.	Type POWER OFF
Factory reset	Every setting goes back to MOKO's factory values, including the MQTT settings, so the badge stops reporting to Omaya.	Type FACTORY RESET
Clear stored data	Deletes the reports the badge stored while it had no signal.	Type CLEAR DATA
Update firmware	The badge downloads and installs a firmware file.	Type UPDATE FIRMWARE

The PS101-M has no separate "beep" command, so Find and Sound badge use its alarm. The badge reports that as an alarm starting and ending. Omaya remembers that the alarm came from Omaya, and the Alarm type must be Alert or SOS: with No alarm the badge refuses, and Omaya says so.

Who may do what:

• View devices: see the panel, the values and the history.
• Edit devices: read settings, change everyday settings, send everyday actions.
• Manage devices as well: power off, factory reset, network and MQTT, Bluetooth password, firmware, clearing stored data, and changing the command topic.

Recommended settings

These are starting points. Try them on one badge, then read the badge back to check.

Lone worker

Someone working alone who must be able to call for help, and be found if they cannot.

Setting	Value
Working mode	Periodic, every 10–15 minutes
Positioning method	Bluetooth, then GPS (with anchors indoors); GPS outdoors only
Alarm type	SOS, started with a double click; report every 60 s while it lasts
Man-down	On, after 10–15 minutes without movement
Wearer can switch it off with the buttons	Off
Low-battery warning	On, at 20 %
Rule	Battery low → in-app alert to the supervisor

Patrol guard

A guard walking a route, whose path matters more than a fixed interval.

Setting	Value
Working mode	Motion: report during a trip every 60–120 s, one position at trip end
Positioning method	Bluetooth, then GPS (beacon anchors at the checkpoints)
Alarm type	SOS, double click
Man-down	On, 10 minutes
Rule	Leaves the site geofence at night → Locate badge now, then an alert

Asset on a trolley

The badge rides on equipment rather than a person. Battery life matters most, alarms not at all.

Setting	Value
Working mode	Motion: no reports while still except every 4–12 hours; one position when a trip ends
Positioning method	Bluetooth (indoors, with anchors) or GPS (yards)
Alarm type	No alarm
Man-down	Off
Lights	Most off
Rule	Leaves its geofence → Sound badge so whoever moves it hears it

Rules

A rule can command a badge. In the rule builder, pick one of these actions:

• Locate badge now — the same as the button.
• Sound badge — Find, for the number of seconds you choose in Stop after (seconds): 10 if blank, at most 120, and 0 keeps it sounding until someone stops it.
• Exit badge alarm — stops the alarm.

The badge is the rule's own device — the device of a Device (one tag or sensor) rule, or the device that fired a Label or Geofence (GPS) rule — unless you pick one in Badge. Any other rule — about a Person / asset, a Gateway, a zone, venue or location — must pick the badge, or it cannot be saved (Choose the badge: this rule is not about one device.). Not again for this badge within (seconds) (120 if blank, at least 10) stops one badge being commanded over and over, on top of the rule's own Repeat at most every. A rule cannot power off, reset or reconfigure a badge.

How to tell a command worked

Every command and every answer is in the badge's Command history, with who sent it — a person, or Rule: … for a rule — and the badge's own reason when it refuses.

The Command history at the bottom of the panel lists every command, newest first: when, what, who (a person, or Rule: …), and the result. Done means the badge itself confirmed it. The panel also lists answers the badge sent without Omaya asking — after a change made with the MKLoRa app, for example — marked not from Omaya.

For Locate now, Done means the badge accepted the request. The position follows as a normal report: on the badge's trail, on the map, and in the badge's latest reading.

If the badge is offline

Omaya sends each command once, the moment you click, on Omaya's own broker. It never resends it by itself. What happens next depends on the badge's connection:

• Badge connected: it answers within seconds.
• Badge briefly disconnected, with Clean session off (Network, MQTT & time server): the broker keeps the command for the badge's session and delivers it when the badge reconnects. Omaya's broker keeps such a session for about two hours (its default). If the badge answers after Omaya stopped waiting, the command turns Done (late).
• Badge switched off, out of coverage for longer, or with Clean session on: the command is lost. After about two minutes Omaya marks it No answer. Send it again once the badge reports.

A command is never stored on the broker for the next connection of anyone else, and is never replayed when the badge reconnects later.

Only one command of each kind can wait at a time, because the badge's answer does not say which of two it belongs to. If you click Save twice, the second is refused until the first is answered or runs out of time. A second Read joins the one already waiting.

Sensors that report their own settings

Some sensors cannot take commands from Omaya but do say how they are set in every broadcast. The MOKO S01 motion and door sensor is one: it reports its PIR delay (how long it stays occupied after the last movement), its PIR sensitivity and its door sensor. On Device → Sensor, select the sensor and View: the Sensor settings card shows each setting as the sensor last reported it.

Pick the value each setting should have under Wanted and Save wanted settings. While the sensor reports something else, the card shows a warning and a Configuration anomaly stays open on Anomalies (admins are told the usual way); it closes by itself at the first report that matches, checked when you save and every hour.

Changing it from Omaya

Every S01 setting — not only these two — can now be changed on the sensor's Configure page: see Configuring devices from Omaya. A change made there also updates the Wanted values here, so the two never disagree.

Omaya can change PIR delay and PIR sensitivity on the sensor itself, through a gateway that hears it. Today that is a Dusun gateway and a MOKO S01 on firmware V1.0.3; the card says when a sensor or gateway cannot do it.

1. Pick the Wanted values and Save wanted settings.
2. Under Change on the sensor, check the gateways listed after via. These are gateways that heard the sensor in the last hour and accept commands.
3. Type the sensor's password (8 characters) once, or choose use factory default if nobody has changed it. Omaya keeps it encrypted, never shows it again and uses it only for this sensor.
4. Choose Change on the sensor now.

Omaya signs in with the same passwords as the Configure page, in the same order: the sensor's own, then your organisation's MOKO password, then the factory default. Whichever works is remembered, and what the sensor reads back shows on its Configure page as now on the device.

Omaya connects through the nearest gateway and gives the password. It writes the wanted values, reads them back, then disconnects, which takes about 20 seconds. If that gateway cannot reach the sensor, it tries up to two more. It then waits up to 90 seconds for the sensor's own broadcast to show the new values. The change is listed under Recent changes as Running, Done (✓ once the broadcast agrees), Failed (with the reason) or Refused.

Omaya only ever sends these two settings. Nothing on the card can switch the sensor off, reset it, make it non-connectable or update its firmware.

Read-only gateways

Any gateway can be made read-only: edit it on Device → Gateway and turn off Accept commands. Omaya still uses its readings for presence and reports, but never sends a command through it. A change that only a read-only gateway could carry is Refused, not sent, and stays in Recent changes with the gateway named. The same happens when a gateway is switched to read-only after a change was queued but before it was sent. Gateways accept commands until you turn the switch off.

Every command in the Activity Log

Every command Omaya sends to a device is also written to System → Activity Log: a sensor settings change, a badge's Locate now or Restart, and the commands rules send. There is one row when it is sent, or refused, and one when it ends: done, failed, timed out, or verified once a sensor's broadcast shows the change. Each row names the device, who or which rule sent it, the values, and the gateway that carried it or refused it. Choose the Devices lane to see only these, and Export for a CSV; commands that failed, timed out or were refused are also under Needs a look. For one device, open the History tab in its panel. The System lane shows what happened without anyone doing it, such as a gateway going offline or a device going silent. Turning a gateway's Accept commands switch on or off is in the log too, as a gateway update showing the old and new value.

What the levels mean

MOKO gives PIR delay as Low ≈ 30 s, Medium ≈ 10 s and High ≈ 2 s, so a higher level is a shorter time, and PIR sensitivity as Low ≈ 5 m, Medium ≈ 8 m and High ≈ 12 m. For counting visits (a toilet, a meeting room), Low delay is the longest the sensor offers; someone who sits still for longer than that can still be counted again, so give the rule that counts visits Repeat at most every a few minutes. Keep sensitivity no higher than the room needs, or it sees movement outside the door. A door sensor that never changes from open has no magnet fitted, or the door is held open.

Problems

What you see	Why, and what to do
"No gateway has heard this sensor recently" or "None of the gateways that hear this sensor can connect to it"	No Dusun gateway near the sensor has heard it in the last hour: the gateway is offline, only other makes of gateway are near, or the sensor has stopped broadcasting. Check the gateway and the sensor's battery.
"Every gateway that hears this sensor is read-only", or a change Refused	Every gateway that hears the sensor has Accept commands turned off. Turn it on for one of them, or leave the sensor as it is.
"The sensor refused the password"	The sensor's password is not the one Omaya has. Type the right one and try again. Nothing was written.
"This sensor runs firmware …, whose layout Omaya does not know yet"	Nothing was written. Use the MOKO app on a phone next to the sensor, and tell us the firmware so it can be added.
Done without ✓	The sensor confirmed the change, but its broadcast had not shown it within 90 seconds. Gateways repeat old frames for about two minutes, so check the card again shortly.
No Badge settings card on the badge	The device is not registered with the PS101-M model. Edit it and choose the model.
"Omaya does not know where to send commands"	There is no MQTT connector for your organisation. Add one under Connectors → IoT Gateway (MQTT), or set the topic with Change.
Every command ends No answer	The badge's Subscribe topic is not the command topic shown at the top, or the badge is offline. Check the topic in the MKLoRa app. If the badge still sends reports, the topic is almost certainly the cause.
Failed: "the alarm function is off"	Trigger, Exit alarm, Find and Sound badge need Alarm type Alert or SOS.
Failed: "out of the range it accepts"	The badge's firmware has a narrower range than its manual. Read the section again and keep closer to the values it reports.
Failed: "does not know this setting"	Older firmware. Update the firmware, or leave that section alone.
"still waiting for the badge's answer"	Wait for the first command to finish, or until it runs out of time.
"Too many commands to this badge"	Omaya allows 60 commands a minute per badge, so a badge is not flooded. Wait a minute.
After an MQTT change the badge disappeared	It restarted with a wrong value. Bring the MKLoRa app next to it, double-click its function button to open the Bluetooth window, and correct the setting.
Find did not beep	Buzzer set to Silent, or Alarm type No alarm.