Creating New Message Types#

File Locations#

Message payload structs are plain header files stored in a single folder:

src/architecture/msgPayloadDef/

All payloads use C-compatible types so they can be used from both C and C++ modules.

Naming Convention#

  • Use upper camel case starting with a capital letter.

  • The file name must end with ...MsgPayload.h.

  • Example: SomeMsgPayload.h.

Struct Definition#

A payload file contains a single typedef struct with a Doxygen brief and per-field documentation:

#ifndef SOME_MSG_PAYLOAD_H
#define SOME_MSG_PAYLOAD_H

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

#endif

Key points:

  • The #ifndef / #define include guard prevents double inclusion.

  • The struct name must match the file name (minus the .h extension) and end with MsgPayload.

  • The payload is just the data. The message object (Message<T>) wraps a payload together with a header that tracks write time and author.

Generating Interface Files#

After adding a new payload header, register it in src/architecture/msgPayloadDef/CMakeLists.txt by adding a call to the CMake helper:

xmera_add_swig_message(SomeMsgPayload)

Then rebuild the project. CMake will auto-generate the required SWIG interface files for the new message type.

Custom SWIG Interface Template#

By default, xmera_add_swig_message() uses a standard template (msgInterfacePy.i.in) that handles the common case where the payload is a single self-contained struct.

If a payload references another struct that SWIG must also know about — for example a nested array-of-structs field — you can supply a custom .i template via the TEMPLATE parameter:

xmera_add_swig_message(AccDataMsgF32Payload
                       TEMPLATE
                       "${CMAKE_CURRENT_SOURCE_DIR}/AccDataMsgF32Payload.i")

The custom template adds %include directives and STRUCTASLIST() calls for the nested payload type so that SWIG generates the correct Python bindings. It uses {type} and {baseDir} placeholders that CMake substitutes at generation time.

A real-world example is located at src/fp32-fsw-xmera-2/algorithms/msgPayloadDef/AccDataMsgF32Payload.i.

Next Steps#