MoonLight: A Lightweight Tool for Monitoring Spatio-Temporal Properties

We present MoonLight, a tool for monitoring temporal and spatio-temporal properties of mobile and spatially distributed cyber-physical systems (CPS). In the proposed framework, space is represented as a weighted graph, describing the topological configurations in which the single CPS entities (nodes of the graph) are arranged. Both nodes and edges have attributes modelling physical and logical quantities that can change in time. MoonLight is implemented in Java and supports the monitoring of Spatio-Temporal Reach and Escape Logic (STREL). MoonLight can be used as a standalone command line tool, as a Java API, or via Matlab interface. We provide here some examples using the Matlab interface and we evaluate the tool performance also by comparing with other tools specialized in monitoring only temporal properties.


Introduction
Cyber-physical systems [24] (CPS) are a widespread class of technological artefacts that include contact tracing devices, self-driving cars, mobile ad-hoc sensor networks and smart cities. CPS are controlled by a computational device and interact within the physical space.As such, they are described by discrete states, controlling actuators, and continuous quantities, measured by sensors, which can both change in time.CPS are arranged in spatial configurations that can be static or dynamic.Their network connectivity can typically change in time.
A fundamental task in engineering CPS is monitoring their behaviors, specified in a suitable formal language, such as Signal Temporal Logic (STL) [19,18].Monitoring can be performed on a deployed system or on simulations of a model, as typically done in the design phase to test different initial conditions, parameters and inputs [4,7].Monitoring a trace returns either a Boolean value, witnessing whether the requirement is satisfied or not, or a quantitative value, for instance a real-value indicating how much the specification is satisfied or violated according to a chosen notion of distance [10,14,5,13,25].
Current tools available for monitoring formal specifications are restricted to temporal properties, mostly ignoring the spatial dimension of CPS [4,7].Our contribution.We present MoonLight, a lightweight tool for monitoring temporal and spatio-temporal properties of spatially distributed CPS, which can move in space and change their connectivity (mobile CPS).MoonLight is implemented in Java and supports monitoring of Spatio-Temporal Reach and Escape Logic (STREL), a spatio-temporal specification language introduced in [6].STREL extends STL [19,18] with two main spatial operators reach and escape from which is possible to derive many other spatial operators (e.g., everywhere, somewhere and surround ).Our implementation is available at: https://github.com/MoonLightSuite/MoonLight.MoonLight can be used: as a standalone command line tool, as a Java API, or via Matlab ™ interface.In this paper, we describe the usage of MoonLight via Matlab ™ interface because several CPS models and analysis tools are available for this framework.We refer to the documentation for the other usage possibilities.
MoonLight takes as input a STREL formula and a spatio-temporal trajectory.Space is represented as a weighted graph, describing the topological configurations in which the CPS entities are arranged.Nodes represent single entities.Both nodes and edges have attributes modelling physical and logical quantities that can change in time.Therefore, a spatio-temporal signal, in the most general case, is described by a sequence of such weighted graphs, allowing both spatial arrangement and attributes to change in time.MoonLight monitors such a sequence of graphs with respect to a STREL formula, returning a Boolean or a quantitative verdict, according to the semantic rules of [6].

Related work.
Monitoring tools for CPS are generally agnostic of the spatial configuration of the entities such as sensors and computational units.They are limited to monitor temporal specifications over time series of data.Examples are S-Taliro [2] for Metric Temporal Logic (MTL) [15], R2U2 [20] for Mission Linear Temporal Logic (MLTL) [20], AMT [23] and Breach [9] for Signal Temporal Logic (STL) [19,18], TeSSLa [16] and RTLola [8] for temporal stream-based specification languages and Montre [26] for Timed Regular Expressions (TRE) [3].However, temporal specification languages are not always expressive enough to capture the rich and complex spatio-temporal patterns that CPS display.For this reason, many researchers have extended temporal specification languages such as STL to express also spatial requirements.Examples include Spatial-Temporal Logic (SpaTeL) [11], the Signal Spatio-Temporal Logic (SSTL) [21], the Spatial Aggregation Signal Temporal Logic (SaSTL) [17] and STREL [6].Despite many developed prototypes built more for demonstration purposes rather than becoming usable tools, we are aware only about jSSTL [22] as offline monitoring tool for spatio-temporal properties.jSSTL [22] supports SSTL and operates over a static topological space, while the tool proposed in this paper can also monitor dynamical locations, such as in mobile wireless sensor networks.

