Differences

This shows you the differences between two versions of the page.

--- tools:monitor:start [2018/05/31 11:44] – [How to Get Hold of a Periodic] graf
+++ tools:monitor:start [2020/08/12 10:02] (current) – [Measuring a Single Block] ursgraf
@@ Line 2: / Line 2: @@
 It is often desirable to determine whether realtime performance criteria are met or how long a certain time domain takes to run. For this purpose each time domain as well as the safety system comprises of a dedicated timer.
 ===== How the Timer Works =====
-The timer function is included in every periodic object. It registers the system time each time the executor executes this particular task (//tick()//). When the task is done, the system time is registered again (//tock()//). The timer keeps track of the previous measurement and calculates the run time in between consecutive runs as well as period and jitter.
+The timer is implemented in ''eeros::PeriodicFunction'' and is included in every periodic object. It registers the system time each time the executor executes this particular task (//tick()//). When the task is done, the system time is registered again (//tock()//). The timer keeps track of the previous measurement and calculates the run time in between consecutive runs as well as period and jitter.
   * run time: tock() - tick()
   * period: tick()[t=n] - tick()[t=n-1]
   * jitter: |actual period - set period|
-Of these three measurements the minimal value, maximal value, mean value and the variance are calculated.
+Of these three measurements the minimal value, maximal value, mean value and the variance are calculated. All times are given in ns.
 <code cpp>
@@ Line 19: / Line 19: @@
 ===== How to use the Timer =====
-The timer measurements can be used to monitor execution timing and notably realtime performance. After the creation of a periodic task, a monitor function can be added before the task is added to the ''Executor''.
+The timer measurements can be used to monitor execution timing and notably realtime performance. After the creation of a periodic task, a monitor function can be added before the task is added to the ''Executor''. \\
+IMPORTANT Add the monitor function before adding the periodic task to the executor.
 <code cpp>
 eeros::task::Periodic periodic("control system", dt, timedomain);  // create a periodic with a given period
 // the periodic will run a given time domain
-periodic.monitors.push_back([&](PeriodicCounter &c, Logger<LogWriter> &log) {
+periodic.monitors.push_back([&](PeriodicCounter &c, Logger &log) {
   log.info() << "period max: " << c.period.max << ", run mean: " << c.run.mean;
 });
@@ Line 30: / Line 31: @@
 eeros::Executor::instance().add(periodic);
 </code>
-Each time the periodic runs it will log the maximum period and the mean run time. This is the time the execution of the periodic takes.
+Each time the periodic runs it will log the maximum period and the mean run time. This is the time the periodic needs to be executed.
 ===== Reducing the Output Frequency =====
 If the periodic has a small cycle time (less than 1 second) it is not advisable to update the log output each time. In the following example the output is only updated after 1000 cycles. Depending on the cycle time, this number can be adjusted.
@@ Line 59: / Line 60: @@
 </code>
-===== Headline =====
+===== Default Monitor =====
+You can add a default monitor to a periodic. Such a default monitor will log a message (on level WARN) as soon as the maximum period exceeds a the envisaged period more than a certain limit. The default value for this limit is 5%.
+<code cpp>
+eeros::task::Periodic per1("per1",0.001, td1);
+per1.addDefaultMonitor();  // warn if the period exceeds 1.05ms
+eeros::task::Periodic per2("per2",0.001, td2);
+per2.addDefaultMonitor(0.02);  // warn if the period exceeds 1.02ms
+</code>
+===== Using the Timer to Change Safety Levels =====
+For a certain type of safety critical robots, it is desirable to change into a safe level in case of the jitter in periodicity of a time domain or the safety system itself exceeds a certain level. Add a monitor function, which periodically checks for the critical maximum value and triggers a specific safety event.
+<code cpp>
+periodic.monitors.push_back([=](PeriodicCounter &c, Logger<LogWriter> &log) {
+  if (c.period.max >= dt) safetySystem.triggerEvent(myEvent);
+});
+</code>
-Each periodic has a built in default monitor. This default monitor will output a message as soon as
 ===== Accuracy of the Measurement =====
@@ Line 74: / Line 90: @@
 With this command it is possible to measure for multiple hours or even multiple days.
-executor.getMainTask()->monitors.push_back([](eeros::PeriodicCounter &c, Logger &log){
+===== Measuring a Single Block =====
-		static int ticks = 0;
+Especially when implementing your own blocks one wishes to measure the time it takes to run it. This can be very useful for blocks with complex algorithms or in cases your timedomain with many blocks takes to much time to run and you want to pinpoint the culprit. For this purpose add a ''PeriodicCounter'' to the block and add //tick()// and //tock()// to its run method.
-		if (++ticks < 200) return;
+<code cpp>
-		ticks = 0;
+#include <eeros/core/PeriodicCounter.hpp>   // add include file
-		log.warn() << "ss: period max: " << c.period.max << "   period min: " << c.period.min << "   period mean: " << c.period.mean;
-		c.reset();
+eeros::PeriodicCounter pc;                  // add periodic counter object to your block
-	});
+virtual void run() {
+  pc.tick();                                // start ...
+  ... // algorithm
+  pc.tock();                                // ... and stop the timer
+</code>
+You can then periodically print the mean and maximum run time.