Skip to content

Bike Computer Part III

Introduction

Dynamic Event Handling

In part 1 of the BikeComputer codelab, we have implemented a version of the bike computer program that uses cyclic static scheduling. In part 2 of the BikeComputer codelab, an event-driven model was implemented to improve event handling. This improves the application’s performance because it guarantees that no event is ever missed. However, task scheduling is still implemented in a static way, meaning that tasks are always executed in the same order, regardless of their importance.

In this part of the codelab, we will study how to handle events in a dynamic way using the capabilities of Zephyr RTOS. Changes to the system’s state caused by events (such as pressing a button) are applied using a separate thread that acts independently from periodic tasks. This preemptive implementation allows for better prioritization and shorter response times.

Multi-tasking Applications with periodic, event-driven and data-driven tasks

An important capability of multi-tasking applications is to adapt the behavior of each task to its intrisic nature, namely:

  • periodic tasks: tasks such as reading sensor data are essentially periodic. In general, these tasks cannot be driven by specific events and they will run at a pre-defined interval.
  • event-driven tasks: tasks such as reacting to a user action cannot be predicted and are by nature not periodic. They are thus driven by external events and implemented using interrupt mechanisms.
  • data-driven tasks: some tasks need to receive data for accomplishing their job. They must thus wait for data and react when new data becomes available.

In this codelab, we will implement the different bike_computer tasks using the appropriate type of task, namely:

  • reset, gear and pedal tasks as event-driven tasks, where an event (and its related data) is produced upon user action (using the buttons).
  • display and temperature tasks as periodic tasks that run at fixed periodic time intervals.

What you’ll build

In this codelab, you’re going to program our bike_computer program that handles event-driven tasks in a dynamic way.

What you’ll learn

  • How to develop a simple embedded program using multiple threads.
  • How to use the work queue mechanism to implement dynamic handling of events.

What you’ll need

Initial Step

To implement this version of the bike_computer program, you must apply some changes to the program developed in part II of the codelab. The changes are documented below.

As a starting point you must duplicate the static_scheduling_with_event version and apply some changes. The steps for applying the changes are:

  • Copy the code from the static_scheduling_with_event folder in a new subfolder named static_scheduling_with_wq. The version under static_scheduling_with_event contains the version that you delivered for phase B of the project.

  • Modify the namespace in all classes from static_scheduling_with_event to static_scheduling_with_wq.

  • Modify your main function to use this new implementation (e.g. include path or namespace use).

  • Add the following definition in the application Kconfig file:

    bike_computer/Kconfig
      config BIKE_COMPUTER_STATIC_SCHEDULING_WITH_WQ
        bool "Build system with static scheduling with event"
        default n
        help
          This option must be enabled to use the static scheduling version
          with event handling with a work queue
    

  • Add the prj_static_scheduling_with_wq.conf file to the root of the bike_computer application:

    bike_computer/prj_static_scheduling_with_wq.conf
    # enable static scheduling with work queue
    CONFIG_BIKE_COMPUTER_STATIC_SCHEDULING_WITH_WQ=y
    
    # increase the stack size of the threads created with zpp_lib
    CONFIG_ZPP_THREAD_STACK_SIZE=4096
    
    # increase the stack size of the main thread
    CONFIG_MAIN_STACK_SIZE=4096
    

Reduce Event Response Times and Improve Concurrency

In the Bike computer - part II codelab, we implemented an event-driven mechanism to register events such as button actions. This improved the program behavior by making sure that no event was ever missed, but this change did not yet improve the event response time. This is due to the fact that event-driven tasks are still executed at periodic time intervals with a static schedule.

Another major drawback of the way devices are implemented in the Bike computer - part II codelab relates to concurrency issues. In this implementation, devices have an internal state that is modified by ISRs. This internal state may be queried concurrently by the BikeSystem tasks. This means that the internal state variables must be protected against concurrent access, which makes its implementation more complex (in most cases). In the new implementation, the internal state of the devices will be communicated to the BikeSystem class each time a change occurs. This will improve response times and simplify concurrent access protection.

