Skip to content

Project Specification

The project specification is described in the following sections.

Constraints

  • The code delivered to github.com compiles without error and can be flashed to the target device.
  • The program must run without error on the target device.
  • Your Zephyr RTOS workspace uses the T3 topology. Each application (e.g. “Blinky” or “BikeComputer”) is delivered as a separate application using the same manifest. These applications are located at the root of the workspace root folder, in a folder named after the application (like “blinky” or “bike_computer”).
  • The manifest folder is named “manifest-repo”.

Note that any major deviation from these rules may lead to the project not being considered for the lecture grade.

Phase 1: Project infrastructure

  • The project code is based on the Getting Started codelab.
  • The project infrastructure (e.g. tools including precommit) is fully developed and deployed to github, as described in the Improving Software Quality codelab.
  • The test programs developed in the Testing codelab are added to github and the CI/CD pipeline is properly configured. Pipeline jobs run successfully.
  • The folder structure is identical to the one documented in the different codelabs. For instance, the BikeComputer program is located in the “bike_computer” folder at the root of the workspace.

Expected Deliverables

  • Deliverable: Your GitHub repository exists and has been shared. It follows all rules and directives defined under project organization.
  • Deliverable: Your workspace includes the Blinky and the BikeComputer programs.
  • Deliverable: The test programs are added as part of the BikeComputer program under the “bike_computer folder.
  • Deliverable: The Github workflow is configured correctly and runs without error. It includes the build of the “ptr_test” program that you have developed. The “ptr_test” program includes the tests described in the unique_ptr and raw pointers exercises.
  • Deliverable: pre-commit has been configured properly and all pre-commit hooks run successfully. All configuration files have been added to your Github repository.
  • Deliverable: a tag named “Phase-1” is added to your github repository.
  • Important: Code developed for the “BikeComputer part 1 & 2” codelab is NOT part yet of Phase 1. It should be committed and pushed to a separate branch of your Github repository. It is expected that the “main” branch contains only the Phase 1 deliverables.