MoonLight in a nutshell
The main component of MoonLight is its Java Application Programming Interface (API): a set of specialized classes and interfaces to manage data domains and signals, to represent spatial models that can evolve in time, to monitor temporal and spatio-temporal properties and to manage input/output to/from generic data sources.Moreover, it also contains a compiler that generates the necessary Java classes for monitoring from a MoonLight script.The latter are built and dynamically loaded to enable the monitoring of the specified properties.
MoonLight provides also an interface that enables the integration of its monitoring features in Matlab™.We now first introduce a simple running example to guide the reader on how to monitor spatial-temporal properties.Then, we present a MoonLight script together with a gentle introduction of formulas semantics.Finally, we show how MoonLight can be used in the Matlab™ environment.

Running Example
A running example is used to describe the behaviour of our tool.We consider a wireless ad-hoc sensor network [1] consisting of three different types of mobile device: coordinator, router, end-device.For each network, there is only one coordinator that is responsible to initialize the network.The routers are responsible for passing data on from other devices and they establish a mesh network of intermediate devices to reach more distant ones.The end-devices can only communicate with router or coordinator, and they cannot relay data from other devices.We assume that all the devices are battery-powered and they are equipped with sensors enabling them to measure and collect data from the environment (e.g.pollution, temperature, etc.).
Fig. 1 illustrates a network with 10 nodes (1 coordinator (C) in violet, 2 routers (R) in cyan and 7 end devices (E) in yellow).The nodes are distributed in an Euclidean space, i.e. axis represent their coordinates in the space.The edges represent the connectivity graph of the network, expressing the fact that two devices can directly interact (i.e. they are within their communication range).
In MoonLight, the space is modelled as a graph, where each node represents a location containing mixed-analog signals while each edge represents a topological relation.Edges are labelled with one or more quantitative attributes describing additional information about the spatial structure.In our example, the sensor network is our graph, each device represents a node/location of the network and contains three signals evolving in time: the type of node (coordinator, router, end-device), the level of battery, and the temperature.The edges are labelled with both their Euclidean distance and with the integer value 1.This last value is used to compute the hop (shortest path) count between two nodes, that is the number of intermediate network nodes through which data must pass between source node and target one.
Moonlight evaluates properties specified in the linear-time spatio-temporal logic STREL over spatio-temporal signals, i.e. functions mapping each node and time instant into a vector of values, describing the internal state of each location.In the following, we show how to use the MoonLight scripting language to specify spatio-temporal properties and how to monitor them.