Start the changes by modifying the BikeSystem and ResetDevice classes as follows:

  • In your BikeSystem class, create a zpp_lib::WorkQueue attribute dedicated to serving ISRs. This zpp_lib::WorkQueue instance owns its own internal thread with priority passed as construction.

  • Add the following definition in the Kconfig file:

    bike_computer/Kconfig
    config WORK_QUEUE_THREAD_PRIORITY
      int "Priority of the thread running the work queue"
      default 9
      help
        This option sets the priority of the thread running the
        work queue (with BIKE_COMPUTER_STATIC_SCHEDULING_WITH_WQ enabled)
    
    This option allows to set the priority of the thread running the zpp_lib::WorkQueue, using zpp_lib::prio_to_preemptable_thread_priority(CONFIG_WORK_QUEUE_THREAD_PRIORITY).

  • Add the following definition in the prj_static_scheduling_with_wq.conf file:

    bike_computer/prj_static_scheduling_with_wq.conf
    # priority of the thread serving the work queue
    CONFIG_WORK_QUEUE_THREAD_PRIORITY=9
    

  • In your BikeSystem class, create a Work attribute that represents the work to be accomplished upon reset. This instance will be used to submit the work to the WorkQueue instance.

  • Modify the BikeSystem::on_reset() method to defer the call to the BikeSystem::reset_task() method using the zpp_lib::WorkQueue instance rather than setting a flag.

  • Clean up the code: remove periodic call to BikeSystem::reset_task(), remove useless attributes, etc.

  • At this point, the ResetDevice class should be a stateless class without any getter methods.

Once the changes are correctly implemented, test that the reset mechanism works properly.

Question 1

First, make sure that you understand what threads are running in your application and what the priority of each thread is. This can be done by adding a call to zpp_lib::Utils::log_threads_summary() in the BikeSystem::start() method and by adding the stats config in the just build command.

Try to modify the priority of the thread used for serving ISRs. This can be done by modifying the CONFIG_WORK_QUEUE_THREAD_PRIORITY configuration parameter. Test with different priorites set to 10 or zpp_lib::PreemptableThreadPriority::PriorityBelowNormal, 9 or zpp_lib::PreemptableThreadPriority::PriorityNormal and 8 or zpp_lib::PreemptableThreadPriority::PriorityAboveNormal. Observe the behavior of the response time in each case.

How can you explain the observed response times? If you observe a difference depending on the priority of the zpp_lib::WorkQueue thread, explain why. If you cannot observe any difference, also give an explanation and explain a scenario where different priorities would produce different results. Hint: try to increase the CPU load by disabling the sleep behavior in the TaskManager::simulate_computation_time() method.

Make the Gear and Pedal tasks event-driven

In the Bike computer - part II codelab, both the gear and pedal tasks were implemented as periodic tasks with ISRs modifying the state of the devices. Even though this improves the application behavior as compared to the Bike computer - part I implementation, this does not make these tasks truly event-driven, as they are still implemented as periodic tasks in the BikeSystem class.

This implementation has significant drawbacks:

  • Both tasks are executed periodically, regardless of any changes to gear or rotation speed. This uses CPU even when no changes have been made.

  • Similarly to the reset task, the response time is not optimal and exhibits a large jitter.

  • Both GearDevice and PedalDevice classes must maintain an internal state and protect concurrent access to this internal state.

To improve this implementation, both the gear and pedal tasks must be made event-driven. This means that events will be generated whenever the user presses the button, which will then defer a specific work to the zpp_lib::WorkQueue instance. To implement this change, you must create a zpp_lib::Work upon user action and call the zpp_lib::WorkQueue to execute the work.

For this implementation, recall that zpp_lib::Work is a template class where the template parameter specifies the callback function to execute when the event is dispatched.

To help you in the implementation, we illustrate the required changes for the GearDevice class:

  • Each time an event is generated, a zpp_lib::Work will be deferred to the zpp_lib::WorkQueue. The zpp_lib::Work instance must contain the GearDevice state, i.e. the current gear and the current gear size (both as uint8_t values).
  • The callback type used to notify the event is thus std::function<void(uint8_t, uint8_t)>. This type must be defined in the GearDevice class with using CallbackFunction = std::function<void(uint8_t, uint8_t)>;
  • Modify the GearDevice constructor to pass a callback of type CallbackFunction at construction.
  • Declare the callback (in the BikeSystem class, when constructing the GearDevice instance) using a capturing lambda.
  • In the BikeSystem::on_gear_changed, defer the work to the WorkQueueinstance. See the note below for a correct implementation.
  • Add two public constant variables in the GearDevice class that document how the internal state of the device is initialized and that allow the BikeSystem class to get the internal state of the device at startup. This enables a proper initialization of the devices and this enables the BikeSystem to update the various devices and the display at startup.

How to defer a work properly from an ISR

