diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..de0ea7a92b590eb8dac1e193b19146c41b4b8a12 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# qronOS Observer Abstractions -- Execution Time Benchmarks + +This repository contains the sources for the qronOS state abstractions execution time benchmarks presented in [1]: we compare the execution time of our approach against the update steps of robust state estimation approaches from the literature, namely a Luenberger observer described by Dkhil et al. [2] and a Kalman filter as presented by Noack et al. [3]. + + +## Requirements + +This section states the requirements for reproducing the experiment. + + +### Hardware + +All tests were carried out on an STM32F411E-DISCO board [4], which contains an STlink programmer. We replaced the latter's firmware with the Black Magic Probe [5]. However, any way to flash the ELF binary onto the main STM32F4 controller is fine. + + +### Software + +These are the prerequisites on the software side: + +- arm-none-eabi-gcc toolchain (We used version 12.2.0. Expect different results for other versions.) +- arm-none-eabi-newlib toolchain (We used version 4.3.0. Expect different results for other versions.) +- arm-none-eabi-binutils toolchain (We used version 2.39. Expect different results for other versions.) +- arm-none-eabi-gdb +- git +- make +- python3 (We used version 3.7.10. Expect problems when using another version and use, e.g., pyenv [6]) +- doxygen (Only for building the documentation) + + +## Usage + +```sh +# Initializes repository once +git submodule init +git submodule update --recursive +pipenv install +``` + +```sh +# Generates Doxygen documentation under $PWD/doc/html/index.html +make doc +``` + +```sh +# Compile elf binary $PWD/build/state_abstractions.elf for STM32F411E-DISCO board +make +``` + +```sh +# Flash using Black Magic Probe when udev rules are set up correctly [5]. +# Please adjust according to your programmer (e.g., the stock STlink). +make flash +``` + +```sh +# Retrieve data after connecting the user USB and assuming /dev/ttyACM2 is the serial device (inf4@FAU State Abstractions Execution Time Benchmark) +pipenv run scripts/readout.sh /dev/ttyACM2 2000000 result.json +``` + +```sh +# Run evaluation script and store files under $PWD/results +pipenv run python scripts/evaluate.py result.json results +``` + + +## Licensing + +The sources packaged here are distributed under the GPLv3 license, see COPYING. Further, the file DEPENDENCIES.md lists the third-party dependencies used by this package and their license texts. + + + +## Literature + +[1] Tim Rheinfels, Maximilian Gaukler, and Peter Ulbrich: "A New Perspective on Criticality: Efficient State Abstraction and Runtime Monitoring of Mixed-Criticality Real-time Control Systems". ECRTS'23. DOI: 10.4230/LIPIcs.ECRTS.2023.16. + +[2] Monia Dkhil et al.: "Interval Estimation for Discrete-Time Switched Linear Systems Based on $L_\infty$ Observer and Ellipsoid Analysis". IEEE Control Systems Letters, 5(1):13-–18, 2021. + +[3] Benjamin Noack et al.: "State estimation for ellipsoidally constrained dynamic systems with set-membership pseudo measurements". In Proceedings of the IEEE International Conference on Multisensor Fusion and Integration for Intelligent Systems (MFI), pages 297-–302, 2015. + +[4] STMicroelectronics: "Discovery kit with STM32F411VE MCU ". https://www.st.com/en/evaluation-tools/32f411ediscovery.html. Accessed 22. March 2023. + +[5] Black Magic Debug documentation: FAQ "It’s annoying to look up an always-changing device name on Linux.", https://black-magic.org/knowledge/faq.html. Accessed 22. March 2023. + +[6] pyenv. https://github.com/pyenv/pyenv. Accessed 22. March 2023.