Data flows, timers and geofences

A flow is the path an incoming report takes through Yggio. It decides which services see the report and in what order - translators, calculations, the location service, the database, the channels and the rule engine.

Most devices never need anything but the default. You change the flow when the use case needs something the default path cannot do. There are two such things: a timer that outlives a single report, and a check of whether a device is inside a geofence.

Flow	What it adds
Default	Nothing. Translators, calculations, location, database, channels, rules
General Timer	A timer per device, so a condition can be required to persist
General Geo Query	Geofence checks, for tracking
General Timer and Geo Query	Both

A flow is a set of instructions, and it can include transform functions - code you upload and Yggio runs inside a sandbox as part of the flow.

Flows are also how Yggio copes with high-frequency data: a flow can skip most of the pipeline and write incoming data straight to the database.

Assigning a flow

The flow belongs to the device. Each device runs its own, so a tracker on the geo query flow and a temperature sensor on the default flow can sit on the same connector.

The connector carries a default flow, which new devices created on it inherit. That is what saves you setting the flow on every device by hand - set it once on the connector and the devices that arrive through it start out right.

Assigning a flow is done through the API today. There is no interface yet for choosing one when a device is created, or for changing it afterwards, and the connector wizard offers Default only. Custom flows are uploaded the same way.

Note: not every integration supports every flow. Check with your support representative for the one you are using, and for uploading a custom flow.

Flows are not supported on the legacy connectors under New Device in Devices.

Default flow

The flow used when nothing has been configured.

Data arrives from the connector and goes to the translator service, which runs every translator on the device. Calculations run next, then the location service, which updates the device's position if it has changed. The result is distributed to the channels, the database and the rule engine.

General Timer flow

The default flow, plus the scheduler after the location service.

A report is a moment. A timer is what turns a moment into a duration, so the flow can answer "has this been true for five minutes" rather than only "is this true now".

The general-timer translator

The flow supplies the scheduling; the translator decides what is being timed. Both are needed - the translator computes timer state on each report, and the flow is what actually waits and writes timerExpired back afterwards. Without the flow the timer never expires.

general-timer is a chained translator: it runs on top of the device's hardware translator and reads fields that translator has already decoded.

Parameter
timerTriggerField	The device field to watch, for example door or temperature. Nested paths work
timerDelay	How long the condition must hold before the alarm fires, in seconds. Default 600
timerBooleanTriggerValue	The boolean value that starts the timer, when the trigger is a boolean

Numeric triggers take a high and a low threshold with hysteresis. A threshold left at "Unused" is disabled.

Output
timerExpired	The alarm. True once the condition has held longer than the delay
timerStart	Whether the timer is running
timerStartedAt	When it started, as a timestamp
timerDelay	The delay in milliseconds, converted from the parameter

timerExpired is what a rule watches, and timerStart and timerStartedAt are what a view or dashboard shows to say a timer is running.

Setting it up

1. Set the device's flow to General Timer.
2. Add the general-timer translator, one device at a time or with Select many.
3. Configure its parameters - the field to watch, the delay, and the thresholds or boolean value.
4. Build a rule on timerExpired, and put timerStart and timerStartedAt on a view or dashboard.

What it is for

• A door or window that has not closed within the expected time.
• A threshold that may be crossed briefly without alarming - temperature over its limit for at most five minutes, and only a longer breach raises the alarm.
• A boolean state held longer than it should be.

General Geo Query flow

The default flow, plus the geo query after the location service. Use it for tracking.

The geo query compares a tracker's WGS84 position against the geofences and produces an access event:

Event
access: enter	The tracker entered a geofence
access: inside	It reported a new position while inside
access: exit	It left

A geofence is a polygon, and it is connected to an IoT node - the geofence reference node. The logic lives in a translator on that node, not on the tracker.

The general-geofence translator

general-geofence goes on the geofence reference node. On each access event it maintains the list of assets currently inside, counts them, and drops assets that have gone quiet or left.

Output
assets	How many assets are inside
trackers	How many of those are the tracker type you are counting
assetList	Everything inside, each with its name, id, position, floor, access state and timestamp
assetUpdate	The asset that just entered, exited or moved

Parameters worth knowing:

• contextMapTrackerField and contextMapTrackerFieldValue pick out one type of asset to count separately. A geofence holding baggage carts and wheelchairs can count assetType = "Baggage Cart" as trackers while assets counts everything.
• removeIdleAssetsAfterHours drops assets that stop reporting, minimum 24 hours. removeExitedAssetsAfterHours drops ones that left, 0 to remove them immediately.
• assetListEnabled and assetListMaxLength turn the asset list off or cap it. Turn it off when a geofence holds many assets.

Telling the tracker where it is

By default the tracker knows nothing about its own geofence state - the counting happens on the geofence node.

forwardAccessEventToTracker changes that. With it on, an enter or exit event is posted back to the tracker, addressed by the field named in trackerIdentifier (devEui, say). What gets sent is forwardDataStructureToTracker, a port and a hex payload. Only events inside forwardAccuracyLimit are forwarded, so a poor position does not move a tracker in or out.

Setting it up

1. Set the trackers' flow to General Geo Query.
2. Create a generic node for each planned geofence with New device.
3. Add the general-geofence translator to those nodes, at creation or later with Select many.
4. Draw the geofences on the map or in a map widget, and connect each to its node.
5. Build rules on the enter and exit events on the geofence nodes.

General Timer and Geo Query flow

Both of the above. It answers questions about how long a tracker has been on one side of a geofence, rather than only which side it is on.

A limit zone is the usual case: an asset may leave a geofenced area, but not for more than twenty minutes, and a certain number of assets must stay inside.

The general-timer translator covers this. Start a timer when an asset enters or exits, and if the state has not changed back within timerDelay, timerExpired fires.

For logic the standard translator does not cover, a custom translator on the geofence node uses the same fields:

Field
timerStart	true starts or restarts the timer, false stops it
timerDelay	The duration, in milliseconds
timerStartedAt	When it started, as a UTC timestamp. Clear it when the timer stops
timerExpired	Written back by the flow when the timer runs out

Other flows

Two more flows exist for positioning use cases: one resolves a position from WiFi access points and map-matches it, and one does the same and can send a tuning downlink back to the device. Neither is self-service. Ask your support representative whether one fits what you are building.