MoonLight Script
A monitor in MoonLight is specified via a MoonLight script.Fig. 3 reportes an example that specifies the necessary information to instrument a monitor for our sensor network.The script (line 1) starts with the definition of the domains of input signal.We recall that STREL is interpreted over spatio-temporal signals.In our scenario, these values are: the type of node, the temperature level and the battery level.As domains, the node type is represented by an integer (int) and the battery and temperature by real values (real).Spatial structures in STREL can change over time.This enables the modelling of the mobile network of sensors as in our example by updating edges and edge labels.The edges can have more than one label with different domains.These are specified in line 2 of our example.In this case we have two labels: hop having type int domain, and dist with type real.Note that, if one is only interested in temporal properties, this part is omitted in the script.
MoonLight, like STREL, supports different semantics for monitoring.A user can specify the desired one by indicating the specific monitoring domain (see line 3).Currently, MoonLight supports qualitative (boolean) and quantitative (minmax) semantics of STREL.
After this initial declaration, the script contains the list of formulas that can be monitored (see lines [4][5][6].Formulas can have parameters that are instantiated when monitoring is performed.A formula can be used within another formula. The syntax of STREL is summarized in Fig. 4. The atomic expression consists of Boolean expressions on signal variables like, for instance, (battery > 0.5) or (nodeType == 2).As expected, the interpretation of atomic formulas depends on the domain of the monitoring.
Formulas are built by using standard Boolean operators (negation !, conjunction &, disjunction |, and implication =>) together with a set of temporal and spatial modalities.
Temporal properties are specified via the standard until and since operators (see e.g.[19,18]) from which we can derive the future eventually and globally operators and the corresponding past variants, once and historically.All these operators may take an interval of the form [a,b], with a,b ∈ R ≥0 , to define where the property should be evaluated.The interval can be omitted in case of unbounded temporal operators.
Spatial modalities, instead, are reach and escape operators, and the derivable operators somewhere and everywhere.All these operators may be decorated with a distance interval [a,b] and a distance expression.The distance expres-sion consists of an expression that is used to compute the length of an edge.If omitted, the real value 1.0 is used.P1 holds if from a node of type 3 (an end device), we can reach a node of type 1 or 2 (a coordinator or a router ), following a path in the spatial graph such that the hop distance along this path (i.e. its number of edges) is not bigger than 1.This property specifies that "end device should be directly connected to a router or the coordinator".
The reach operator allows us to express properties related to the existence of a path.The other operator of STREL, escape, can be used to express the ability of move away from a given point.Let us consider the following property: P2 = escape(hop) [5,inf] (battery > 0.5) P2 states that from a given location, we can find a path of (hop) length at least 5 such that all nodes along the path have a battery level greater than 0.5, i.e. that a message will be forwarded along a connection with no risk of power failure.
To specify properties around a given location, operators somewhere and everywhere can be used.For instance, we can consider the following property: P3 = somewhere(dist)[0,250] (battery > 0.5)) P3 is satisfied (at a given location) whenever there is a node at a distance between 0 and 250 having a battery greater than 0.5.In this formula the distance is computed by summing the value dist of traversed edges.The everywhere operators works in a similar way, however it requires that its subformula holds in all nodes satisfying the distance constraints.
Note that both reach and escape are existential operators, as they predicate the existence of a path with certain properties, and all the properties are interpreted at a given location, at a given time.Temporal and spatial operators can be nested as for example: PT1 = (battery <= 0.5)reach(hop)[0, 10] eventually(battery > 0.5) PT1 holds if each node can reach a node in less than 10 hops where the battery is greater than 0.5 in at least one time step in the next 5 time units.We will show a second example later, but for more formal details and examples about STREL, we refer to [6] and the to tool documentation.

Using MoonLight in Matlab ™
To use MoonLight in Matlab ™ one has just to run the installation script (named install.m)distributed with MoonLight.A detailed description of the installation process is available at the tool web site.After this installation, MoonLight becomes available to be used in the Matlab ™ environment.In Fig. 5 a simple example is presented showing the main features of this module.The function ScriptLoader.loadFromFileloads the script.It takes as parameter the file name containing the script to load (see line 1).After this operation is performed, a Java class is generated from the script and dynamically loaded.A reference to this object is returned to be used later.In the provided code, the script of Fig. 3 is loaded from the file sensorNetMonitorScript.
After a script is loaded, the monitors defined inside can be instantiated.In the example of Fig. 5 the monitor associated with formula named Ppar is retrieved (line 2).When we have the monitor we can use it to verify the satisfaction of the property over a given spatio-temporal signal.This is done by invoking the method monitor of the just loaded monitor.This function takes the following parameters: -spatialModel is an array of Matlab ™ graph structures specifying the spatial structure at each point in time; in the sensor network example, for each time step i, spatialModel{i}.Edges represents the adjacent list of the graph.This input is omitted when purely temporal models are considered.time is an array of time points at which observations are provided.
values is a map (a cell array), with a cell for each node.In each cell, there is a matrix n×m where each row represents the values of the signals at the time points specified by time (with n equal to the number of time points and m the number of the considered signals); in the sensor network example, each node has a 3 signals representing the node's type, battery, and temperature.We represent different types of nodes using integer numbers, 1, 2, and 3 to represents coordinator, router, and end-device respectively.This input is a simple matrix in case of purely temporal models.param is used to instantiate the parameter k of formula Ppar.
The output br from line 4 in Fig. 5 is similar to the input signal.It is a map that associates a Boolean-value (for the Boolean semantics) or a real-value signal (for the quantitative semantics) with each node, i.e. the Boolean or quantitative satisfaction at each time in each node.Finally, line 5 shows how to set the quantitative semantics ( in the Boolean case: moonlightScript.setBooleanDomain()).
In Fig. 2 (left), we can see the Boolean satisfaction at time zero of each node with respect the formula P1 of our script example in Fig 3 .The blue nodes (marked with a V) on the plot of Fig. 2(left) correspond to the nodes that satisfies the property, i.e. the end devices that reach a router or a coordinator with at most 1 hop.Fig. 2 (right) shows the satisfaction of formula: P4 holds only in the nodes connected directly to the coordinator or to routers that can reach the coordinator through a maximum of four other routers.We can see that nodes 3, 4, 5 and 9 satisfy P1 but not P4.Property PT2 = globally P4 can be used to check that P4 is true in each time step.

