They are especially useful because they automatically derive the correct queue item size from the selected `PBEnvelope` payload member, which helps avoid one of the easiest mistakes in this module: mismatching `item_size` with the actual decoded protobuf payload type.
### Why these macros are useful Without these macros, every handler config has to manually specify: - queue storage buffer - queue length - item size - task name - default priority - default stack depth - queue initialization fields That is tedious and error-prone. #### I) They derive `item_size` automatically Each macro uses: `sizeof(((PBEnvelope*)0)->payload.payload_member)` to compute the exact size of the selected envelope payload member at compile time. This removes the need to manually write `.item_size = sizeof(MyPayloadType)` and reduces the chance of queue item size mismatches. #### II) They allocate queue storage automatically Each macro also declares: ```c static uint8_t name##_queue_buffer[...]; ``` with the correct total size based on: - payload member size - selected queue length So the queue backing storage is generated alongside the config object. ### Important consequence of these macrosThese macros define **static objects**.
That means each use creates: - a static queue buffer - a static `packet_handler_config_t`This is generally what you want for a dispatcher configuration that should live for the full lifetime of the system.
It also means: - they should normally be used at file scope - using the same `name` twice in one translation unit will cause symbol redefinition - they are not runtime factory macros, they are compile-time object definition helpers --- ## **Shared Functionality** For **all** of these macros, the generated config uses: ```c #define PACKET_HANDLER_CONFIG_STATIC(name, packet_tag, payload_member_size, handler_fn) .handler = (handler_fn) .task_name = #name .packet_type = (packet_tag) .item_size = payload_member_size .queue_buffer = name##_queue_buffer .queue_struct = {0} .queue = NULL ``` This is helpful for two reasons: - `task_name` is automatic The task name becomes **the same as the symbol (handler config itself) name**, which keeps config definitions compact and readable. - Queue internals are initialized consistently The queue control structure is zero-initialized, and the runtime queue handle starts as `NULL`, matching the expectations of the dispatcher startup code. ### IMPORTANT NOTE on `payload_member`The `payload_member` argument is not the packet type name. It is the **member name inside** `PBEnvelope.payload`**!**
This matters because the macros compute size using direct member access syntax: `sizeof( ((PBEnvelope*)0) -> payload.payload_member)`. **So, if the wrong member name is used, compilation will fail, which is actually helpful for once.** **The member names are defined in** `envelope.pb.h` **.** For example, currently `envelope.pb.h` contains the following: ```c typedef struct _PBEnvelope { pb_size_t which_payload; union _PBEnvelope_payload { /* Sensorboard messages */ SensorBoardPHInfo ph_info; /* Armboard messages */ ArmBoardControlSignals arm_ctrl; ArmBoardDiagnostics arm_diag; //etc etc... } } ```So, the macro must be called with the member name **matching the rest of the config**, such as `ph_info` or `arm_ctrl` and **NOT** the protobuf struct type name!
--- ## **Available macros** ### 1) Default configuration macros The header defines these default values: ```none #define PACKET_HANDLER_DEFAULT_PRIORITY (tskIDLE_PRIORITY + 2U) #define PACKET_HANDLER_DEFAULT_QUEUE_LENGTH (5U) #define PACKET_HANDLER_DEFAULT_STACK_DEPTH (0U) ``` - `PACKET_HANDLER_DEFAULT_PRIORITY` Default FreeRTOS task priority assigned to handler tasks created with the simpler macros. - `PACKET_HANDLER_DEFAULT_QUEUE_LENGTH` Default number of queued packets per handler. - `PACKET_HANDLER_DEFAULT_STACK_DEPTH` Default stack depth field stored in the config. A value of `0U` is intentional here. In the dispatcher implementation, a task stack depth of zero is treated as “use the dispatcher default,” which becomes: `PACKET_HANDLER_TASK_STACK_DEPTH_DEFAULT`. So this macro does **not** mean “zero stack.” It means “defer to the runtime default chosen by the dispatcher.” --- ### 2) Basic config: `PACKET_HANDLER_CONFIG_STATIC` ``` #define PACKET_HANDLER_CONFIG_STATIC(name, packet_tag, payload_member_size, handler_fn) ``` This is the simplest form. Creates a handler config using: - **default** priority - **default** queue length - **default** stack depth behaviour ##### Parameters - `name` User defined name, go crazy. - `packet_tag` This is the Nanopb generated tag for the packet type. They follow the pattern `PBEnvelope_[`*`payload_member`*`]_tag`. So for example: PBEnvelope\_arm\_ctrl\_tag - `payload_member` See [important note on payload\_member](#header-3a64 "IMPORTANT NOTE on payload_member"). **Needs to match the packet\_tag and the buffer type the callback is specified for!** - `handler_fn` Callback function. Type signature [packet\_handler\_t](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/functions-of-the-packet-dispatcher#bkmrk-a.-packet_handler_t- "Functions of the packet dispatcher"). ##### ##### Example ```c /* Config for: ArmBoardMovementFeedback */ //Define the callback function with the specified signature static result_t Callback_ArmBoardMovementFeedback(void *buffer) { if (buffer == NULL) { return RESULT_ERR_INVALID_ARG; } //Retreive the packet ArmBoardMovementFeedback* pckt = (ArmBoardMovementFeedback *)buffer; //Get all fields pckt->arm_error; /* Go wild... */ return RESULT_OK; } PACKET_HANDLER_CONFIG_STATIC( Handler_ArmBoardMovementFeedback, // NOTE: This name is USER DEFINED, let your imagination run PBEnvelope_arm_feedback_tag, // Make sure these... arm_feedback, // ... MATCH! Callback_ArmBoardMovementFeedback); // Callback as above ``` --- ### 3) Full config: `PACKET_HANDLER_CONFIG_STATIC_EX` ```none #define PACKET_HANDLER_CONFIG_STATIC_EX(name, packet_tag, payload_member, handler_fn, priority_, stack_depth_, queue_length_) ``` Full explicit version. Lets you set: - name, packet\_tag, payload\_member, handler\_fn as above - **custom** priority - **custom** stack depth - **custom** queue length ##### Best used when - the handler needs a non-default stack size - you want fully explicit resource configuration ##### Example ```c PACKET_HANDLER_CONFIG_STATIC_EX(vision_handler_cfg, PBEnvelope_detected_object_tag, detected_object, handle_detected_object, tskIDLE_PRIORITY + 3U, 768U, 16U); ``` --- ###