Distance sensors: pick a mode for your scenario

A distance sensor — the MOKO SO2R time-of-flight sensor — answers one question over and over, about once a second: how far away is the nearest thing in front of me? Anywhere from 4 cm to 3 m, inside a narrow cone.

That single number can answer three very different questions, depending on where you point the sensor and which mode you give it. This page is for choosing: find your scenario, mount the sensor the way it says, set the mode, and you know what you will get in Omaya.

Which mode is your question?

Your question	Mode	Examples
Is something there?	Occupancy	a parking bay, a hospital or care-home bed, a desk or chair, a loading dock, a meeting room table
How full is it?	Level	a waste bin, a water or chemical tank, a hopper, a stack of stock or supplies
How many went past?	Counter	a trolley lane, a vehicle or boom gate, a conveyor chute, a slow doorway

One sensor has one mode. If you need two answers from the same spot — is the bay occupied and how many cars used it — use two sensors, or have a rule log every change of the first into a data table and count the rows.

How it works, in one minute

Every mode starts from the same measurement: the empty reading — the distance the sensor sees when there is nothing there: the floor under the bay, the bottom of the empty bin, the far side of the lane. Everything else is compared with it.

• Occupancy and Counter call the beam blocked when something is nearer than the empty reading by more than the margin (200 mm unless you change it). Occupancy reports blocked = occupied. Counter books one crossing each time the beam goes from clear to blocked.
• Level turns the reading into a percentage: 0 % at the empty reading, 100 % at the full reading, and a named band — empty, low, medium, high by default, or your own.
• A change only counts once it has held for a number of readings (Confirm after, 2 by default — about two seconds). That stops a single glitch reading from flipping a bay to occupied or booking a crossing.
• Nothing in range (more than 3 m away, or no echo) is treated as clear.

Scenarios

Occupancy

A parking bay — is it taken?

Mount on the ceiling above the middle of the bay pointing straight down, or on the back wall at bumper height pointing out. Keep it within 3 m of where a car will be — a basement ceiling at 2.4 m is ideal.

Set mode Occupancy. Take the empty reading with the bay empty (it will read the floor, or the far wall). Raise the margin to 400–500 mm so a person walking through the bay, or a shopping trolley, is not a car.

You get the bay's zone occupied / free live, and an hourly record, so Space Utilisation shows what share of the day each bay was in use. A rule can say "bay has been occupied for more than 4 hours".

A bed — is the patient or resident in it?

Mount above the bed, on the ceiling or a wall bracket, pointing at the middle of the mattress — not the pillow, not the edge.

Set mode Occupancy. Take the empty reading with the bed empty and made — the mattress, not the floor. A lying person is 150–300 mm above the mattress, so the default 200 mm margin may be too much: try 100–150 mm, and check with a person lying down (the panel shows the verdict live).

You get the bed occupied / empty. The useful part is the rule: "bed empty for more than 15 minutes between 22:00 and 06:00" → alert the night nurse or carer. That is a hold condition — see Rules.

A desk, chair or meeting-room table — is it being used?

Mount under the desk pointing at the knee space, or above a chair. For a meeting room, one sensor over the head of the table is enough to answer "is this room in use?".

Set mode Occupancy, empty reading with nobody there. Keep Confirm after at 2–3 so someone leaning over the desk for a second is not a sitting.

You get occupied / free for the desk's zone and Space Utilisation over the day. When the sensor is in a meeting room zone, the Meeting Room app uses it: the room shows in use, and a booked room nobody turned up to can be released automatically.

A loading dock — is a truck backed in?

Mount on the dock wall above the door at the height of a truck's rear, pointing out. The empty reading will be the yard (or nothing in range — that is fine; it means clear).

Set mode Occupancy, margin 500 mm or more. A rule on "occupied for more than 45 minutes" flags a truck that has been at the dock too long.

Level

A waste bin — when does it need emptying?

Mount under the lid (or on a bracket above an open bin) pointing straight down into the bin, in the middle.

Set mode Level. Empty reading: the bin empty — the bottom of the bin. Full reading: what the sensor reads when the bin is as full as you want it to get — put a board at the fill line, or fill it, and press Use now. Keep the full level at least 10 cm below the sensor (the sensor cannot read closer than 4 cm, and rubbish is uneven).

Bands that work for bins: empty up to 10 %, ok up to 60 %, soon up to 85 %, full above.

You get the bin's percentage and band on every reading. The action is a rule: "when the band becomes full" → raise a work order for the cleaning team, or notify them. Add "and it has held for 10 minutes" so a bag dropped in and pressed down is not a false alarm.

A water, diesel or chemical tank — how much is left?

Mount on the tank's top, pointing down at the liquid, away from the inlet (a falling stream reads as a high level) and from the tank wall (the cone must not touch the side — see the cone).

Set mode Level. The empty reading is the tank bottom (or the lowest level you care about), the full reading the top fill line.

Bands for a supply tank run the other way round from a bin — you care when it is low: refill now up to 15 %, low up to 35 %, ok above.

You get a live percentage. Rules: "band becomes refill now" → order it.

Clear liquids and foam can read badly; steam and condensation on the lens will. Test before you rely on it.

A stack of supplies or stock — paper towels, pallets, cartons

Mount above the stack pointing straight down at its middle.

Set mode Level, empty reading with the shelf or floor bare, full reading with the stack at its normal full height.