Temporal evaluation: monitoring Signal Temporal Logic
We consider the Automatic Transmission example in [12].This benchmark consists of a Matlab ™/Simulink deterministic model of an automatic transmission controller.The model has two inputs (the throttle and the break) and two outputs: the speed of the engine ω (RPM) and the speed of the vehicle v (mph).We monitor the robustness of four requirements in [12]: (R1) The engine speed never reaches ω: globally (ω < ω) (R2) The engine and the vehicle speed never reaches ω and v resp.: (R3) If engine speed is always less than ω, then vehicle speed can not exceed v in less than T sec.: !(eventually [0, T] (v > v) & globally (ω < ω)) (R4) Within T sec. the vehicle speed is above v and from that point on the engine speed is always less than ω: eventually [0,T] We randomly generated 20 different input traces with 6400 samples and another 20 with 12800 samples (0.01 sec. of sampling time).For each input trace, we simulated the model and we monitored the robustness of the four requirements over the outputs by varying the parameters v ∈ {120, 160, 170, 200}, w ∈ {4500, 5000, 5200, 5500} and T ∈ {4, 8, 10, 20}.For a fixed combination of parameters and output traces, we repeated the monitoring experiment 20 times and we considered the mean of the execution times.In Figure 6, we compare the performance of our Moonlight monitors with S-Taliro [2] and Breach [9] using bloxplots representing the quartiles of the execution times distribution for monitoring each requirement with each tool.The graph shows a good performance of Moonlight with respect to the other tools.However, it is important to note that Breach considers piece-wise linear signals and computes the interpolation between two consecutive samples when necessary, while our tool and S-Taliro interpret the signal step-wise.

Spatio-Temporal Evaluation
We evaluate the scalability of the spatial operators in the running example varying the number of nodes of the graph: N = 10, 100, 1000.Note that the number of edges is around 1700 for N = 100 and 8000 for N = 1000.We monitor the Boolean (B) and the quantitative (Q) semantics of the requirements presented in Section 2.2, excluding P1.For the spatio-temporal requirements we consider K time step, for K = 10, 100.We repeat the monitoring experiments 50 times for each N. Table 1 shows the average execution time.For spatial formulas, we can see that formula (P4) performs better than the other two.(P2) is slower because monitoring algorithms of the reach and somewhere are O(n 2 ) i.e. linear in the number of edges and quadratic in the number of vertexes, while the one for escape is O(n 3 ).As expected, the Boolean semantics is faster than the quantitative one: it can reach sooner the fixed point.Formula (P3) is the slowest due to the fact that uses the euclidean distance while formula (P2) and (P4) the lighter hop distance.For spatio-temporal formulas, the reason why (PT1) is much faster than (PT2) is that (PT1) has a temporal subformula, hence the number of time steps can be dramatically reduced before monitoring the spatial part.This does not happen for (PT2), where the operators are inverted.In this case the difference between the two semantics is more evident.For static graphs and properties restricted to everywhere and somewhere spatial modalities, the performances are similar to jSSTL [22,21].Further experiments can be found in the tool release.

Conclusion
MoonLight provides a lightweight and very flexible monitoring tool for temporal and spatio-temporal properties of mobile and spatially arranged CPS.The possibility to use a dedicated Matlab ™ interface enables to easily integrate MoonLight as a component in other tool chains implementing more sophisticated computer-aided verification and synthesis techniques such as falsification analysis and parameter synthesis.In the near future, we plan to add also a Python interface and to extend the tool with new functionalities such as the support parallelized and online monitoring.

Fig. 2 :Fig. 3 :
Fig.2:(left) Boolean satisfaction of formula P1, (blue nodes (V) satisfy the formula), red nodes do not satisfy the formula.(right)Boolean satisfaction of formula P4, (blue nodes (V) satisfy the formula), red nodes do not satisfy the formula.