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
- Zephyr Development Environment for developing and debugging your program in C++.
- The Bike computer - part I, Bike computer - part II and Multi-tasking codelabs are prerequisites to this codelab.
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_eventfolder in a new subfolder namedstatic_scheduling_with_wq. The version understatic_scheduling_with_eventcontains the version that you delivered for phase B of the project. -
Modify the namespace in all classes from
static_scheduling_with_eventtostatic_scheduling_with_wq. -
Modify your
mainfunction to use this new implementation (e.g. include path or namespace use). -
Add the following definition in the application
Kconfigfile:bike_computer/Kconfigconfig 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.conffile to the root of thebike_computerapplication: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
BikeSystemclass, create azpp_lib::WorkQueueattribute dedicated to serving ISRs. Thiszpp_lib::WorkQueueinstance owns its own internal thread with priority passed as construction. -
Add the following definition in the
Kconfigfile:bike_computer/KconfigThis option allows to set the priority of the thread running theconfig 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)zpp_lib::WorkQueue, usingzpp_lib::prio_to_preemptable_thread_priority(CONFIG_WORK_QUEUE_THREAD_PRIORITY). -
Add the following definition in the
prj_static_scheduling_with_wq.conffile:bike_computer/prj_static_scheduling_with_wq.conf# priority of the thread serving the work queue CONFIG_WORK_QUEUE_THREAD_PRIORITY=9 -
In your
BikeSystemclass, create aWorkattribute that represents the work to be accomplished upon reset. This instance will be used to submit the work to theWorkQueueinstance. -
Modify the
BikeSystem::on_reset()method to defer the call to theBikeSystem::reset_task()method using thezpp_lib::WorkQueueinstance rather than setting a flag. -
Clean up the code: remove periodic call to
BikeSystem::reset_task(), remove useless attributes, etc. -
At this point, the
ResetDeviceclass 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
GearDeviceandPedalDeviceclasses 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::Workwill be deferred to thezpp_lib::WorkQueue. Thezpp_lib::Workinstance must contain theGearDevicestate, i.e. the current gear and the current gear size (both asuint8_tvalues). - The callback type used to notify the event is thus
std::function<void(uint8_t, uint8_t)>. This type must be defined in theGearDeviceclass withusing CallbackFunction = std::function<void(uint8_t, uint8_t)>; - Modify the
GearDeviceconstructor to pass a callback of typeCallbackFunctionat construction. - Declare the callback (in the
BikeSystemclass, when constructing theGearDeviceinstance) using a capturing lambda. - In the
BikeSystem::on_gear_changed, defer the work to theWorkQueueinstance. See the note below for a correct implementation. - Add two public constant variables in the
GearDeviceclass that document how the internal state of the device is initialized and that allow theBikeSystemclass to get the internal state of the device at startup. This enables a proper initialization of the devices and this enables theBikeSystemto 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::functionor 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::Workinstance that is passed to thezpp_lib::WorkQueueinstance using theWorkQueue::call()method must remain valid until theWorkQueuethread has completed the call to theWorkinstance’s handler. Therefore, you cannot create aWorkinstance on the stack, pass it to theWorkQueueand then leave the ISR method, since theWorkinstance will be destroyed when you leave the ISR method. -
Using
zpp_lib::Workproperly allows to deal with these two problems:- An instance of
zpp_lib::Workcan be created as attribute of theBikeSystemclass. 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 thezpp_lib::Workinstance can be updated using thezpp_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.
- An instance of
-
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()andBikeSystem::speed_distance_task(). - Remove all unused attributes from the
BikeSystemclass, such as current gear or speed. - Remove all getter methods from the
GearDeviceandPedalDeviceclasses.
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 thetest_bike_system_static_with_eventtest and it validates that the periodic tasks run according to the defined periods. -
test_reset_bike_system_with_wq: It validates that resetting theBikeSystemworks properly, with the expected response time (below \(100 us\) with a jitter smaller than \(31 us\)).
test_reset_bike_system_with_wq
// 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 theSpeedometerclass. 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()andResetDevice &get_reset_device()to theBikeSystemclass. - Add the methods
get_XXX_button()to theResetDeviceandGearDeviceclasses.
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_MSconfiguration parameter must be set to120000for all platforms. This means that with this implementation of thebike_computerapplication, periodic tasks meet their deadlines for a longer time than with previous implementations. - The
CONFIG_WORK_QUEUE_THREAD_PRIORITY=8configuration parameter must be added to theextra_argsentry. This allows to run the work queue thread with a priority higher than the one of the thread running the periodic tasks of thebike_computerprogram. - The
extra_conf_filesentry must be modified to usestatic_scheduling_with_wq.conf - The
platform:nrf5340dk/nrf5340/cpuapp:CONFIG_INTERRUPT_IN_EMUL=yconfiguration parameter must be added to theextra_argsentry. This allows to emulate buttons for the nrf5340dk/nrf5340/cpuapp platform . - The
phase_btags must be changed tophase_c. - The
timeoutvalue 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,GearDeviceandPedalDeviceclasses has been modified as specified, to support event-driven handling of the buttons. - The
BikeSystemclass has been modified to handle events by deferring work to a dedicatedzpp_lib::WorkQueueinstance. - You have written the required test program and run all tests successfully.
- You have answered all questions.
- The
pre-commitconfigur-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_computerusing azpp_lib::WorkQueuemechanism to handle events is functional. All related files are available in thestatic_scheduling_with_wqfolder and all related code is developed under thestatic_scheduling_with_wqnamespace. -
The developed code is compliant to the
clang-tidyrules andjust run-clang-tidy bike_computer log+debug+gpio+display+sensor+log_cpu+stats prj_static_scheduling_with_wq.confruns successfully. Be aware that if you followed the guidelines and applied the correct configurations, more than 45 files should be analyzed when runningjust run-clang-tidy. -
The following hook is added to the
pre-commitconfiguration andpre-commitruns successfully. This hook includes the additional test program.id: clang-tidy-bike-computer-bike-system-part3
-
The
bike_computer/tests/bike_system_part3test runs successfully on your board and on qemu_x86. TheCONFIG_TEST_DURATION_IN_MSparameter have been estimated and updated in thebike_computer/tests/bike_system_part3/testcase.yamlfile. Theci/applications_for_test.yamlfile is updated to include thephase_ctag. 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_part3just test-all "your_map_file.yaml", including thebike_computer/tests/bike_system_part3test.just test-all-qemu, including thebike_computer/tests/bike_system_part3test.
-
The answers to the four questions of this codelab are documented in the README.md file.