You get how much is left. A toilet supply cupboard with "band becomes low" → restock task is a common first use.

Counter

A trolley lane or vehicle gate — how many passed?

Mount at the side of the lane at trolley or bumper height, pointing across it. The empty reading is the far side of the lane (or nothing in range on a wide gate).

Set mode Counter, margin so that the far side is well clear (a 2 m lane with 200 mm margin is fine). Confirm after 2.

You get one entry on the Enter / Exit report for each trolley or vehicle, and the Entry Count rule metric — a running total for the day, so "more than 400 vehicles today" is a rule.

Counter is not a footfall counter

The sensor reports about once a second and a crossing has to hold for Confirm after readings, so anything that goes through the beam in under a second or two is missed. A trolley, a car at a gate, a slow queue: counted. People walking briskly through a door: many are missed.

It also has no direction — a beam cannot tell in from out — so the Enter / Exit report shows entries only and 0 exits for a distance sensor. That is expected, not a fault.

For people through a doorway, use a door counter; for how many people are in a room, a radar — see People counters and tags and Radars. And never mark a venue "every way in and out is counted" when a doorway has only a distance sensor: with no exits, the building would only ever fill up.

Where you see the result

Mode	Live	History	Rules can use
Occupancy	the zone's occupied / free; the Meeting Room app's in use	an hourly record — Space Utilisation shows the share of each day in use	occupied
Level	the device page	none by itself — a rule can write each change to a data table if you want the history	level_percent, level_band
Counter	—	entries on the Enter / Exit report (and Dynamic reports)	Entry Count (today's running total)

Every mode also keeps the raw distance, hour by hour, on the Distance report (Reports → Distance) — the first place to look when a verdict seems wrong.

Occupancy does not change the Right Now people number. That number counts people; occupied is a yes/no, not a count.

Rules that act on it

The mode turns a distance into something a rule can reason about. Build the rule on the sensor, pick the field, and add a condition — see rules on any sensor reading.

Scenario	Rule
Bin full	level_band becomes full → raise a work order for cleaning
Tank low	level_band becomes refill now → notify facilities
Night-time bed exit	occupied = 0, held for 15 minutes, between 22:00 and 06:00 → alert the night staff
Truck overstaying	occupied = 1, held for 45 minutes → notify the dock supervisor
Bay overstay	occupied = 1, held for 4 hours → flag the bay
Busy gate	Entry Count above 400 today → notify security

Becomes fires once, when the value changes to it — so a full bin raises one work order, not one a second. Held for (Only after it has held for a while) waits until the condition has been true continuously for that long — see the guide.

Setting it up

1. Register the sensor under Device → Sensor: its MAC, Device Model SO2R (vendor MOKO), and the zone it watches — the bay, the bed space, the room, the bin store.
2. Mount it as your scenario says, and leave the area in its empty state.
3. On the device's page, open Distance calibration. Reading now shows the live distance.
4. What is the sensor watching? — pick Occupancy, Level or Counter.
5. Empty reading (mm) — press Use now while the area is empty.
6. Occupancy / Counter: set the Margin (mm); the panel shows Blocked when nearer than so you can sanity-check it. Level: press Use now for the Full reading (mm) with it full (or type it), and adjust the Bands.
7. Confirm after — 2 readings is right for almost everything.
8. Now test: put a car in the bay, lie on the bed, fill the bin, walk a trolley through. With this setup shows the verdict live. Adjust, then Save calibration.

The sensor's own settings — how often it measures, its range and its signal strength — are shown on its Configure page (View → Configure), read through a Dusun gateway. To change them, use MOKO's app next to the sensor for now. See Configuring devices from Omaya.

Mounting: the cone matters

The sensor does not see a point, it sees a cone about 27° wide, and it reports the nearest thing anywhere in that cone.

Distance	Width of what it sees
0.5 m	about 25 cm
1 m	about 50 cm
2 m	about 1 m
3 m	about 1.4 m

• Keep edges out of the cone. A tank wall, a door frame, a shelf lip or a door handle near the edge of the cone is "the nearest thing" some of the time. On one of our own units a door handle at the edge of the cone produced a false blocked every few seconds; moving the sensor 10 cm cured it.
• Re-take the empty reading whenever you move the sensor. The old one describes a place the sensor no longer looks at.
• Bright light near an entrance can cause the odd very short reading. Confirm after 2 absorbs it; do not set it to 1 there.
• Dark, shiny or transparent surfaces — black plastic, glass, clear liquid — return less light. Test with the real target before relying on it.
• 3 m is the limit. Beyond it the sensor reports nothing in range, which every mode reads as empty / clear.

When it disappoints

Symptom	Likely cause	Fix
Occupied when nothing is there	an edge or object in the cone; empty reading taken from an old position	re-aim; re-take the empty reading
Never occupied	margin larger than the object (a lying person, a low trolley)	lower the margin
Flickers between states	the object sits right at the margin	move the margin away from it; raise Confirm after to 3
Counter misses people	they cross in under a second — expected	use a door counter for people
Counter shows 0 exits	a beam has no direction — expected	—
Level stuck at 100 %	something on or right in front of the lens	clean it; keep the full level at least 10 cm below the sensor
No verdict at all	the sensor has not reported, or (occupancy) has no zone	check the device's last seen and its zone