Phase 2: BikeComputer: Static Cyclic and Event-Driven implementations

  • Phase 2 is based on Phase 1. Every specification below is in addition to Phase 1 specifications. If issues have been added to your github repository, these must be solved and closed as part of Phase 2. Issues will be added at latest 2 weeks prior to the deadline.

  • The BikeComputer program must be delivered in the following versions:

    • static cyclic scheduling: in the “static_scheduling” folder, under the static_scheduling namespace, the BikeSystem class implements static cyclic scheduling using a Super-Loop in the BikeSystem::start() method. This is documented in the BikeComputer part 1 codelab. codelab](../codelabs/bike-computer-part2.md#reduce-cpu-usage-with-sleep-calls-rather-than-busy-wait){target=”blank”}
    • static cyclic scheduling with event handling: in the “static_scheduling_with_event” folder, under the static_scheduling_with_event namespace, the BikeSystem class implements static cyclic scheduling using the TTCE API. It implements event handling using interrupts for the buttons. The behavior is implemented in the BikeSystem::start() method and is documented in the BikeComputer part 2 codelab.
      In this implementation, busy waits are replaced by ThisThread::sleep_for() calls.

Expected Deliverables

  • Deliverable: the README file of the project contains the following information:

    • A short description of the project and of the different phases of the project.
    • For phase 2, a description of the commands used to build the BikeComputer program and to run the associated tests.

  • Deliverable: A diagram showing how tasks are scheduled during one major cycle must be added to your repository and included in the README file.

  • Deliverable: Answers to the question asked in the BikeComputer part I codelab and to the 4 questions asked in the BikeComputer part II codelab are given and documented in the README file of your project.

  • Deliverable: the CPU usage is optimized for every scenario:

    • When polling for button states, busy wait calls are replaced by sleep calls and CPU usage drops from around 99% to around 75%.
    • When implementing periodic tasks by using the TTCE API, CPU usage remains around 75%.
    • When handling buttons with ISR, CPU usage drops from around 75% to a value below 20%.

  • Deliverable: CPU logging must be enabled (if not in test mode).

  • Deliverable: The code has been pushed to the “main” branch of your Github repository. Any code that implements mechanisms that are not part of phase 1 and 2 must be pushed to a different branch. A tag named “Phase-2” is added to your github repository.

  • Deliverable: The code passes all test cases contained in the “bike_computer/tests/bike-computer/” folder successfully. The different test cases are described in the related codelabs.

  • Deliverable: The project can be compiled and run even if the application folder is moved to another location (e.g. to a subfolder in the workspace’s root folder). This means that “CMakeLists.txt” must be written in a way that supports this.

  • Deliverable: bugs from phase 1 are fixed following the guidelines described below.

Bug Fixes from Phase 1

After you delivered the Phase 1 of the project, a few issues related to your project may have been created. These will need to be fixed within Phase 2.

In order to fix issues orderly, the proper way to do so is to create a dedicated branch per issue and only commit the fix(es) related to that issue on that branch. Once the fix is made available and approved, the branch created for that purpose is deleted. Below you find a description how you shall go about it.

Under the github project you created, under Issues, chose the issue you intend to address and :

  1. Define who the issue is assigned to with the field Assignees
  2. Declare what type of issue it is Labels (note: choose the correct type)
  3. Potentially define at what milestone the issue should be fixed. In your case add Phase 2 as milestone
  4. Create a dedicated branch for fixing the particular issue Afterwards you can pick the newly created branch to fix the issues with the following commands 
      git fetch origin
  git checkout 2-testing-guthub-functions-mispelled
  5. Go about fixing the issue and commit to the newly created branch 
      git add README.md
  git commit -m "fix: corrected github mispell"
    Or (as the example was fixed directly in github)

  6. In order to protect the quality of the main branch, usually it is protected. Protected in this context means that no changes are accepted without application of the four eye principle (see at the bottom of the page for a definition).

    In order to activate the protection, you need to :

    • go to your repository Settings and click on Branches
    • there you need to choose Branch protection rules and Add rule
    • once the Add rule page opens up, fill in the information as per the following picture:

  7. When are finished, you should be able to see the following:

  8. Once the fix is available, you shall create a pull request

  9. When you are creating the pull request, you shall define at least one reviewer. Normally, at least the issue issuer shall be invited to review the correction.
  10. After the reviewer has approved the change, for as long as there are no conflicts, the merge can occur into main. It can even do automatically if one chooses so (Enable auto-merge).
  11. When the merge has been done, you should delete the specific branch created for fixing the issue (see Delete branch in picture below)

Note

Make sure you replace 2-testing-guthub-functions-mispelled in the example above with the correct branch when you run above commands.

Warning

Once the branch protection is installed, it would make sense to use dedicated branches also for feature development. Not only is this good practice, but it also works for everyone - contrary to bypassing branch protection that only works for administrators.

Quote - Four eyes principle

The Four eyes principle is a requirement that two individuals approve some action before it can be taken. The Four eyes principle is sometimes called the two-man rule or the two-person rule.

Source: https://cros-legacy.ec.europa.eu/content/four-eyes-principle_en#:~:text=The%20Four%20eyes%20principle%20is,or%20the%20two%2Dperson%20rule

Phase 3: BikeComputer: multi-tasking and bootloader integration

In Phase 3, you must deliver a version of the BikeComputer program with the following requirements:

  • Important note: changes to “bike_computer/src/common” files such as “bike_computer/src/common/task_manager.cpp/hpp”, as notified on the Teams channel, must be integrated. The latest version of zpp_lib must be used.
  • The version of the BikeComputer program delivered in Phase 2 is still functional and existing test programs from Phase 2 all succeed.
  • The multi-tasking version of the BikeComputer described in the Bike computer part 3 codelab is made available and functional.
  • When the BikeComputer program starts, a runtime memory analysis is performed, as described in the memory analysis codelab. The analysis includes both heap and stack analysis and the statistics is printed for all threads created by the program. If not in test mode, a memory analysis is then launched at a regular time interval and the statistics show that the heap and the stack sizes do not grow any more after the warmup phase.
  • The BikeComputer program implements a bootloader as documented in the bootloader codelab. The update process is fully functional based on the following requirements:
    • All configuration changes to the MCUboot and BikeComputer programs related to bootloading are made available in separate configuration files. The configuration files as used for Phase 2 are left unchanged.
    • The MCUboot bootloader application compiles and can be flashed to the board.
    • The “prj_bootloader.conf” and “prj_serial_recovery.conf” files used to configure the bootloader application are delivered at the root of the workspace.
    • The MCUboot bootloader application can be built using the command west build deps/bootloader/mcuboot/boot/zephyr --pristine --extra-conf "full path to prj_serial_recovery.conf". Once the bootloader has been flashed to the board, along with the BikeComputer program that supports theMCUboot application, the BikeComputer program can be updated using the Serial Recovery scenario.
    • The “prj_dfu.conf” file used to configure the BikeComputer program is delivered in the “bike_computer” folder.
    • The BikeComputer program compatible with the bootloader can be built by adding --extra-conf "full path to prj_dfu.conf" to the build command). Once the bootloader compiled with the “prj_bootloader.conf” has been flashed to the board, along with this modified BikeComputer program, the BikeComputer program can be updated the over UART from the BikeComputer application.

Expected Deliverables

  • Deliverable: All requirements described above are met.

  • Deliverable: The deliverables described in the bike computer part 3 codelab are parts of the project deliverables.

  • Deliverable: An answer to the question asked in the bike computer part 3 codelab is given and documented in the README file of your project.

  • Deliverable: The memory footprint of your BikeComputer program has been optimized for both ROM and RAM. Your “README.md” file documents what optimizations have been applied to minimize the ROM footprint, and how the optimal sizes of the stack and heap have been computed and configured.

  • Deliverable: Support for bootloader and program update is implemented as documented above.

  • Deliverable: Add explanations to the README.md file demonstrating how to update the BikeComputer program from version “1.0.0” to “1.0.1”. This documentation includes an explanation of how a new firmware must be confirmed.

Bug Fixes from Phase 2

After you delivered the Phase 2 of the project, a few issues related to your project may have been created. These will need to be fixed within Phase 3. The procedure for fixing bugs is the same as the one documented for Phase 2.