To defer work from an ISR method, there are some important points to consider:

  • Memory cannot be allocated in an ISR method. For this reason, creating a std::function or a closure from a lambda with capture in the ISR method itself is unsafe. Using a lambda without capture would be an option, but we need at least to capture the reference to the instance (this), which makes this approach unsafe.
  • The zpp_lib::Work instance that is passed to the zpp_lib::WorkQueue instance using the WorkQueue::call() method must remain valid until the WorkQueue thread has completed the call to the Work instance’s handler. Therefore, you cannot create a Work instance on the stack, pass it to the WorkQueue and then leave the ISR method, since the Work instance will be destroyed when you leave the ISR method.
  • Using zpp_lib::Work properly allows to deal with these two problems:

    • An instance of zpp_lib::Work can be created as attribute of the BikeSystem class. It may be initialized in the constructor’s initializer list as _gear_work(zpp_lib::Work<BikeSystem, uint8_t, uint8_t>(this, &BikeSystem::updateGear, 0, 0)).
    • In the ISR BikeSystem::on_gear_changed() method, the parameters to be used in the zpp_lib::Work instance can be updated using the zpp_lib::Work.set_params(...) method. This method can be safely called since new parameters will be rejected if there is still a pending work instance. In this case, rejecting new parameters is acceptable and simulates a “greyed out” button.
  • If you follow these guidelines, you should be able to properly defer the work from the ISR method to the work queue.

Similar changes must also be applied to the PedalDevice class and its use in the BikeSystem class. Once you made the documented changes, you must of course:

  • Remove the periodic calls to BikeSystem::gear_task() and BikeSystem::speed_distance_task().
  • Remove all unused attributes from the BikeSystem class, such as current gear or speed.
  • Remove all getter methods from the GearDevice and PedalDevice classes.

At this point, the BikeSystem::start() method schedule only three periodic tasks, using the BikeSystem::temperature_task(), BikeSystem::display_task1() and BikeSystem::display_task2() methods. The other tasks are now implemented as event-driven tasks.

Prepare for Testing

Your final version of the BikeComputer program must be tested. The following test cases must be implemented in the tests/bike_system_part3 test application:

  • test_bike_system_static_with_wq: It is identical to the test_bike_system_static_with_event test and it validates that the periodic tasks run according to the defined periods.

  • test_reset_bike_system_with_wq: It validates that resetting the BikeSystem works properly, with the expected response time (below \(100 us\) with a jitter smaller than \(31 us\)).

test_reset_bike_system_with_wq
bike_computer/tests/bike_system_part3/src/main.cpp
// test_reset_bike_system_with_wq handler function
// Using global static variables is acceptable for this test, since they
// are only used in this test and not in the BikeSystem class
// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
static std::chrono::microseconds s_reset_time = std::chrono::microseconds::zero();
// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
static zpp_lib::Event s_reset_event;
static constexpr uint32_t kResetEventFlag = (1UL << 0);
static void reset_callback() {
  s_reset_time = zpp_lib::Time::get_uptime();
  s_reset_event.set(kResetEventFlag);
}

ZPP_ZTEST(bike_system_part3, test_reset_bike_system_with_wq) {
  // create the BikeSystem instance
  bike_computer::static_scheduling_with_wq::BikeSystem bike_system;

  // run the bike system in a separate thread
  zpp_lib::Thread thread(zpp_lib::PreemptableThreadPriority::PriorityNormal, "Test BS MT");
  auto res = thread.start([&bike_system]() {
    auto res = bike_system.start();
    zpp_zassert_true(res, "Failed to start BikeSystem");
  });
  zpp_zassert_true(res, "Could not start thread");

  // let the bike system run for 10 secs
  // this will test whether scheduling is ok
  static constexpr auto kInitialTestDuration = 10s;
  zpp_lib::ThisThread::sleep_for(kInitialTestDuration);

  // test reset on BikeSystem
  bike_system.get_speedometer().set_on_reset_callback(reset_callback);

  // instantiate the reset button
  zpp_lib::InterruptIn& reset_button = bike_system.get_reset_device().get_reset_button();

  // check for reset response time
  constexpr uint8_t kNbrOfResets               = 10;
  std::chrono::microseconds last_response_time = std::chrono::microseconds::zero();
  for (uint8_t i = 0; i < kNbrOfResets; i++) {
    // reset the BikeSystem by simulating button press
    reset_button.write(zpp_lib::kPolarityPressed);

    // take time before waiting for reset
    auto start_time = zpp_lib::Time::get_uptime();

    // wait for resetCallback to be called
    s_reset_event.wait_any(kResetEventFlag);

    // get the response time and check it
    auto response_time = s_reset_time - start_time;

    // check that the response time is within the expected margin
    // cppcheck generates an internal error with 20us
    constexpr std::chrono::microseconds kMaxExpectedResponseTime(100);
    zpp_zassert_true(response_time <= kMaxExpectedResponseTime, "Response time is too long: %lld usecs", response_time.count());

    printf("Reset task: response time is %lld usecs\n", response_time.count());

    using std::literals::chrono_literals::operator""us;
    constexpr auto kMaxExpectedJitter = 31us;
    if (i > 0) {
      auto jitter = response_time - last_response_time;
      zpp_zassert_true(std::abs(jitter.count()) <= kMaxExpectedJitter.count(), "Response time jitter is too high");
    }
    last_response_time = response_time;

    // unpress the button
    reset_button.write(!zpp_lib::kPolarityPressed);

    // let the bike system run for 2 secs
    static constexpr auto kSleepDurationAfterReset = 2s;
    zpp_lib::ThisThread::sleep_for(kSleepDurationAfterReset);
  }

  // stop the bike system
  bike_system.stop();

  res = thread.join();
  zpp_zassert_true(res, "Could not join thread");
}

