Document safety app

[pahmann]

Within meta-elisa we pull the safety app, but we have not properly documented how it works, for which reason we patch the cluster-demo from AGL to interact with CAN signals, etc.

[pahmann]

@gabpaoloni I assume wg-architecture already has a lot of understanding about the safety app and can support us in documenting it properly.

[pahmann]

The current readme mentions "Intermediary repo for the AGL cluster demo safety app, until meta-elisa is restructured" which is not correct. The current way is good. So we can remove this sentence and add description of the safety app to the readme.md

[pahmann]

Consider the update in the bitbake recipe as well when cleaning up here: elisa-tech/meta-elisa#38

[pahmann]

From tools meeting with @sudipm-mukherjee some first notes about the safety-app for proper documentation.

Safety-signal-source.c is getting the information from control-app.c. It is continuously sending the 6 byte message to safety-app.c.
First 5 bytes (0 to 4) is the information and 6th byte is for parity.

control-app.c will provide the screen and command line menu for interacting with the named pipe. It takes the input from keyboard which state to trigger. Once it gets the information it sends it to Safety-signal-source.c.

safety-app.c is there to perform the end to end (E2E) check. It checks the message from Safety-signal-source.c for consistency. It checks parity of the messages received. 6th byte is the parity.
Safety-app calculates the parity. In case safety-app is not feed or in case the parity is corrupted the safe state (which means watchdog) is triggered. Triggering the watchdog means that it is no longer pet.

Corrupt message

corrupt message: safety control informs safety-signal-source which corrupts the message to safety-app which triggers the safe state.
If you do a corrupt message. In safety-signal-source will just send a random number. It can be seen here: Where https://github.com/elisa-tech/wg-automotive-safety-app/blob/main/Safety-signal-source.c#L79 calls the corrupt message it becomes visible in
https://github.com/elisa-tech/wg-automotive-safety-app/blob/main/safety-app.c#L95

system("cansend can0 021#0000000000000080");
write_wdt = false;

Danger sign is sent

Drop message

If the flag is set it will not send the message.
https://github.com/elisa-tech/wg-automotive-safety-app/blob/main/Safety-signal-source.c#L87
You will not see the danger sign, just the log is updated. There is no safe-state triggered in this case.

Trigger safe staste

safety-signal-source will send a different CAN signal. The meter will not be displayed anymore. This is just an optical trick to differentiate it from the corrupt message.
Reboot is triggered in this case.
https://github.com/elisa-tech/wg-automotive-safety-app/blob/main/safety-app.c#L95

Some remarks

• Only the 3 error messages are sent in case something unexpected happens. For other cases there is an integer counter, which can result in an overflow. The overflow is not checked, as this is not an issue for the demo implementation.
• We send message once per second https://github.com/elisa-tech/wg-automotive-safety-app/blob/main/Safety-signal-source.c#L93. Which also means the WDT timeout is set larger 1 second. This is not the realistic timer for final implementation, which will be shorter duration (e.g. 200ms).
• We use a random number for a corrupt message. So actually the random number could end up as the original parity. It is very unlikely, but could happen. This is also given due to the nature of hte demo state and not making it a real application.
• The WDT timeout is set to 10. Details of meaning need to be clarified.

[pahmann]

Watchdog details and drop message behaviour needs to be clarified with @Jochen-Kall

[pahmann]

Feedback from @Jochen-Kall for some of the requests

Setting the watchog to 10 is an arbitrary value. We chose it large/high for demonstration purposes. Also there was the precision issue. If recalled correctly the watchdog implementation originated in the field of telecommunication infrastructure, and thus was never designed for the tight timings of the automotive use cases (meaning ms).

The fault injection modes were designed to trigger the according fault detection and reaction

• Drop message -> detect by watchdog
• Corrupt message -> detect by crc check
• Delay message -> It was not implement explicitly, but the handling is the same as dropped message, the watchdog reacts to not getting a pet in time.

For the "request safe state" the idea was, that an outside source might request the save state explicitly, even if the cluster display itself is working correctly, thus the option to demonstrate like that.

(Jochen also confirmed, that it was right to keep it in the repo as it is and not putting it to the meta-elisa. This was already changed with a previous PR.)