This interactive document describes how to interact with the unified interface for *Large-Scale Metrology* devices which was
developed during the LaVA project. The interface itself is based on the *Sensor Interfacing Language (SOIL)* which in turns was
developed in the Cluster of Excellence *Internet of Production*.
The chosen approach decouples the unified modeling of different Large-Scale Metrology systems, the general information model for sensor
systems, and the communication using standardized protocols. These three topics will be briefly covered here, for more conceptual details, the reader
is kindly asked to refer to [https://doi.org/10.18154/RWTH-2021-10238](https://doi.org/10.18154/RWTH-2021-10238).
## Sensor Interfacing Language (SOIL)
To further reduce complexity and provide concise representations, a division of resources into Objects (OBJ), Functions
(FUN), Variables (VAR) and Parameters (PAR) only offering specific subsets is proposed:
* **Objects** provide an object-oriented data view and in combination with structured
identifiers are the only resources allowed to posses subordinate child items.
* **Variables** encapsulate access to data with physical origin, e.g. measurements, which
are naturally read-only.
* **Parameters** separately encode read and potential
write access to primitive data fields.
* **Functions** are resources that are callable with a set of argument and return values, leading to a function invocation on the resource.
The overall organization of SOIL is hierarchial, using locally unique identifiers (uuid) which can be concatenated to a fully
qualified identifier, which e.g. serves as URL. Only Objects are allowed to have child items. Each resource types comes
with a defined set of metadata to ensure high data quality, especially for long-term objectives. The metadata fields are described in the
schema section of this document.
## Modeling of Large-Scale Metrology Systems
For the unified modeling of Large-Sale Metrology systems, a functional view from an application's perspective
was adopted over a physical view exactly representing the embodiement of the system. Hence, a Large-Scale Metrology System is modeled as:
* A set of **base stations**, which are fixed and have an enabling role. In case of a centralized system, there
is exactly one base station. Examples are a laser tracker head, indoor GPS transmitters, OPTIMUM Heads or distributed cameras.
A fixed-type kinematic, as e.g. for CMMs, is also interpreted as base station.
* A set of **mobile entities**, which corresponds to the targets whose positions are measured. In the information model,
the measurement of the current position is always retrieved through the corresponding mobile entity, even if
it is effectively measured at the base or through multilateration or multiangulation. Examples are SMRs, n=2 spheres
indoor GPS PCEs or photogrammetric targets.
This approach organizes the entire information model under four elements:
* **Root** The root object is the entry point for the Large-Scale Metrology as general device, accomodating elements
which are rather general (e.g. Startup and Shutdown)
* **LSM** The Large-Sale Metrology (LSM) objects represents the model briefly described above. It can be integrated
into more complex models and therefore is a node on its own.
* **Entity** For each mobile entity, an own object containing the relevant functions, parameters and variables is present.
Each entity has an *uuid* to address it.
* **Base** For each base station, an own object containing the relevant functions, parameters and variables is present.
Each entity has an *uuid* to address it.
These elements are used as tags to organize the description below.
## REST and MQTT Access
SOIL is protocol-agnostic by definition, i.e. it may be mapped to HTTP/REST, MQTT, OPC UA, grpc.io and many more.
This document describes the mapping to HTTP/REST and MQTT using JSON for serialization. The HTTP Verbs are translated to
READ, UPDATE, CREATE, REMOVE and INVOKE to act on the resources. The elements are addressed through their FQID as URL or MQTT topic,
while the FQIDs may be prepended with global prefixes. The significance of the individual methods as described under the **Any** tag below
and not repeated here. For using MQTT, the device's implementation must connect to broker provided outside it scope to which the user can subscribe.
The serialization is expected to be identical both via HTTP/REST and MQTT and to follow the schemas provided in this document. The minimum requirement for
an MQTT-enabled device is to publish the updates to its Variables, while it is recommended to also publish Parameter updates.
## Testing
This OpenAPI scheme can be used as a client to interact with the HTTP/REST part of a Large-Scale Metrology system's interface.
The reader is kindly referred to open source tools available for this purpose.
Currently, the provision of virtual Large-Scale Metrology device at [https://iot.wzl-mq.rwth-aachen.de/public/SOIL/devices/LSM/](https://iot.wzl-mq.rwth-aachen.de/public/SOIL/devices/LSM/)
is planned. As an alternative, testing with a local implementation (e.g. at [http://localhost:8000/](http://localhost:8000/)) is possible.
### Acknowledgements
The authors acknowledge funding from the LaVA project (Large Volume Applications, contract 17IND03 of the
European Metrology Programme for Innovation and Research EMPIR). The EMPIR initiative is co-funded by
the European Union's Horizon 2020 research and innovation programme and the EMPIR Participating States.
The authors would like to thank the German Research Foundation DFG for the kind support within the Cluster
of Excellence Internet of Production - Project-ID: 390621612.
