System overview

Overview

Five diagrams explain most of the platform: who works in it, how a building is described, what can be in a room, how a packet becomes a number on a screen, and how Omaya is told to act on it.

Read this chapter before the menu reference. Most questions of the form "why is this page empty?" are answered by one of these diagrams.

Users and screens

Three doors, two kinds of account. Administrators use the admin console; the people who only use an app — cleaners, receptionists, guards — have an app user account and sign in at their organisation's own page. The phone app takes either. northwind stands for your organisation's tenant ID.

One platform serves several kinds of screen, each for a different person:

Screen	Intended for	Typical use	Read
Admin console (/admin/…)	The people who set the platform up and read its reports	A facilities manager sets up floors and rules; an operations lead reads the reports	Signing in, the menu reference
Staff apps (/<organisation>/…)	People who use one app as part of their job, without the admin console	A cleaner ticks off cleaning rounds; a receptionist checks visitors in	The apps
Omaya Mobile	Either of the above, on an Android phone	A technician takes work orders on his rounds	The mobile app
TV screens	Nobody signs in: a screen on a wall	The lobby shows which meeting rooms are free now	TV dashboard

The admin console and the staff apps read the same data. What differs is who has an account where: administrators are created under System > Admins, app users under Apps > App Users, and an app appears only for an organisation that has it enabled.

How a 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.

Characteristics

Building is optional, and hidden when empty. If a location has no buildings, the level does not appear in the picker at all. A single-site deployment reads Location > Venue > Zone; showing an empty tier would only add a decision that can be made wrongly.

A floor is not a level. There is no 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 object that zones belong to must be the same object.

A room's capacity belongs to its zone, once. The capacity of a meeting room is set on its zone, and every function reads it from there, including the meeting-room booking app. There is deliberately no second place to enter a room's capacity, because two places would allow a room to have two capacities. A venue can carry a capacity of its own for the floor as a whole (the fire certificate figure); when it is left empty, the floor holds the sum of its zones.

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.

Characteristics

A zone's number means whatever the best device in it can measure. In a room with a radar, the count is a count of people. In a room with nothing but gateways, the count is a count of badges. Both appear in the same column, which is why every count carries its source.

CAUTION

Before concluding that a room is under-occupied, check what is measuring it. A meeting room with no radar and no counter, in an office where nobody wears a badge, reports zero all day.

How a reading becomes a number

One packet, two destinations, two different freshnesses.

How it works

The split at the end of the path explains the most common reported discrepancy: the Right Now page and a report disagree.

They read opposite ends of the same pipeline, by design. Live state exists seconds after a packet arrives; the Right Now page, the zone occupancy tiles and the rule engine read it. The report tables are rebuilt every five minutes from the same data; every report, export and history endpoint reads them. In the most recent few minutes, the first has data that the second does not have yet.

Characteristics

• Today's daily totals are provisional. The per-day figures are finalised in a rebuild at 00:05 UTC, which is just after 08:00 in Kuala Lumpur or Singapore. The hourly rows stay current to within about five minutes all day; the day's total settles the next morning.
• The look-back period is limited. Report data older than the organisation's data retention setting (System > Configuration) is removed every night, a month at a time. A report for a period before that comes back empty, not wrong.

How Omaya acts on a reading

Repeat at most every is the part people leave at its default and then regret. It starts at 30 seconds, and a condition that stays true is true every time it is checked, so a rule left at the default can send the same message sixty times an hour. Set it to the interval at which you would actually want to be told again.

How it works

A rule watches one thing (a device, a person or asset, a label, a zone, a floor, a site, a gateway or a geofence), checks a number or an event about it, and acts. When it is checked is set by Checked, on the rule's Checked card:

Checked	When the rule is evaluated
Real-time	As data arrives. A rule on a device, label, person or zone is checked when a reading comes in from a device it covers. A rule on a floor or a site is checked when a sensor on that floor reports something new, and at least once a minute while the value holds. A rule on an event (someone entering a place, a gateway going offline, a work order opened) is checked once, when the event happens.
Scheduled	On the selected interval, from every 5 minutes to weekly. Omaya checks every minute which scheduled rules are due. Footfall and capacity figures move with the hourly roll-up, so rules on them must be scheduled.
Manual	Only when someone clicks Run it now on the Rules list.

A condition that must hold for a number of minutes is re-checked every minute until it has held that long.

What the rule sees depends on which side of the split its metric comes from: a radar metric is live; a footfall metric comes from the roll-up. Rule metrics states which applies to every metric.

Restrictions

Three further settings on the Checked card decide whether a rule is useful:

• Repeat at most every: how long after it fires before it may fire again, from 30 seconds to one day; the default is 30 seconds. A condition that stays true is true at every check, so this setting stops one situation from becoming sixty messages. On a label rule or a person / asset rule, each device keeps its own clock.
• Days: the days on which the rule may fire. A weekly reminder is one day selected plus Repeat at most every 24 hours; there is no interval longer than one day.
• Hours: a start and a stop time, so that a "room left empty" rule does not alert anyone at 03:00.

Verification

Test, beside Save, checks each condition against the live reading at that moment, and replays the rule over the last few days of tag movements to state how often it would have fired, before it sends anything.

Rules describes how to build one.

Related documents

• Occupancy: which number is which: the page to read before drawing 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 a room can measure.