Debounce patient alarms

[ethanjli]

This PR fixes #322 by:

• Moving the Debouncer class in the firmware from Pufferfish/Driver/Button to Pufferfish/Protocols/Application.
• Cleaning up the Debouncer class's member names and fixing errors in the implementation of Debouncer.
• Porting the firmware's Debouncer class to the backend, so that the backend can debounce alarms, and making the breathing circuit simulator alarms be debounced.
• Changing the Debouncer::transform method to fit the signal-processing filter pattern used in Pufferfish/Protocols/Application/SignalSmoothing.h, in which the transform method always writes its output signal to the bool &output parameter (rather than only writing the output signal when the method returns Status::ok).
• Making the Breathing Circuit's Alarms service round the floating-point measurements to int before comparing against the int alarm limits. This makes the alarm triggering behavior less twitchy and more consistent with the values displayed on the frontend. e.g. if the SpO2 lower alarm limit is 40%, an SpO2 measurement of 39.6%, which the frontend displays as 40%, shouldn't trigger the alarm.
• Implementing an EnumMap class for a map with uint*_t-backed enums as keys and arbitrary values, featuring O(1) insertion, O(1) lookup and deletion, and O(n) traversal, with O(n) memory usage (where n is the largest integral value used by the enum), intended for use as a fast lookup table. For comparison, OrderedMap has O(m) insertion, O(m) lookup and deletion, and O(m) traversal, with O(m) memory usage (where m is the maximum number of key-value pairs allowed in the map), intended for use in quickly generating small lists of key-value pairs (e.g. the list of active alarms).
• Using the EnumMap to store the debouncer for each debounced alarm code.
• Creating a BreathingCircuit/Alarms.h file to define the list of debouncers for the breathing circuit (and also using that as the list of alarms to deactivate when ventilation stops, instead of having an array of alarm codes in BreathingCircuit/AlarmsService.h). Currently, Application::AlarmsManager can only handle a single list of debouncers (i.e. those for the breathing circuit); a future PR will be needed to be able to also define lists of debouncers for other modules (e.g. power management, if debouncing is needed there) and give them to the same instance of Application::AlarmsManager. (FYI @rohanpurohit, in case this is relevant to #327)
• Implementing a Util::Timer class to encapsulate a starting time and timeout together for Util::within_timeout calls.
• Using the Util::Timer to add a "lock-out" mechanism for alarms in the firmware and backend, so that FiO2 and flow rate alarms won't be triggered in the ~2 seconds after ParametersRequest.fio2 or ParametersRequest.flow are changed, to give the system time to reach the requested values before sounding alarms. Note: this "lock-out" mechanism is only implemented in the firmware, not the backend. We can port it to the backend later if needed.
• Requiring the setup method of the Sensor driver for the Nonin OEM III to have been called at least once before it starts producing measurements (and returning InitializableState::ok) with output. This allows us to disable the driver for the Nonin OEM III by excluding it from main.cpp's list of Initializable objects, and thus to enable SpO2 and HR simulation - see the next item.
• Modifying the Breathing Circuit simulator to only simulate values for sensors which are missing (i.e. excluded from main.cpp's list of Initializable objects). Commenting out sfm3019_air and sfm3019_o2 is required for the simulator to simulate flow rates, while commenting out nonin_oem now is required for the simulator to simulate SpO2 and HR. This also fixes a bug where previously the simulator was adding simulated noise to real SpO2 and HR measurements from the Nonin OEM III sensor, which was making the displayed values bounce more than they should. @rohanpurohit If you can follow a similar pattern for choosing when to run the power simulator in #327, that'd be great. Basically, between the setup and the main loop I set some variables from the outcomes of the initialization routine, by trying to call output methods. You can do the same for the ltc4015 sensor for a bool ltc4015_status variable, which you can then use as your if check for whether to call the power_simulator.transform method.

This PR also does some refactoring in the firmware:

• Using the EnumMap to store the nanopb message descriptor for each message type used by Pufferfish/Protocols/Transport/Messages.h. This allows us to associate enums directly with MessageTypes enum values, rather than having to also figure out the array indices corresponding to those enum values and to deal with gaps between enum values (e.g. so that it won't be annoying to have message types with uint values 1-12 and then message types with uint values 64-80 and then message types with uint values 128-135).
• Using Util::Timer instead of Util::within_timeout wherever reasonable, to encapsulate starting times together with timeout durations. (FYI @raavilagoo and @rohanpurohit we should prefer using Util::Timer::within_timeout in the future, to make the code more readable. @rohanpurohit we should switch from Util::within_timeout to Util::Timer::within_timeout in #327's power management simulator)
• Moving the logic related to setup and tracking setup status of all Initializables into a new Initializables class in Pufferfish/Driver/Initializable.h.
• Reordering parameters in the firmware's Breathing Circuit driver classes' transform methods so that all input parameters (const references and values) come before all output parameters (non-const references). FYI @rohanpurohit we should make sure we do the same in #327, and anything which can be a const reference should be so (e.g. AlarmsService::transform(PowerManagement &power_management,... should be changed to AlarmsService::transform(const PowerManagement &power_management,...)
• Making a HAL/Platform.h which is the only file which selects the platform used by the firmware; it's used to set the definitions for HAL/Endian.h and HAL/Types.h.
• Exposing iterators in Util::Containers::Vector so that we can iterate through Vector objects with range-based for loops (FYI @raavilagoo and @rohanpurohit so you can take advantage of this when possible)

This PR also reorganizes some files in the firmware:

• Files in Pufferfish/Protocols are moved into Pufferfish/Protocols/Transport or Pufferfish/Protocols/Application, following the pattern set in the backend's ventserver.protocols. The unit test files are also moved to match this directory structure.
• Files related to containers (arrays, vectors, ring buffers, maps) are moved from Pufferfish/Util to Pufferfish/Util/Containers.

Due to the file reorganization:

• FYI @raavilagoo there will be a merge conflict in either this PR or #366, depending on which gets merged into develop first - we'll need to move the test files, change some #includes, and change some namespace paths. You can look at the changes I've made to unit tests in this PR to get a sense of how we'll need to update the unit tests.
• FYI @rohanpurohit there might also be merge conflicts with #333 and #327, we'll have to see.

[ethanjli]

@rohanpurohit This PR is now ready for testing. Since it refactors/touches a lot of modules, it would be helpful if you could exercise as many functionalities of the firmware as possible during testing. I've tagged you and Raavi in the PR description for items where certain changes may impact how you implement things in the firmware.

For records-keeping:

1. This project is licensed under Apache License v2.0 for any software, and Solderpad Hardware License v2.1 for any hardware - do you agree that your contributions to this project will be under these licenses, too? Yes
2. Were any of these contributions also part of work you did for an employer or a client? No
3. Does this work include, or is it based on, any third-party work which you did not create? No

[ethanjli]

without commenting out the initializables array, ventilation cannot be started and shows that the connection to the MCU is lost, also fixes the bug where it takes straight to dashboard sometimes

Hmm, I'm not sure I understand what you mean. I personally am able to run the firmware and start ventilation with the following in main.cpp:

auto initializables = PF::Driver::make_initializables(sfm3019_air, sfm3019_o2, /*fdo2,*/ nonin_oem);

(I comment out fdo2 because I don't have a working hardware unit for it). If you comment out the elements in the array for the sensors you're missing, are you able to run the firmware and start ventilation? I would expect that if you comment out the entire line declaring/defining the initializables object, the firmware shouldn't compile (because main() uses the variable).

[rohanpurohit]

without commenting out the initializables array, ventilation cannot be started and shows that the connection to the MCU is lost, also fixes the bug where it takes straight to dashboard sometimes

Hmm, I'm not sure I understand what you mean. I personally am able to run the firmware and start ventilation with the following in main.cpp:

auto initializables = PF::Driver::make_initializables(sfm3019_air, sfm3019_o2, /*fdo2,*/ nonin_oem);

Oh! so to clarify i don't have any of those sensors with me currently, i plan to get them soon, so i remember facing a situation where if i DONT do this

 auto initializables = PF::Driver::make_initializables(/*sfm3019_air, sfm3019_o2, fdo2, nonin_oem*/);

it would take me straight to the dashboard instead of what I'm seeing currently where it says lost connection to the mcu, n i see the same on develop so maybe I'm confusing it with some other bug that was not fixed in this PR.

(I comment out fdo2 because I don't have a working hardware unit for it). If you comment out the elements in the array for the sensors you're missing, are you able to run the firmware and start ventilation?

Yes, I'm able to. sorry for the confusion

[ethanjli]

Ah, that's good to know. Currently, if the firmware fails setup, the frontend's landing page still allows us to press "Start" and "Start Ventilation", but it also reports that it has lost its connection to the hardware controller; if I press "Start Ventilation", the button doesn't do anything (should be fixed with #361). We should ensure that the microcontroller is connected and active before we enable the "Start" button from the landing page (which requires #371).