MOKO PS101-M smart badge (cellular)

The PS101-M is a badge with its own SIM. It talks to Omaya directly over the mobile network (LTE-M or NB-IoT), with no gateway in between: it sends where it is, its battery, and its alarms — SOS, Alert and man-down — and Omaya can send it commands back (Device settings and commands).

Where it is comes three ways, chosen on the badge:

• GPS outdoors: a position, turned into geofence visits, trips and stops on the badge's trail and the wearer's (Indoor and outdoor).
• Bluetooth scan indoors: the badge lists the beacons it hears, and Omaya places it in the room of the ones it heard loudest (Beacon and Wi-Fi anchors).
• Wi-Fi scan: the same with your own access points as anchors.

It does not broadcast like a tag

The badge does not send a continuous Bluetooth signal for gateways to hear. Its Bluetooth is a configuration window that stays open for a few minutes (3 by default) after power-on or a double-click of the function button. Indoors it is found by scanning — set a Bluetooth or Wi-Fi fix and add anchors — or not at all.

The steps, in order

The badge needs two topics from Omaya, and the second one exists only once the badge is registered. So Omaya comes first, then the badge, then Omaya again.

1. Connect the MKLoRa app to the badge and note its MAC — Connect the app
2. In Omaya: create the connector and keep its host, port and topic — A
3. In Omaya: register the badge by its MAC, and copy its command topic — B
4. On the badge: point it at Omaya with both topics — Network settings
5. In Omaya: bind it to the person who wears it — C
6. Decide who is paged for its alarms — D
7. Name the places (geofences outside, anchors inside) — E
8. Check it end to end — F

Before you start

• A data SIM that supports LTE-M (Cat-M1) or NB-IoT on your carrier, with its APN and the PIN switched off. Ordinary phone SIMs often do not attach to those networks; ask the carrier.
• MOKO's MKLoRa app on a phone (iOS or Android). The badge is set up only over Bluetooth with this app.
• Somewhere outside with open sky for the first GPS test.

Fitting the SIM and powering on

Open the back cover, insert the SIM, close it. Hold the function button (on the back) for 3 seconds: the green LED stays on for 3 seconds. The orange LED then says how the network is going:

Orange LED	Means
Blinks every second	Joining the network
Blinks every 2 seconds	No SIM detected
Blinks every half second	On the network
On for 5 seconds	Connected to the MQTT broker

The Bluetooth window for the app is only open for 3 minutes after power-on. Double-click the function button to open it again.

Connect the app

In MKLoRa: PS101 → refresh → PS101-M-XXXX (the last four characters of its MAC) → Connect. The default login password is Moko4321.

Write down the badge's MAC address from DEVICE → Device Information: Omaya registers the badge by it in step B.

Change the Bluetooth password first

Anyone with the free app and the default password can connect to the badge and point it somewhere else. GENERAL → Bluetooth Settings → Change Password before it leaves your hands.

Out of the box the badge publishes to MOKO's own broker (47.104.81.55). Nothing reaches Omaya until its network settings point at Omaya, which needs steps A and B first.

In Omaya first

A. Create the connector

Connectors → IoT Gateway (MQTT) → add:

Field	Choose
Connector Name	e.g. PS101 badges
Vendor	Generic / Other
Protocol	BLE (Bluetooth Low Energy)
Active	on

Press Save, then open the connector again: the MQTT Topic box appears only on a saved connector. It shows:

• the topic, omaya/<your organisation id>/<token>/generic/ble, with a copy button. The 16 characters after your organisation id are this connector's token;
• the Host, and the Port: 8883 with TLS, 1883 plain.

Keep all three for the badge. The token works as the badges' password: anyone who has the topic can publish as your badges, so share it only with whoever sets them up. Rotate Token issues a new one, and the old topic stops working at once: every badge then needs the new topic before it reaches Omaya again.

B. Register the badge

Device → Sensor → add, with the badge's MAC (the one you wrote down from DEVICE → Device Information), model PS101-M Smart Badge, type Tracker. Register it as a device, not a gateway: the badge reports itself. A badge registered without a model is recognised as a PS101 from its first message.

Messages from a badge Omaya does not know are not stored. The log says "unrecognized device" with its MAC, which is how to find a typo.

