In practical terms, it is a **decode-and-dispatch layer** between an **input source** that receives raw bytes and **a set of application handlers** that want already-decoded payloads
The implementation has **some assumptions and hazards** that absolutely need to be understood before you start messing with its internal structure.
--- ## **High-level design** The design has three major parts: - Global handler registry The global handler registry contains an **array** of packet handler tasks (see [packet\_handler\_config\_t](https://bookstack.roboteamtwente.nl/link/229#bkmrk-b.-packet_handler_co) ). A packet handler task configures (amongst other things) the callback function for a certain type of packet. The array of configs is given by the caller at initialization time. This array is stored globally and **used by dispatch logic for packet type lookup**.What we call a **packet** is a raw protobuf. What we call a **handler** is a (configuration of a) callback function for a specific protobuf/packet.
- One queue & task per packet type The dispatcher takes each handler configuration and creates **1 FreeRTOS queue** and **1 FreeRTOS task**. When receiving messages, the dispatcher enqueues decoded payloads into the corresponding queue. **The corresponding task blocks that queue and calls the handler callback** (which saved in the registry).The task takes the **correspoding** payload out of the queue and calls the specified handler/callback function. By corresponding we mean that each type of packet has their own queue.
- Shared decode step Incoming frames are decoded into a global static `PBEnvelope` object: `static PBEnvelope DecodingEnvelopeCurrent;`. The dispatcher then copies `DecodingEnvelopeCurrent.payload` into a handler queue. **This detail matters a lot for concurrency and payload sizing.** #### NOTE on handler task lifecyclesEach handler task is intended to live forever.
A task is responsible for passing a specific packet type from the corresponding queue to the correct callback. As stated above, a handler task **gets created by the dispatcher** according to the configuration (see [packet\_handler\_config\_t](https://bookstack.roboteamtwente.nl/link/229#bkmrk-b.-packet_handler_co) ) done by the caller when initializing the dispatcher. ##### Lifecycle 1. **Created by** `PacketHandlerStart()` As part of [PacketDispatcherInit()](#bkmrk-c.-packetdispatcheri "c. PacketDispatcherInit()"). 2. **Validate configuration** Task\_name, handler and queue need to be present for it to work. These params are set in [packet\_handler\_config\_t](https://bookstack.roboteamtwente.nl/link/229#bkmrk-b.-packet_handler_co). If you use the [macros](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/helper-macros-for-handler-config "Helper Macros for Static Handler Config"), this should be fine. 3. **Allocate local packet buffer** 4. **Block forever on queue receive** So, when we receive a packet in the corresponding queue, we wait for it to be handled. 5. **Process packets as they arrive** The processing is done by the callback specified in the handler. ##### Terminates only if... - config is **invalid** - queue is **null** - heap **allocation fails** for packet buffer In those cases it deletes itself.At the moment, there is no restart or supervision mechanism in this module!
--- ## **External dependencies**This is not a standalone module. It sits in the middle of RTOS tasking, protobuf decoding, and transport reception.
This module depends on:| **specifically used pieces** | |
| FreeRTOS | - `xQueueCreateStatic` - `xQueueReceive` - `xQueueSend` - `xTaskCreate` - `vTaskDelete` |
| nanopb / protobuf decoding | - `pb_istream_from_buffer` - `pb_decode` |
| `PBEnvelope` generated protobuf definitions | - `PBEnvelope_fields` - `PBEnvelope_size` |
| [Logging library](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/logging "Logging") | |
| [Result Library](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/result-library "Result Library") | |
| `stm/ethernet_udp.h` | - `receive_frame` |
**NOTE:** `PACKET_DISPATCHER_TASK_STACK_DEPTH` is currently defined but not actually used in the provided implementation!
```none #define PACKET_HANDLER_TASK_STACK_DEPTH_DEFAULT ((configSTACK_DEPTH_TYPE)512U) #define PACKET_DISPATCHER_TASK_STACK_DEPTH ((configSTACK_DEPTH_TYPE)1024U) ``` --- ### 2) packet\_handler\_t (callback) ```c typedef result_t (*packet_handler_t)(void* buffer); ``` This type represents the **callback function** invoked by a **handler task** when a packet of its type is received. #### Parameters - `buffer` Pointer to the **decoded packet payload** copied from the queue. The actual type of `buffer` depends on the registered `packet_type` in the config for the handler (see [packet\_handler\_config\_t](#bkmrk-b.-packet_handler_co "b. packet_handler_config_t (struct)")). For example, if a handler is registered for one specific protobuf payload type, the handler should cast `buffer` to the corresponding generated struct type.The callback receives only a raw `void *`. That means type safety is **entirely dependent on correct configuration!**
- `packet_type` must match the actual protobuf payload member - `item_size` must match the size of that decoded payload type - handler must cast `buffer` to the correct struct type If any of those mismatch, the code may compile while quietly doing something stupid (and it will be your fault :D). #### Return value Returns `result_t`. The handler task logs a warning if the return value is not `RESULT_OK`. --- ### 3) packet\_handler\_config\_t (struct)**NOTE:** there exist macros to make the configuration easier! **See:** [Helper Macros for Static Handler Config](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/helper-macros-for-handler-config "Helper Macros for Static Handler Config")
```c typedef struct { packet_handler_t handler; const char* task_name; pb_size_t packet_type; UBaseType_t task_priority; configSTACK_DEPTH_TYPE task_stack_depth; size_t item_size; UBaseType_t queue_length; uint8_t* queue_buffer; StaticQueue_t queue_struct; QueueHandle_t queue; } packet_handler_config_t; ``` #### Purpose Describes one packet type and the task/queue resources needed to process it. **Each entry in the handler config array** (passed to [PacketDispatcherInit(...)](#bkmrk-c.-packetdispatcheri "c. PacketDispatcherInit(...)")) **corresponds to one routed packet type!** #### Fields - `handler` Callback invoked when a packet of this type is received. Must not be `NULL`. - `task_name` Name used when creating the FreeRTOS task. Must not be `NULL`. - `packet_type` The protobuf discriminator value to match against `DecodingEnvelopeCurrent.which_payload`, which is the routing key. - `task_priority` Priority of the FreeRTOS handler task. If set to zero, that is still a valid FreeRTOS priority value. There is no separate “unset” semantic here. - `task_stack_depth` Stack depth for the handler task. If `<= 0`, the implementation replaces it with: `PACKET_HANDLER_TASK_STACK_DEPTH_DEFAULT`. Since this type is typically unsigned, the `<= 0` check effectively means “zero” in practice. - `item_size` Size of **one** queued item.This must match the size of the decoded payload type copied into the queue.
- `queue_length` Number of items the queue can hold. - `queue_buffer` Backing storage for static queue data. Must be large enough for `queue_length * item_size` - `queue_struct` Static queue control structure used internally by `xQueueCreateStatic()`. Caller provides storage but should not manually initialize runtime content. - `queue` Queue handle written internally during initialization.Caller should not pre-fill it!
--- ### 4) PacketDispatcherInit(...) ```c result_t PacketDispatcherInit(packet_handler_config_t* handlers, size_t handler_count); ``` **Initializes the dispatcher** by... - storing the handler registry - creating **one queue** and **one task** per handler entry #### Parameters - `handlers` Pointer to an array of handler configurations (see above: [packet\_handler\_config\_t](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/packet-dispatcher#bkmrk-b.-packet_handler_co "b. (struct) packet_handler_config_t")). The implementation stores a global pointer to it and passes individual entries to tasks. - `handler_count` Number of entries in the array.**IMPORTANT:** The `handlers` array **must remain valid for the full lifetime** of the system. Do **NOT** allocate this array on a temporary stack frame unless you are into being abused by segfaults :)
--- ### 5) DispatchPacket(...) ```c void DispatchPacket(receive_frame* incoming_packet); ``` **Decodes** one incoming raw frame and **routes** its decoded payload to the appropriate handler queue. ##### Internal functioning 1. validates basic frame properties 2. creates a nanopb input stream from the raw bytes 3. decodes into the global static `DecodingEnvelopeCurrent` 4. scans the registered handler list 5. finds the first handler whose `packet_type` matches `which_payload` 6. sends `DecodingEnvelopeCurrent.payload` to that handler’s queue 7. returns If no matching handler is found, it logs a warning. If decode fails, it logs an error.**NOTE:** This function returns `void`, so dispatch failure is **only observable through logs**.
#### Parameters - `incoming_packet` Pointer to a transport frame containing `payload`, `len` of the incoming packet. --- ## **Internal (private) task model** ### `PacketHandlerTask()`Also see [note on handler task lifecycles](https://bookstack.roboteamtwente.nl/link/228#bkmrk-note-on-handler-task) !
Each handler config gets its own task (and corresponding queue, remember ladies?) running this loop: 1. validate config and resources 2. allocate one packet buffer using `malloc(conf->item_size)` 3. block forever on `xQueueReceive()` 4. when a packet arrives: - call `conf->handler(packet_buffer)` - log if handler returns error #### Purpose of per-task buffer The queue copies incoming items into the task’s local `packet_buffer`. That means the handler callback receives a stable task-local buffer for the duration of the callback. The callback does **not** receive a pointer directly into the global decode object.The task allocates its buffer dynamically with `malloc()` once at startup and never frees it, because the task is intended to live forever.
--- ## **Macros**There exist macros to make the configuration of a handler easier! See: [Helper Macros for Static Handler Config](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/helper-macros-for-handler-config "Helper Macros for Static Handler Config").
## # Helper Macros for Handler Config ## **Purpose** To reduce repetitive boilerplate when defining packet handlers, the module also provides a set of helper macros in `packet_dispatcher_macros.h`. These macros generate: - a statically allocated queue buffer - a fully initialized `packet_handler_config_t`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); ``` --- ###More information on the mentioned steps can be found in [Functions of the Packet Dispatcher](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/functions-of-the-packet-dispatcher "Functions of the Packet Dispatcher")
--- ## **Typical Usage Model** ### Intended setup 1. Define one [handler function](https://bookstack.roboteamtwente.nl/link/229#bkmrk-2%29-packet_handler_t-) per packet type 2. define one [packet\_handler\_config\_t](https://bookstack.roboteamtwente.nl/link/229#bkmrk-2%29-packet_handler_co) entry per packet type (using the [macros](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/helper-macros-for-handler-config "Helper Macros for Handler Config")) 3. provide queue storage buffers (When using the [macros](https://bookstack.roboteamtwente.nl/books/embedded-infastructure/page/helper-macros-for-handler-config), you do not need to do this manually) 4. call [PacketDispatcherInit(...)](https://bookstack.roboteamtwente.nl/link/229#bkmrk-4%29-packetdispatcheri) 5. whenever a frame arrives, call [DispatchPacket()](https://bookstack.roboteamtwente.nl/link/229#bkmrk-5%29-dispatchpacket%28..) ### Flow after setup 1. Ethernet/UDP receives raw frame 2. networking code builds `receive_frame` 3. `DispatchPacket()` decodes it 4. payload type is matched 5. decoded payload is copied into target queue 6. matching handler task wakes 7. the callback processes typed payload --- ## **IMPORTANT configuration rules**This module is heavily configuration-driven. Several things must match exactly.
#### I. `packet_type` must match the protobuf discriminator Each handler’s `packet_type` must be the exact value used by `PBEnvelope.which_payload`. If this is wrong, packets will never reach that handler. #### II. `item_size` must match the decoded payload type The queue copies bytes from `&DecodingEnvelopeCurrent.payload` into a queue item of size `item_size`. If `item_size` is: - too small -> payload will be truncated - too large -> copied data may include unrelated union bytes or layout assumptions - wrong type entirely -> handler sees garbage with confidence #### III. `queue_buffer` must be sized correctly The backing storage must be at least: `queue_length * item_size`. **If not, queue creation or runtime behavior is invalid.** #### IV. Handler must cast `void *` correctly The callback receives a raw buffer pointer. It must cast to the correct generated protobuf type. #### V. Handlers array must be an array of structs The current `PacketDispatcherInit()` API expects: ```c packet_handler_config_t* handlers ``` meaning a contiguous array of structs, not an array of pointers. So with the current implementation, the final array should actually be: ```c static packet_handler_config_t* handlers[] = { drive_handler_cfg, sensor_diag_handler_cfg, }; ``` NOT an array of pointers. --- ## **Examples** ### 1) Using macros ```c //Imports #include "packet_dispatcher.h" #include "packet_dispatcher_macros.h" /*Define handler callbacks*/ //Callback for protobuf of type ArmBoardMovementFeedback static result_t Callback_ArmBoardMovementFeedback(void *buffer) { if (buffer == NULL) { return RESULT_ERR_INVALID_ARG; } ArmBoardMovementFeedback* pckt = (ArmBoardMovementFeedback *)buffer; //Retreive the packet pckt->arm_error; //Get fields of protobuf //Do something... return RESULT_OK; } //Config using most basic macro PACKET_HANDLER_CONFIG_STATIC(Handler_ArmBoardMovementFeedback, PBEnvelope_arm_feedback_tag, arm_feedback, Callback_ArmBoardMovementFeedback); //Callback for protobuf of type ArmBoardControlSignals static result_t Callback_ArmBoardControlSignals(void *buffer) { if (buffer == NULL) { return RESULT_ERR_INVALID_ARG; } ArmBoardControlSignals* pckt = (ArmBoardControlSignals *)buffer; pckt->control_base; //Get fields of protobuf pckt->control_gripper_pitch; //... etc etc //Do something... return RESULT_OK; } //Config using most basic macro PACKET_HANDLER_CONFIG_STATIC(Handler_ArmBoardControlSignals, PBEnvelope_arm_ctrl_tag, arm_ctrl, Callback_ArmBoardControlSignals); //Add configs to the list of configs static packet_handler_config_t* handlers[] = {Handler_ArmBoardMovementFeedback, Handler_ArmBoardControlSignals}; //HERE WE PUT ETH_init(...) and the creation of queues from the networking board //See respective documentation PacketDispatcherInit(handlers, 2); ETH_udp_init(2, queues, DispatchPacket); //Passing DispatchPacket to ETH_udp_init makes sure it gets called upon receiving msgs //Once again, after this we can use networking and do ETH_add_arp(...) and ETH_udp_send(...) ``` --- ### 2) Manual configuration ```c //Imports #include "packet_dispatcher.h" static result_t handle_drive_cmd(void* buffer) { PBDriveCommand* msg = (PBDriveCommand*)buffer; return drive_process(msg); } static result_t handle_arm_cmd(void* buffer) { PBArmCommand* msg = (PBArmCommand*)buffer; return arm_process(msg); } static uint8_t drive_queue_storage[8 * sizeof(PBDriveCommand)]; static uint8_t arm_queue_storage[4 * sizeof(PBArmCommand)]; static packet_handler_config_t handlers[] = { { .handler = handle_drive_cmd, .task_name = "drive_pkt", .packet_type = PBEnvelope_drive_cmd_tag, .task_priority = 3, .task_stack_depth = 512, .item_size = sizeof(PBDriveCommand), .queue_length = 8, .queue_buffer = drive_queue_storage, }, { .handler = handle_arm_cmd, .task_name = "arm_pkt", .packet_type = PBEnvelope_arm_cmd_tag, .task_priority = 3, .task_stack_depth = 512, .item_size = sizeof(PBArmCommand), .queue_length = 4, .queue_buffer = arm_queue_storage, }, }; ``` Then during startup: ```c result_t res = PacketDispatcherInit(handlers, ARRAY_LEN(handlers)); ``` And during frame reception: ```c DispatchPacket(&rx_frame); ``` ####