onway routers can use geographic data to implement certain functionality, such as geofencing using the router position acquired over GNSS receivers. Geodata can be authored and supplied by customers and partners using well known industry standard data formats.
The onway tooling takes care of converting geodata for efficient deployment and use. Geodata is converted to an efficient binary format, packed into bundles using compression, and changes can be applied using efficient binary delta updates.
The exchange format used by onway geographic data uses GeoJSON encoding, as specified in RFC7946. This format is widely supported by a wide range of tools.
GeoJSON documents for use by the onway toolchain must contain either
a single Feature or multiple Features in a
FeatureCollection. Each Feature may contain
additional application specific metadata in its
properties.
The onway tooling takes care of converting GeoJSON input into a more
efficient binary format embedded in SquashFS bundles. GeoJSON documents
must be provided over private or public OCI
distribution compatible registries, such as Docker Hub, GitHub
Container Registry or others. The GeoJSON data must be provided as OCI
Artifact using the application/geo+json
Content-Type.
To upload an OCI Artifact, the use of the oras tool is recommended. It pushes the file to a registry using an explicit Content-Type:
oras push cr.example.com/my/geodata:v1 geo.json:application/geo+json
\--------------------------/ \------/ \------------------/
Repository and tag Geodata Content-TypeFor distribution in the SquashFS bundle, the GeoJSON gets converted
using onway tooling to the GeoBIN format for use by the
router. The file gets named after the name of the repository in the
registry URL. Specifically, this is the part after the last
/ and before the : of a tag, appended with
.geobin to indicate the file format. For
cr.example.com/org/example:v2, the base image will be named
example.geobin.
To test the bundling process and the geodata conversion as used by
onway, the onway-bundle-builder tool can be installed from
the onway authoring tools repository
using sudo apt install onway-bundle-builder. An example for
bundling a GeoJSON document is:
onway-bundle-builder -r cr.example.com/my/geodata:v1 -o bundle.squashfsEach repository may contain a single GeoJSON document, only, but
multiple Features can be supplied in a
FeatureCollection, or multiple repository sources can be
bundled into a single bundle.
For the geofencing application on onway routers, geofencing zones
must have a name that can be referenced in the router geofencing
configuration. The name of such a zone must be embedded in the source
GeoJSON data in the Feature properties in a
key named geofence-zone. All available
Features having this property can be used as geofencing
zone to evaluate if the current router position is within or outside of
the geometry.
If a router moves along a geofencing zone border, inaccuracy of the GNSS position may result in flapping within/outside states for such a zone. To avoid such a flapping, thresholds can be defined for a zone. A router previously outside of a zone signals entering into the zone only if it is geographically at least a threshold distance within the zone. A router previously inside a zone signals zone exit only if it is geographically at least a threshold distance away from the zone.
Zone enter/exit thresholds can be specified per GeoJSON
Feature in the properties with the keys
geofence-enter-thresh for the zone enter threshold and
geofence-exit-thresh for the zone exit threshold, in
meters.
________
/ \______
/ ET \ XT
/<----> \<---->
-----------\------E-----------|------X-----------> Router
\ / movement
/ Zone Z |
\ ___ / ET: Enter threshold distance
\ _/ \___/ XT: Exit threshold distance
\___/ E: Position for enter event into Z
X: Position for exit event out of ZIf the geofence-enter-thresh and
geofence-exit-thresh properties are not
specified for a geofence-zone, a minimal default of
10 meters is used. An example using a Feature
as a geofencing zone is:
{
"type": "Feature",
"properties": {
"geofence-zone": "CH",
"geofence-enter-thresh": 50,
"geofence-exit-thresh": 100
},
"geometry": {
"type": "Polygon",
"coordinates": [ ... ]
}
}A geofencing zone can be a Polygon or a
MultiPolygon Feature to geofence the router
position to a complex area. Alternatively, geofencing can be based on
Point, MultiPoint, LineString or
MultiLineString geometries to check if the router position
is near to such a geometry. This is useful for geofencing
roads, tracks or borders, for example. The distance that is considered
near to a geometry is defined in a geofence-near
property, defining the distance in meters, defaulting to 50
meters. If a non-polygon geometry has a geofence-zone,
geofencing uses such a near calculation, considering the
geofence-enter/exit-thresh properties.
Zone Y (LineString)
\
N \ N
<-------->|<-------->
ET | XT
<----> | <---->
------------E---|----------------X-----------> Router
| movement
\
\_____ N: Configured nearing distance
ET: Enter threshold distance
XT: Exit threshold distance
E: Position for enter event near Y
X: Position for exit event near YIf a router not near a geometry moves towards it, an enter event to the geometry is raised if the distance to the geometry is less than the nearing distance minus the enter threshold. When currently near to a geometry, the exit event is raised when the distance to the geometry gets larger than the nearing distance plus the exit threshold.
Geodata can be created with a wide variety of tools and exported to a GeoJSON document. Many free online geodata editors exist, one recommendation is uMap. It allows creating (multi-)polygons, optionally with holes, and can export to GeoJSON. Unfortunately there is no convenient way to edit geofencing metadata, which must be added manually in the exported GeoJSON file.
An other online tool for creating and visualizing GeoJSON files is geojson.io. While it has fewer options for creating complex polygons, it provides a user friendly way to append the polygon metadata required for geofencing.