C++ Module: cppModuleTemplate
Executive Summary
The C++ module template demonstrates message handling, a simple vector calculation, reset
behavior, and accessors for private variables. On every update, it copies an optional
input vector and adds an increasing counter to the first component. It implements the
same calculation as C Module: cModuleTemplate using the C++ SysModel interface.
This page is a working example of module documentation. See Module RST Documentation for the RST authoring tutorial.
Module Assumptions and Limitations
The vectors and counter are dimensionless teaching examples, with no physical model. The counter advances once per scheduled update, independently of the task period. No configuration is required to run the module. A connected input supplies its latest payload; the module does not check its age or require a new write on every update. A disconnected input supplies a zero vector.
Message Connection Descriptions
Connect the input from Python using subscribeTo(). Both messages use the three-element
dataVector field of CModuleTemplateMsgPayload.
Msg Variable Name |
Msg Type |
Description |
|---|---|---|
dataInMsg |
Optional dimensionless input vector. Uses a zero vector when disconnected. |
|
dataOutMsg |
Dimensionless input vector with the update counter added to its first component. Reset publishes a zero vector; each update publishes the calculated vector. |
Detailed Module Description
Each UpdateState() call increments updateCounter, copies the input vector, and
adds the counter to its first component, as in Eq. (1).
The implementation uses v3SetZero() and v3Copy() from linearAlgebra to
demonstrate sample vector math. Its input scratch array is local to the update method.
The C++ output message initializes itself on construction. Reset() clears the counter
and publishes a zero output payload at the reset time. The next update uses a counter
value of one. Reset preserves sampleConfigVector.
Configuration and Runtime State
The private variables follow the configuration and runtime state roles described for the C template:
setSampleConfigVector()demonstrates setting a configuration vector. Its three components must be positive when using the setter. The vector defaults to zero, survives resets and updates, and does not affect the output calculation.setUpdateCounter()demonstrates scalar assignment and validation, accepting a positive value. The counter is runtime state:Reset()clears it, including values assigned beforeInitializeSimulation().getSampleConfigVector()andgetUpdateCounter()provide read access. Variable logging through these getters is demonstrated in Setting and Recording Module Variables.
User Guide
The following complete script runs three updates, at 0, 0.5, and 1 second, and checks the
output vectors. Add the recorder after the module to record the newly written output.
InitializeSimulation() calls Reset() before the scheduled updates begin.
import numpy as np
from Basilisk.architecture import messaging
from Basilisk.moduleTemplates import cppModuleTemplate
from Basilisk.utilities import SimulationBaseClass, macros
simulation = SimulationBaseClass.SimBaseClass()
time_step = macros.sec2nano(0.5) # [ns]
process = simulation.CreateNewProcess("exampleProcess")
process.addTask(simulation.CreateNewTask("exampleTask", time_step))
module = cppModuleTemplate.CppModuleTemplate()
module.ModelTag = "cppModuleExample"
module.setSampleConfigVector([1.0, 2.0, 3.0]) # [-] Preserved by reset.
simulation.AddModelToTask("exampleTask", module)
input_payload = messaging.CModuleTemplateMsgPayload()
input_payload.dataVector = [1.0, 2.0, 3.0] # [-]
input_message = messaging.CModuleTemplateMsg().write(input_payload)
module.dataInMsg.subscribeTo(input_message)
recorder = module.dataOutMsg.recorder()
simulation.AddModelToTask("exampleTask", recorder)
simulation.InitializeSimulation()
simulation.ConfigureStopTime(2 * time_step)
simulation.ExecuteSimulation()
expected = [[2.0, 2.0, 3.0], [3.0, 2.0, 3.0], [4.0, 2.0, 3.0]] # [-]
np.testing.assert_array_equal(recorder.dataVector, expected)
np.testing.assert_array_equal(recorder.times(), [0, time_step, 2 * time_step])
assert module.getUpdateCounter() == 3
To try the disconnected-input case, omit the subscribeTo() call and change expected
to [[1.0, 0.0, 0.0], [2.0, 0.0, 0.0], [3.0, 0.0, 0.0]]. The initial zero payload
written by reset is replaced by the first update before the recorder samples at time zero.
-
class CppModuleTemplate : public SysModel
- #include <cppModuleTemplate.h>
basic Basilisk C++ module class
Public Functions
-
CppModuleTemplate()
This is the constructor for the module class. It sets default variable values and initializes the various parts of the model
-
~CppModuleTemplate() override
Module Destructor.
-
void Reset(uint64_t CurrentSimNanos) override
Reset the counter and publish a zero output payload.
This method is used to reset the module.
Note
The sampleConfigVector configuration is preserved.
- Parameters:
CurrentSimNanos – [ns] Time at which the module is reset.
-
void UpdateState(uint64_t CurrentSimNanos) override
Add the update counter to the first component of the optional input vector.
- Parameters:
CurrentSimNanos – [ns] Time at which the module is updated.
-
void setUpdateCounter(double value)
Demonstrate scalar assignment and validation using the runtime counter.
Note
Reset() always clears the counter, including after this setter is used.
- Parameters:
value – [-] Positive counter value.
-
inline double getUpdateCounter() const
Read the runtime counter, for example for variable logging.
- Returns:
[-] Current counter value.
-
void setSampleConfigVector(std::array<double, 3> value)
Set the sample configuration vector used for variable logging.
Note
Reset() preserves this vector. The vector is unused by the output calculation.
- Parameters:
value – [-] Sample vector with positive components.
-
inline std::array<double, 3> getSampleConfigVector() const
Read the sample configuration vector.
- Returns:
[-] Current sample vector.
Public Members
-
Message<CModuleTemplateMsgPayload> dataOutMsg
attitude navigation output msg
-
ReadFunctor<CModuleTemplateMsgPayload> dataInMsg
translation navigation output msg
-
BSKLogger bskLogger
BSK Logging.
-
CppModuleTemplate()