State and occupancy translators
A state translator turns a reading into the canonical state field that the rest of Yggio understands. They are small adapters: a presence sensor reports presence, but views, rules and reports are built around occupied, so something has to bridge the two.
They are chained, running on top of the device's hardware translator.
Why they exist
A hardware decoder should report what the device actually said. Where that value is the right measurement in the wrong shape, or needs a reference before it means anything, the conversion belongs in its own translator rather than baked into the decoder.
That keeps the decoder honest and the conversion reusable, and it means the installation-specific part stays where you can change it. set-level-from-distance is the clearest case: a range-finder reports a distance, and only you know how far away the sensor sees the bottom of an empty container. Put that number in the translator's parameters and the same decoder works for every container you own.
The result is a canonical field, so everything downstream works on it, including an alarm translator.
The translators
| Translator | What it derives | Fields produced |
|---|---|---|
set-occupied-from-presence | The canonical occupied 0/1 value from a presence sensor's boolean presence field | occupied |
set-door-to-openstate | An inverted openState boolean from a sensor's door field, so open means open | openState |
set-level-from-distance | A fill level from a downward-pointing distance sensor, by subtracting the reading from normalDistance, the distance the sensor sees when the container is empty | level, occupied |
set-lnglat-from-gateway-location-chirpstack | A position from the ChirpStack gateway's location when the device reports none. For LoRaWAN sensors with no GPS, the nearest gateway's coordinates are rough but often good enough to place the device | lnglat |
set-enable-location-service-from-scan | A trigger for Yggio's location service, raised whenever a tracker delivers a fresh GNSS or WiFi positioning scan, so the position is resolved from the scan | enableLocationService, locationRequests |
set-road-blocked-if-traffic-anomaly | A candidate road blockage from an anomaly in traffic counts, carried together with the road name, the city and a geofence, for road maintenance | roadBlockedCandidate, countDetection, roadName, city |
Parameters
Most of these have nothing to configure: the conversion is fixed by what the field means. For the three that do, check each parameter below - some are required and the translation fails at runtime if they are left blank, while others are optional and fall back to automatic detection.
| Parameter | Used by | Purpose |
|---|---|---|
normalDistance | set-level-from-distance | The distance the sensor reads when the container is empty, which the measurement is subtracted from |
distanceField | set-level-from-distance | Read the distance from a specific field instead of the default |
doorField | set-door-to-openstate | Read the door state from a specific field instead of the default |
Note that set-lnglat-from-gateway-location-chirpstack gives you the gateway's position, not the device's. It is a useful default for a sensor that would otherwise appear nowhere on the map, and it should not be read as a measured location.
For the full A–Z index of every translator, see the translators overview.