diff --git a/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.cpp b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.cpp new file mode 100644 index 00000000..a1cf4b6e --- /dev/null +++ b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.cpp @@ -0,0 +1,27 @@ +// ====================================================================== +// \title BootloaderTrigger.cpp +// \author aychar +// \brief cpp file for BootloaderTrigger component implementation class +// ====================================================================== + +#include "FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.hpp" + +#include + +namespace Components { + +// ---------------------------------------------------------------------- +// Component construction and destruction +// ---------------------------------------------------------------------- + +BootloaderTrigger ::BootloaderTrigger(const char* const compName) : BootloaderTriggerComponentBase(compName) {} + +BootloaderTrigger ::~BootloaderTrigger() {} + +// In the future this command/component should either be removed entirely, or some kind of protection +// should be added to ensure this can't be ran when the satellite is in space +void BootloaderTrigger ::TRIGGER_BOOTLOADER_cmdHandler(FwOpcodeType opCode, U32 cmdSeq) { + reset_usb_boot(0, 0); +} + +} // namespace Components diff --git a/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.fpp b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.fpp new file mode 100644 index 00000000..0d46ab14 --- /dev/null +++ b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.fpp @@ -0,0 +1,25 @@ +module Components { + @ Used to trigger bootloader mode to install board firmware for integration testing. (DO NOT USE IN SPACE VERY BAD!!!!) + passive component BootloaderTrigger { + + @ Restarts board and puts it in bootloader mode. (Only should be used for integration testing) + sync command TRIGGER_BOOTLOADER( + ) + + ############################################################################### + # Standard AC Ports: Required for Channels, Events, Commands, and Parameters # + ############################################################################### + @ Port for requesting the current time + time get port timeCaller + + @ Port for sending command registrations + command reg port cmdRegOut + + @ Port for receiving commands + command recv port cmdIn + + @ Port for sending command responses + command resp port cmdResponseOut + + } +} diff --git a/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.hpp b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.hpp new file mode 100644 index 00000000..24972e86 --- /dev/null +++ b/FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTrigger.hpp @@ -0,0 +1,35 @@ +// ====================================================================== +// \title BootloaderTrigger.hpp +// \author aychar +// \brief hpp file for BootloaderTrigger component implementation class +// ====================================================================== + +#ifndef Components_BootloaderTrigger_HPP +#define Components_BootloaderTrigger_HPP + +#include "FprimeZephyrReference/Components/BootloaderTrigger/BootloaderTriggerComponentAc.hpp" + +namespace Components { + +class BootloaderTrigger final : public BootloaderTriggerComponentBase { + public: + // ---------------------------------------------------------------------- + // Component construction and destruction + // ---------------------------------------------------------------------- + + //! Construct BootloaderTrigger object + BootloaderTrigger(const char* const compName //!< The component name + ); + + //! Destroy BootloaderTrigger object + ~BootloaderTrigger(); + + private: + void TRIGGER_BOOTLOADER_cmdHandler(FwOpcodeType opCode, //!< The opcode + U32 cmdSeq //!< The command sequence number + ) override; +}; + +} // namespace Components + +#endif diff --git a/FprimeZephyrReference/Components/BootloaderTrigger/CMakeLists.txt b/FprimeZephyrReference/Components/BootloaderTrigger/CMakeLists.txt new file mode 100644 index 00000000..81311246 --- /dev/null +++ b/FprimeZephyrReference/Components/BootloaderTrigger/CMakeLists.txt @@ -0,0 +1,36 @@ +#### +# F Prime CMakeLists.txt: +# +# SOURCES: list of source files (to be compiled) +# AUTOCODER_INPUTS: list of files to be passed to the autocoders +# DEPENDS: list of libraries that this module depends on +# +# More information in the F´ CMake API documentation: +# https://fprime.jpl.nasa.gov/latest/docs/reference/api/cmake/API/ +# +#### + +# Module names are derived from the path from the nearest project/library/framework +# root when not specifically overridden by the developer. i.e. The module defined by +# `Ref/SignalGen/CMakeLists.txt` will be named `Ref_SignalGen`. + +register_fprime_library( + AUTOCODER_INPUTS + "${CMAKE_CURRENT_LIST_DIR}/BootloaderTrigger.fpp" + SOURCES + "${CMAKE_CURRENT_LIST_DIR}/BootloaderTrigger.cpp" +# DEPENDS +# MyPackage_MyOtherModule +) + +### Unit Tests ### +# register_fprime_ut( +# AUTOCODER_INPUTS +# "${CMAKE_CURRENT_LIST_DIR}/BootloaderTrigger.fpp" +# SOURCES +# "${CMAKE_CURRENT_LIST_DIR}/test/ut/BootloaderTriggerTestMain.cpp" +# "${CMAKE_CURRENT_LIST_DIR}/test/ut/BootloaderTriggerTester.cpp" +# DEPENDS +# STest # For rules-based testing +# UT_AUTO_HELPERS +# ) diff --git a/FprimeZephyrReference/Components/BootloaderTrigger/docs/sdd.md b/FprimeZephyrReference/Components/BootloaderTrigger/docs/sdd.md new file mode 100644 index 00000000..94abb38a --- /dev/null +++ b/FprimeZephyrReference/Components/BootloaderTrigger/docs/sdd.md @@ -0,0 +1,79 @@ +# Components::BootloaderTrigger + +The BootloaderTrigger component provides a command interface to reset the board into bootloader mode for firmware installation during integration testing. **WARNING: This component should NOT be used in production or flight configurations.** + +## Usage Examples + +The BootloaderTrigger component is designed to facilitate firmware updates during ground testing and integration. It operates as a passive component that responds to commands. + +### Typical Usage + +1. The component is instantiated during system startup +2. During integration testing, when firmware needs to be updated: + - The `TRIGGER_BOOTLOADER` command is sent to the component + - The board immediately resets into bootloader mode + - Firmware can then be uploaded via USB + +**IMPORTANT:** This component should be removed or disabled for flight builds to prevent accidental activation in space. + +## Class Diagram + +```mermaid +classDiagram + namespace Components { + class BootloaderTriggerComponentBase { + <> + } + class BootloaderTrigger { + + BootloaderTrigger(const char* compName) + + ~BootloaderTrigger() + - TRIGGER_BOOTLOADER_cmdHandler(FwOpcodeType opCode, U32 cmdSeq) + } + } + BootloaderTriggerComponentBase <|-- BootloaderTrigger : inherits +``` + +## Port Descriptions + +| Name | Type | Description | +| -------------- | ------------ | -------------------------------------- | +| cmdIn | command recv | Port for receiving commands | +| cmdResponseOut | command resp | Port for sending command responses | +| cmdRegOut | command reg | Port for sending command registrations | +| timeCaller | time get | Port for requesting the current time | + +## Sequence Diagrams + +```mermaid +sequenceDiagram + participant Ground System + participant Command Dispatcher + participant BootloaderTrigger + participant Pico Bootrom + + Ground System->>Command Dispatcher: Send TRIGGER_BOOTLOADER command + Command Dispatcher->>BootloaderTrigger: cmdIn(TRIGGER_BOOTLOADER) + BootloaderTrigger->>Pico Bootrom: reset_usb_boot(0, 0) + Note over BootloaderTrigger,Pico Bootrom: Board resets into bootloader mode + Note over Ground System: Board now accepts firmware upload via USB +``` + +## Commands + +| Name | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| TRIGGER_BOOTLOADER | Restarts the board and puts it into bootloader mode. This is a synchronous command that triggers an immediate reset. Should only be used during integration testing. | + +## Requirements + +| Name | Description | Validation | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| TRIGGER_BOOTLOADER Command | The component shall provide a command interface to reset the board into bootloader mode using the Pico bootrom API | Verify that sending the command causes the board to reset and enter bootloader mode, allowing firmware upload | +| Safety Warning | The component shall include clear documentation warnings that it must not be used in flight configurations | Documentation review and code review process | +| Integration Testing Support | The component shall enable firmware updates during ground integration testing without requiring physical access to boot pins | Verify successful firmware updates can be performed remotely during testing | + +## Change Log + +| Date | Description | +| ---------- | ------------- | +| 2025-10-01 | Initial Draft | diff --git a/FprimeZephyrReference/Components/CMakeLists.txt b/FprimeZephyrReference/Components/CMakeLists.txt index 79100334..08ac562c 100644 --- a/FprimeZephyrReference/Components/CMakeLists.txt +++ b/FprimeZephyrReference/Components/CMakeLists.txt @@ -4,3 +4,4 @@ add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/Drv/") add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/FatalHandler") add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/ImuManager/") add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/Watchdog") +add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/BootloaderTrigger/") diff --git a/FprimeZephyrReference/ReferenceDeployment/Top/instances.fpp b/FprimeZephyrReference/ReferenceDeployment/Top/instances.fpp index 597c813b..4b6f7ebd 100644 --- a/FprimeZephyrReference/ReferenceDeployment/Top/instances.fpp +++ b/FprimeZephyrReference/ReferenceDeployment/Top/instances.fpp @@ -69,4 +69,6 @@ module ReferenceDeployment { instance lis2mdlManager: Drv.Lis2mdlManager base id 0x10018000 instance lsm6dsoManager: Drv.Lsm6dsoManager base id 0x10019000 + + instance bootloaderTrigger: Components.BootloaderTrigger base id 0x10020000 } diff --git a/FprimeZephyrReference/ReferenceDeployment/Top/topology.fpp b/FprimeZephyrReference/ReferenceDeployment/Top/topology.fpp index 60afd964..bc6a5437 100644 --- a/FprimeZephyrReference/ReferenceDeployment/Top/topology.fpp +++ b/FprimeZephyrReference/ReferenceDeployment/Top/topology.fpp @@ -32,7 +32,7 @@ module ReferenceDeployment { instance imuManager instance lis2mdlManager instance lsm6dsoManager - + instance bootloaderTrigger # ---------------------------------------------------------------------- # Pattern graph specifiers # ----------------------------------------------------------------------