Some changes are required in different classes of the bike_computer application for the test program to compile and work properly. Note that these changes must be implemented only for test builds using the #if CONFIG_TEST preprocessor directive.

  • Add the public method void set_on_reset_callback(std::function<void()> cb) to the Speedometer class. This method must allow to register a callback with the proper signature and this callback function must be called (without additional delay) upon reset.
  • Add the public method Speedometer &get_speedometer() and ResetDevice &get_reset_device() to the BikeSystem class.
  • Add the methods get_XXX_button() to the ResetDevice and GearDevice classes.

Run first your tests against these two test cases. The testcase.yaml definitions is the same as the one of the bike_computer/tests/bike_system_part2 definition with the following changes:

  • The CONFIG_TEST_DURATION_IN_MS configuration parameter must be set to 120000 for all platforms. This means that with this implementation of the bike_computer application, periodic tasks meet their deadlines for a longer time than with previous implementations.
  • The CONFIG_WORK_QUEUE_THREAD_PRIORITY=8 configuration parameter must be added to the extra_args entry. This allows to run the work queue thread with a priority higher than the one of the thread running the periodic tasks of the bike_computer program.
  • The extra_conf_files entry must be modified to use static_scheduling_with_wq.conf
  • The platform:nrf5340dk/nrf5340/cpuapp:CONFIG_INTERRUPT_IN_EMUL=y configuration parameter must be added to the extra_args entry. This allows to emulate buttons for the nrf5340dk/nrf5340/cpuapp platform .
  • The phase_b tags must be changed to phase_c.
  • The timeout value may need to be updated.

Write your own GearDevice Test

To validate the correct implementation of the GearDevice class, you must also validate that changing the gear (up and down) works properly. Your test program must simulate button press by invoking the zpp_lib::InterruptIn::write() method as demonstrated in the test_reset_bike_system_with_wq test program.

The test program must validate the following:

  • When pressing button 4 (with button 2 pressed), the current gear and gear size are updated correctly. When the maximum value for the gear is reached, then pressing the up button should not update the gear any more.

** When pressing button 3 (with button 2 pressed), the current gear and gear size are updated correctly. When the minimal value for the gear is reached, then pressing the down button should not update the gear any more.

Wrap-Up

At the end of this codelab, make sure that you have accomplished the following:

  • The ResetDevice, GearDevice and PedalDevice classes has been modified as specified, to support event-driven handling of the buttons.
  • The BikeSystem class has been modified to handle events by deferring work to a dedicated zpp_lib::WorkQueue instance.
  • You have written the required test program and run all tests successfully.
  • You have answered all questions.
  • The pre-commit configur-tion file has been modified to include the necessary hooks. All software quality tools succeed, changes are committed and pushed to your repository.

Deliverables

Deliverables/Requirements (Project Phase C)

The deliverables/requirements for project Phase C include the following:

  • The implementation of the bike_computer using a zpp_lib::WorkQueue mechanism to handle events is functional. All related files are available in the static_scheduling_with_wq folder and all related code is developed under the static_scheduling_with_wq namespace.

  • The developed code is compliant to the clang-tidy rules and just run-clang-tidy bike_computer log+debug+gpio+display+sensor+log_cpu+stats prj_static_scheduling_with_wq.conf runs successfully. Be aware that if you followed the guidelines and applied the correct configurations, more than 45 files should be analyzed when running just run-clang-tidy.

  • The following hook is added to the pre-commit configuration and pre-commit runs successfully. This hook includes the additional test program.

    • id: clang-tidy-bike-computer-bike-system-part3
  • The bike_computer/tests/bike_system_part3 test runs successfully on your board and on qemu_x86. The CONFIG_TEST_DURATION_IN_MS parameter have been estimated and updated in the bike_computer/tests/bike_system_part3/testcase.yaml file. The ci/applications_for_test.yaml file is updated to include the phase_c tag. The following commands run successfully:

    • just test bike_computer/tests/bike_system_part3 "you_map_file.yaml"
    • just test-qemu bike_computer/tests/bike_system_part3
    • just test-all "your_map_file.yaml", including the bike_computer/tests/bike_system_part3 test.
    • just test-all-qemu, including the bike_computer/tests/bike_system_part3 test.
  • The answers to the four questions of this codelab are documented in the README.md file.