Creating New Message Definitions

Msg File Location

The preferred message definition uses only C code to define a struct which contains the message data. This is written in a stand-alone *.h file located in the src/architecture/msgPayloadDefC folder.

If the message struct definition needs to include C++ code, then the stand-alone message definition file is stored in src/architecture/msgPayloadDefCpp folder.

The *.h file name need to be upper camel case (start with a capital letter) and end with ...MsgPayload.h. An example is SomeMsgPayload.h.

Msg Data Definition

The message data is defined through a struct definition. For example, assume the new message is to be of type SomeMsg:

#ifndef SOME_MSG_H
#define SOME_MSG_H

/*! @brief Brief description of what this message contains */
typedef struct {
    int variable1;              //!< [units] variable description
    double variable2[3];        //!< [units] variable description
}SomeMsgPayload;

#endif

The #ifndef statement ensures this header file is only included once when compiling. The struct definition needs to have the message type name followed by MsgPayload. In this case it is SomeMsgPayload. The msg payload is the data of the message. This is in contrasts to the message object which contains a copy of this message payload, as well as a message header.

Creating the Msg C/C++ Swig Interface Files

To create message objects in C and C++ modules, build Basilisk after adding the message definition. The initial python3 conanfile.py build auto-creates the corresponding C module interface files and stores them in basilisk/dist3/autoSource/cMsgCInterface. The C++ message objects are automatically created as template classes using the *.h definitions in msgPayloadDefC. Naturally, no C module interface files are created for *.h files in msgPayloadDefCpp.

Once dist3 is configured, a normal incremental build detects added, renamed, or deleted payload definitions and automatically reconfigures CMake as needed:

cmake --build dist3 --parallel 12

Running python3 conanfile.py again is also valid when the Conan or CMake configuration needs to be refreshed. It preserves unchanged generated and compiled products, so it does not turn an otherwise incremental build into a clean build.

The generated Python messaging package is written from the current payload manifest. When a *Payload.h file is renamed or deleted, the build removes that payload’s stale generated source, Python wrapper, metadata, and compiled extension artifacts. A clean build is therefore not required to prevent an obsolete message type from remaining importable.

For the Basilisk module to have python interfaces to the module messages, you must include the message definition ...MsgPayload.h file in the module swig interface file *.i. See Swig Interface File for an example on how to do this in a C++ module, and Swig Interface File on how to do this for a C module.