Then open the badge: Device → Sensor → the badge → View. Its Badge settings panel shows the command topic, omaya/<your organisation id>/<token>/device/<MAC>/cmd, which is where Omaya sends the badge its commands. Copy it: it is the badge's Subscribe Topic in the next step. The panel exists only once the badge is registered.

On the badge: point it at Omaya

Connect MKLoRa to the badge again (double-click its function button if the 3-minute Bluetooth window has closed), with the topics from steps A and B to hand.

NETWORK → Network Settings

Field in the app	Default	Set to
Host	47.104.81.55	The Host from the connector's MQTT Topic box (step A)
Port	1883	1883, or 8883 with SSL/TLS on
Client Id	the badge's MAC	Leave it: the MAC is already unique
Subscribe Topic	/PS101-M/{MAC}/receive	The command topic from the badge's Badge settings panel in Omaya (step B): omaya/{org}/{token}/device/{MAC}/cmd, MAC as 12 upper-case hex characters. This is where Omaya sends commands
Publish Topic	/PS101-M/{MAC}/send	The topic from the connector's MQTT Topic box (step A), omaya/{org}/{token}/generic/ble — no leading slash
Clean Session	on	Leave
QoS	1	Leave at 1
Keep Alive	60 s	Leave
Username / Password	blank	Blank (Omaya's broker does not ask for one today)
SSL/TLS	off	On with port 8883 if you want the link encrypted; see Problems
LWT	on, topic = subscribe topic	Leave as it is, or turn it off. It must not use the publish topic
APN	blank	Your SIM's APN
Network Priority	eMTC → NB-IoT	Whatever your carrier offers; LTE-M first is usual

Press Save (top right). The badge applies the new broker after it reconnects; restart it from the app if the orange LED does not settle on "connected".

The leading slash

MOKO's default topics start with /. In MQTT that is an extra, empty first level, so /omaya/… is a different topic from omaya/… and Omaya never sees it. Delete the slash.

DEVICE

Setting	Set to
MQTT Data Format	JSON. Omaya does not read HEX. Leave it on JSON
Current Time Zone	Your local time zone (default UTC+8). Reports carry their offset, so Omaya reads them correctly either way
Low Power Prompt	10–20 %, and Low-power Payload on — the badge then tells Omaya when it is low
ON/OFF Settings → Shut-Down Payload	On, so Omaya knows a badge was switched off rather than lost
Buzzer / Vibration	To taste. They sound on the badge during an alarm

GENERAL → Device Mode

Only one mode runs at a time.

Mode	What it sends	Choose it when
Periodic (default)	A position every Report Interval (default 30 min, 1 min – 10 days)	Most sites. Shorter intervals give finer trips and cost battery
Motion	A position when the wearer starts and stops moving, every n seconds while moving (default 300 s), and every 30 min when still	People who move a lot, then sit for hours: fine trips without draining the battery at a desk
Timing	A position at up to ten clock times a day	A check-in at fixed times
Standby	Only a heartbeat (default every 12 hours), and positions for alarms or when asked	Lone workers who only need the alarms

Strategy (per mode) says how the badge finds itself: GPS for outdoors; Bluetooth or Wi-Fi for indoors with anchors; or a chain such as BLE → GPS (try Bluetooth, then GPS if no beacon was heard), which covers a person who is sometimes in, sometimes out. Without anchors, a Bluetooth or Wi-Fi strategy gives Omaya a list of what was heard and no room.

Omaya expects the badge as often as its mode says: a badge on a 30-minute period counts as online for about an hour after each report, one in Standby for a day after each heartbeat. It is not shown offline between reports.

GENERAL → Auxiliary Operation

Item	What to set
Alarm Function	SOS (default) or Alert — one at a time. See Alarms
SOS	Trigger (double-click, triple-click or a long press), report interval during the alarm (10–600 s), and Notify Event On Start / End both on
Alert	Trigger, and Notify Event On Start / End both on
Man-Down Detection	Off by default. On for lone workers: timeout is how long without movement counts (1–120 min, default 10), and Notify Event On Start / End both on
Downlink for Position	The strategy used when Omaya asks the badge where it is

The "notify event" switches are what tell Omaya an alarm started and ended. Leave them on.

A fleet of badges

When one badge is right, NETWORK → Export Config File and Import Config File on the others. Then fix each badge's Subscribe Topic: it contains that badge's own MAC.

Your MQTT settings

The publish topic is the topic on your connector (step A): your organisation id, then the connector's 16-character token, which is the badge's password — treat the topic like one. Every badge can publish on the same topic; Omaya tells them apart by the MAC in each message.

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.

The subscribe topic is the same organisation and token, then device/, the badge's MAC as the app shows it (12 characters, upper case, no colons) and /cmd. For example, for an organisation acme whose connector token is 3f9c0a7d5e1b2c48, and a badge AA:BB:CC:2A:6F:20:

omaya/acme/3f9c0a7d5e1b2c48/device/AABBCC2A6F20/cmd

Those values are made up: use your own organisation id and your own connector's token, as shown on your connector.

Copy it from the badge's Badge settings panel in Omaya (Device → Sensor → the badge → View), which shows the exact topic Omaya sends its commands to — see Device settings and commands. Register the badge first (step B) so the panel exists.

Fill in your own

Type your organisation id, token and the badge's MAC — or paste the whole topic from the connector page — and copy each value into the app. It works in the page only: nothing you type is sent or saved.

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

Then, in Omaya

C. Bind it to a person

Entity → the person (or Add Entity) → Bound Sensors → add the badge. Their trail, Entity Tracker card, Roll Call status and Movement Replay then follow the badge. Alarms name the person. See People and assets (entities).

D. Decide who is paged

The badge's alarms reach people two ways; set up at least one.

• Security Watch (if you have the app): every SOS, Alert and man-down from a registered badge is a critical incident on the guards' board, with where the badge is. No extra setup — registering the badge is enough.
• Devices → Panic Buttons: pages the people you list, by email, in-app, SMS, WhatsApp or push. Pick one badge, or a label every badge carries, and the press SOS, Alert or Man-down (or any press).

A panic button is a rule, so it is listed under Rules as well, where you can add other actions. The Button pressed condition fires at the start of every alarm and can match its kind, and the badge's fields (alarm_state, event) can be used in a condition (Rules on any sensor).

E. Name the places

• Outside: on Space → Location → Map, draw a geofence around each place you want named. Everywhere else is a trip or a stop.
• Inside: if the badge uses a Bluetooth or Wi-Fi fix, add the beacons or access points as anchors on Space → Beacon & Wi-Fi Anchors (Beacon and Wi-Fi anchors).

F. Check it

1. Device → Sensor → the badge → View. Within a minute of saving the network settings: Latest reading shows Battery, Charging, Mode and Alarm none, and Last seen is now. The badge sends its device information each time it connects.
2. Take it outside (GPS strategy) and wait one report interval: Monitor → Live Monitor → Sensors shows it Outdoor; Monitor → Entity Tracker has the person under Outside.
3. Inside (Bluetooth / Wi-Fi strategy, anchors added): Latest reading shows Bluetooth scan: n seen — strongest …, and the badge is placed in the anchors' room.
4. Test the alarm with the people you paged warned first: trigger SOS on the badge. One page goes out, and on Security Watch one critical incident SOS from …. The positions the badge sends during the alarm update the incident; nobody is paged again. Hold SOS to end it (15 s by default): the incident is marked ended on the badge. A guard then resolves it as Test.

What Omaya does with each report

The badge sends	Omaya
Device information (on every connect)	Battery %, voltage, charging, firmware (kept on the device), IMEI and ICCID, mode, signal (RSRQ)
Location fixed — GPS	A point on the map, the trail (geofence visit, trip or stop), geofence rules and webhooks
Location fixed — Bluetooth / Wi-Fi	The scan list on the latest reading, and a room from your anchors
Location failed	Why, in words (GPS fix timed out, PDOP above the limit …) on the latest reading and the device
Event	Movement start / end; man-down, Alert and SOS start and end → Alarms
Low power	A battery alert straight away, not at the nightly check
Shut down	Offline at once, and who switched it off (button, app, command, flat battery)
Three-axis	Acceleration and angles on the latest reading
OTA / certificate result	Success or failure, kept on the device and passed to the command that started the update
Stored data (when asked for)	Each stored report at the time it happened — see Reports sent late
Every report	Battery, charging, internal temperature, mode and alarm state, as fields a rule can use

Alarms

Alarm	On the badge	In Omaya
SOS	Button trigger. Buzzer, vibration and red LED; a position every SOS interval until someone holds SOS (15 s) or Omaya sends Exit alarm	One incident, one page. Each position updates where the incident says the badge is. Ends when the badge says so
Alert	Button trigger. One position, then the badge leaves the alarm by itself	One incident, one page, ended when the badge reports it over
Man-down	No movement for the timeout. Positions faster until the wearer moves	One incident (No movement from …), one page, ended when the wearer moves

• One alarm, one incident. However many reports arrive during an SOS, the people on the routing are paged once. A new SOS after the last one ended is a new alarm.
• If the badge's "alarm ended" message is lost, its next report saying no alarm is active ends it; an alarm with no report for 30 minutes is treated as over.
• When it ends, the Security Watch incident is marked as ended on the badge; a guard still resolves it. Admins on the routing get an in-app note, and webhook subscribers get emergency.cleared after the emergency.activated that started it (Webhook events).
• Where: the page and the incident say where the badge was last placed — the geofence or street position outside, the room inside. The first position of an SOS usually follows the start by the time a fix takes; the incident shows it when it arrives.
• A late alarm. On a poor network the badge stores reports and sends them later. An alarm that reaches Omaya up to 15 minutes late still pages, and says how late. One older than that is recorded as history and pages nobody.
• Find / Sound badge from Omaya sets the badge's alarm off for a few seconds so it beeps. That alarm is Omaya's own: it is logged as a find and pages nobody.
• From Omaya: Locate now, Trigger alarm and Exit alarm are on the badge's Badge settings panel (Device settings and commands).

Battery

The PS101-M has a 1500 mAh rechargeable battery on a magnetic charger. Omaya shows its level, voltage and whether it is charging. Because it is charged rather than replaced, it gets no "replace in N days" forecast: the Battery report says rechargeable (or charging). Low-battery alerts still apply, and the badge's own low-power message raises one at once. If Facility Management is on, a critical battery opens a work order titled Charge …; switch that off under Admin → Your Apps → Facility → Work orders opened automatically if you would rather not.

MOKO publishes no battery life per mode. A shorter report interval, Motion mode with frequent in-trip fixes, a long SOS and Wi-Fi + Bluetooth + GPS chains all cost more. Charge badges overnight.

Reports sent late

When the badge has no network it keeps its reports (up to 10,000) and sends them when it is back, or when asked for its stored data. Omaya files each at the time it happened, not the time it arrived:

• points appear on the map at their own time; the trail is never rewound — a point older than the trail's latest stays a point;
• they never make the badge look online now, and never change its current battery or latest reading;
• a report Omaya already has (the stored copy of one that arrived live) is ignored.

Ask the badge for its stored data with the upload stored data command on its Badge settings panel.

When it disappoints

What you see	Likely cause	What to do
Nothing ever arrives	The publish topic still has MOKO's leading /, is mistyped, or the badge still points at MOKO's broker	Recopy the topic without the slash; check Host; press Save and restart the badge
Orange LED blinks every 2 s	No SIM detected	Reseat the SIM
Orange LED never stays on	No mobile data, wrong APN, or the SIM is not provisioned for LTE-M / NB-IoT	Check the APN with the carrier
Connected (orange on 5 s) but nothing in Omaya	MAC not registered, or registered as a gateway	Register it under Device → Sensor with the MAC from Device Information
Readings arrive but the log says PS101: message not fully understood	The badge sent something Omaya's decoder does not know (firmware differs from MOKO's document)	Send the log line to support; the readings it did understand are kept
Garbage or nothing after a settings change	MQTT Data Format set to HEX	Set it back to JSON in the app
No position indoors	GPS strategy indoors, or a Bluetooth / Wi-Fi strategy with no anchors	Use BLE → GPS and add anchors
Location failed: PDOP above the limit	Weak sky view	Raise GPS Fix → PDOP limit in the app, or accept fewer outdoor fixes
SOS pages nobody	No panic button covers the badge and Security Watch is off	Add a panic button for the badge or its label, press SOS (D)
An alarm never ends in Omaya	The badge's Notify Event On End is off	Turn it on; meanwhile it ends at the next report, or after 30 min of silence
Commands are never answered	The Subscribe Topic on the badge differs from the one on its Badge settings panel	Copy the topic from the Badge settings panel into the app
SSL/TLS on, never connects	The badge may need the CA certificate uploaded	Upload it in SSL/TLS in the app, or use port 1883
Badge shows offline	Switched off (the device says by whom), or no report for twice its interval	Check it is charged and on