miniHIL UserGuide

Motivation

The text logging allows to write textual messages to the PC similar to printf. This helps to debug the miniHIL application or to output any interesting information.

Pre-requisites

Connect to USB-1 at miniHIL board
Open the miniHIL Dashboard and connect to the miniHIL board

Logging in ROOM

The protocol for logging is PLogger. The usage is depicted in the example below:

examples/logging.room

import etrice.api.logger.PLogger

ActorClass ALoggingExample {
	Structure {
		SAP logger: PLogger 
		SAP timer: PTimer
		Attribute counter: int32
	}
	Behavior {
		StateMachine {
			State state0
			Transition init0: initial -> state0 {
				action '''
					timer.startTimer(1000);
				'''
			}
			Transition tr0: state0 -> state0 {
				triggers {
					<timeout: timer>
				}
				action '''
					logger.log("Hello from ALoggingExample"); 
					logger.logF("This is the %d-th message", ++counter);
				'''
			}
		}
	}
}

	Declare a SAP of protocol PLogger
	Call one of the port operations

Log message will only be sent if there is an actual connection - otherwise they are dropped. This can also happen to messages that are sent too early, e.g. on startup or initial transition. In addition, the simulator mcu has to be flashed and running, in particular not suspended on a breakpoint.

Activate the logging example

The example above is available from

MiniHilProject_Examples\MiniHilProject\model-user\examples\logging.room

To try it do the following steps:

Open the file

MiniHilProject_Examples\MiniHilProject\model-user\MiniHilProject.room

Enable the example actor reference by removing uncommenting it
MiniHilProject.room
```
//
//  Logging HowTo
//
ActorRef loggingExample : ALoggingExample
```
After building and flashing the example project, you should see the output in the GUI text console:

Logging in CaGe files

In CaGe files two c functions may be used within target code blocks: TestLog_testTrace(const char* format, …) and TestLog_println(const char* format, …).

Both functions internally use printf to print the passed parameters.

TestLog_println(const char* format, …) prints the string into the text log.

TestLog_testTrace(const char* format, …) prints the string into the text log and into the generated CaGe traces.

Logging to the CaGe trace from ROOM Actors

In addition to text logging, test-related log entries can be added to the CaGe trace from ROOM actors using the PCageTracing protocol. This allows test logs to be displayed in the GUI text console and captured in the CaGe trace simultaneously.

The usage is depicted in the example below:

examples/tracing.room

import cage.trace.*
import examples.cageTracing.cageTracingTestActor

ProtocolClass PingPongProtocol {
	incoming {
		Message ping()
	}
	outgoing {
		Message pong()
	}	
}

ActorClass ATraceWritingActor {
       Interface {
           Port pingPongPort: PingPongProtocol
       }
	Structure {
           external Port pingPongPort
           
           // SAPs are used to access the test log and the cage tracing functionality
		SAP tracer: PCageTracing 
	}
	Behavior {
		StateMachine {
			State ready
			Transition init0: initial -> ready
			Transition tr0: ready -> ready {
				triggers {
					<ping: pingPongPort>
				}
				action '''
					tracer.logTrace("Hello from ATracingExample"); 
					char logBuffer[110];
					snprintf(logBuffer, 110, "Cage Traces are stored in the HilSimGUI/build/test/cageTraces folder after the execution of the tests.");
					tracer.logTrace(logBuffer);
                       pingPongPort.pong();
				'''
			}
		}
	}
}

	Declare a SAP of protocol PCageTracing
	Call the `logTrace` operation

The messages will only be sent if there is a connection. If messages are sent too early, such as during the initial transition, they might not appear.

Activate the logging to the CaGe trace example

The example is available in the following path. To activate the example please open the file:
```
MiniHilProject_Examples\MiniHilProject\model-user\MiniHilProject.room
```
Enable the tracing example by uncomment the example actor reference:
MiniHilProject.room
```
//
//  Cage Tracing HowTo
//
ActorRef tracingExample : ATracingExample
```
After building and flashing the project, you should see trace messages in both the text log and generated CaGe traces. If you run the exampleSuit test, the cage traces will be written to the folder:
```
HilSimGUI\build\tests\cageTraces
```

Writing message into the cage trace

Summary

Connect to USB-1 at the miniHIL board.
Use the PLogger protocol to perform text logging and call its logging operations to output messages to the text log.
Use the PCageTracing protocol and call its operations to capture to both the text log and generated CaGe traces.
The output for both examples will be displayed in the GUI text console, for the PCageTracing protocol also being captured in the generated CaGe traces.

Text Logging