How Omaya fits together

Four pictures that between them explain most of the platform: how your building is described, what can be in a room, how a packet becomes a number on a screen, and how you tell Omaya to do something about it.

Read this before the menu tour. Nearly every question of the form "why is this page empty?" turns out to be one of these four diagrams answered differently than expected.

How your building is described

Location → [Building] → Venue → Zone. Building is optional and disappears when you have none, so a single-site deployment reads Location → Venue → Zone. Everything that positions, ingests or reports hangs off the venue, which is why the venue — not the building — is where a floor plan and its calibration live.

Three things follow from this that catch people out.

Building is optional, and invisible when empty. If a location has no buildings, the level does not appear in the picker at all. That is not a missing feature — a single-site deployment genuinely reads Location → Venue → Zone, and showing an empty tier would be one more decision to get wrong.

A floor is not a level. You will not find a "floors" page, because a floor is two fields on a venue: a label and an ordering number. The venue owns the floor plan image, its scale and its calibration, and every zone is a shape drawn in that image's coordinates — so the plan and the thing zones belong to have to be the same object.

Capacity belongs to the zone, once. Set the capacity of a meeting room on the zone and everything reads it from there, including the meeting-room booking app. There is deliberately no second place to type it, because two places is how a room ends up with two capacities.

What can be in a room

One room can carry four things that all sound like they answer "how busy is it?" and none of which answer it the same way. The radar counts who is in the room. The gateway locates tags. The counter over the door counts people going through it, which only becomes an inside figure once every door is counted. The zone is the shape all of it is reported against.

The practical consequence: a zone's number means whatever the best thing in it can measure. Give a room a radar and its count is a count of people. Give it nothing but gateways and its count is a count of badges. Both appear in the same column, which is why every count carries its source.

Before you conclude a room is under-occupied, check what is actually measuring it. A meeting room with no radar and no counter, in an office where nobody wears a badge, will honestly report zero all day.

How a reading becomes a number

One packet, two destinations, two different freshnesses.

The split at the end is worth internalising, because it explains the single most common "bug report" we get: the Right Now page and a report disagree.

They are reading opposite ends of the same pipe, on purpose. Live state exists seconds after the packet arrives, and that is what the Right Now page, the zone occupancy tiles and the rule engine read. The report tables are rebuilt every five minutes from the same data, and that is what every report, export and history endpoint reads. In the newest few minutes, the first has data the second does not yet.

Two further consequences:

• Today's daily totals are provisional. The per-day figures are finalised in a rebuild just after midnight. The hourly rows stay current to within about five minutes all day; the day's total settles overnight.
• How far back you can look has a limit. Old monthly partitions are dropped on your tenant's retention setting.

How you act on it

The throttle is the part people leave out and then regret. A condition that stays true keeps being true every minute, so a rule with no throttle is a rule that sends the same message sixty times an hour. Set it to the interval at which you would actually want to be told again.

Rules are evaluated every minute. What the rule sees depends on which side of that split its metric comes from — a radar metric is live, a temperature metric comes out of a five-minute rollup — and the rule metrics page says which is which for all twenty of them.

Three settings decide whether a rule is useful or maddening:

• Throttle (action_every) — the cooldown before the same rule may fire again. 30 seconds to 24 hours. A condition that stays true is true every minute, so this is what stops one situation becoming sixty messages.
• Active days — restrict the rule to particular days. A weekly report-style note is active days set to one day plus a 24-hour throttle; there is no interval longer than a day.
• Time window — a start and stop time, so the "room left empty" rule does not page anyone at 3 a.m.

Where to go next

• Occupancy: which number is which — the one page to read before you draw a conclusion from a count.
• Report glossary — what each report answers, and the terms on it that are easy to misread.
• Rule metrics — everything a rule can test.
• Devices and what they report — what the hardware in that room can actually tell you.