can-api-generator 2.5.0__tar.gz → 2.6.0__tar.gz

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: can-api-generator
-Version: 2.5.0
+Version: 2.6.0
 Summary: Program to generate a 'signal' style CAN API in C
 Project-URL: Documentation, https://sr.ht/~laplace/can-api-generator#readme
 Project-URL: Issues, https://sr.ht/~laplace/can-api-generator/issues
@@ -244,6 +244,31 @@ slot (`now % period == offset`); the missed slot is skipped, not caught up.
 The `tx_callback` rules are unchanged: in callback-only mode a `NULL` return queues nothing, and `send_now` stays set as well. Works with and without
 `--tx-signal-store`.
 
+#### Delta timing (`--tx-timing delta`)
+By default `<api>_periodic_tx` takes an absolute time and fires a message only when `now % period == offset`, so it has to be called on every tick. With
+`--tx-timing delta` it instead takes the number of ticks elapsed since the previous call, and each message counts down on its own:
+```c
+void <api>_periodic_tx_init(struct <Prefix>TxSignals *tx_signals);
+uint16_t <api>_periodic_tx(struct <Prefix>TxSignals *tx_signals, CanFrame *output_frame, uint32_t dt);
+
+uint32_t dt = now - prev;
+prev = now;
+while (<api>_periodic_tx(&tx_signals, &frame, dt)) {
+    send(&frame);
+    dt = 0;  // drain the other messages that fell due
+}
+```
+Every message whose countdown runs out during `dt` is marked pending; one pending frame is returned per call, in message order, and the rest are drained by calling
+again with `dt = 0`. With `--tx-function` there is no draining: one call hands every pending message to the sink, and a frame the sink rejects stays pending and is
+retried on the next call (unlike absolute timing, where the slot is missed).
+If `dt` spans several periods (a stall), the message is sent once and rescheduled to the next slot on its original grid, so its phase does not change. A message
+whose countdown runs out while `enable` is 0 is skipped, but its countdown keeps running. In callback-only mode a `NULL` callback return sends nothing for that slot.
+`send_now` behaves as with absolute timing; if it coincides with a due slot, a single frame is sent.
+
+In `MsgTxContext`, `last_tx` is replaced by `remaining` (ticks until the next slot) and `pending`. `<api>_periodic_tx_init` takes no time argument, and
+`<api>_update_tx_period(ctx, period)` re-phases the message to `offset + 1` ticks from the next call.
+`--time-as-tx-callback-arg` cannot be combined with delta timing, as there is no absolute time to pass.
+
 ### Encode All Signals
 Some messages use multiplexes combining many signals in to a single message. This may be particularly true for configuration messages that have many related parameters and use
 multiplexes to fit all parameters in to a single message using many mux groups. If the entire config should be read out and the read back happens periodically, the supervisory controller
@@ -666,6 +691,8 @@ Options:
   `<api>_periodic_tx(tx_signals, now)` then queues every due message through it in one pass and returns the number accepted. A 0 return leaves `last_tx` and
   `send_now` untouched so the message is retried. See [Queueing frames through a bound TX function](#queueing-frames-through-a-bound-tx-function). Only meaningful
   together with `-p`.
+* `--tx-timing [absolute|delta]` — `absolute` (default) passes the current time to `<api>_periodic_tx`; `delta` passes the ticks since the previous call. See
+  [Delta timing](#delta-timing---tx-timing-delta). Only meaningful together with `-p`; cannot be combined with `--time-as-tx-callback-arg`.
 * `--rx-signal-store` — generate the permanent per-message RX signal store (the pre-2.0 default). Without it, global RX is callback-only: no store is
   generated and decoded signals reach the application only through the RX callback. See [Global RX](#global-rx). Only meaningful together with `-r`.
 * `--with-rx-valid` — in callback-only mode, add a `valid` field to `MsgRxContext` and set it on each matched frame, for struct-layout compatibility with
@@ -682,6 +709,8 @@ Options:
   to an existing project's frame struct naming.
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
+* `--seed INT` — seed the random number generator that picks each periodic message's `offset_seed`, so repeated runs produce identical output.
+  Unseeded by default, so every run picks new values.
 * `-v`, `--verbose` — dump the processed message dicts that get fed into the Jinja templates. Useful when debugging template or generator changes.
 * `--help` — show the CLI help and exit.
 
@@ -722,11 +751,15 @@ Options:
 ### Config file
 
 Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
-one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
-underscores both work), and values are the option values (`true`/`false` for flags):
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` or the
+positional argument names (dashes or underscores both work), and values are the option values (`true`/`false` for flags). A relative `db-file` is resolved
+against the config file's directory; output files are still written to the working directory.
 
 ```yaml
 api:
+  db-file: db.kcd
+  library-name: my_api
+  node-name: DUT
   periodic-tx: true
   tx-signal-store: true
   time-as-tx-callback-arg: true
@@ -736,5 +769,5 @@ dyndec:
 ```
 
 Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
-`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
-the command line. An unknown key or an invalid value is an error.
+`can-api-gen api --config can.yaml --no-tx-signal-store`. Positional arguments given on the command line fill from the left and take precedence over the
+file, so `can-api-gen api --config can.yaml other.kcd other_api DUT` ignores all three from the file. An unknown key or an invalid value is an error.

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/README.md

@@ -218,6 +218,31 @@ slot (`now % period == offset`); the missed slot is skipped, not caught up.
 The `tx_callback` rules are unchanged: in callback-only mode a `NULL` return queues nothing, and `send_now` stays set as well. Works with and without
 `--tx-signal-store`.
 
+#### Delta timing (`--tx-timing delta`)
+By default `<api>_periodic_tx` takes an absolute time and fires a message only when `now % period == offset`, so it has to be called on every tick. With
+`--tx-timing delta` it instead takes the number of ticks elapsed since the previous call, and each message counts down on its own:
+```c
+void <api>_periodic_tx_init(struct <Prefix>TxSignals *tx_signals);
+uint16_t <api>_periodic_tx(struct <Prefix>TxSignals *tx_signals, CanFrame *output_frame, uint32_t dt);
+
+uint32_t dt = now - prev;
+prev = now;
+while (<api>_periodic_tx(&tx_signals, &frame, dt)) {
+    send(&frame);
+    dt = 0;  // drain the other messages that fell due
+}
+```
+Every message whose countdown runs out during `dt` is marked pending; one pending frame is returned per call, in message order, and the rest are drained by calling
+again with `dt = 0`. With `--tx-function` there is no draining: one call hands every pending message to the sink, and a frame the sink rejects stays pending and is
+retried on the next call (unlike absolute timing, where the slot is missed).
+If `dt` spans several periods (a stall), the message is sent once and rescheduled to the next slot on its original grid, so its phase does not change. A message
+whose countdown runs out while `enable` is 0 is skipped, but its countdown keeps running. In callback-only mode a `NULL` callback return sends nothing for that slot.
+`send_now` behaves as with absolute timing; if it coincides with a due slot, a single frame is sent.
+
+In `MsgTxContext`, `last_tx` is replaced by `remaining` (ticks until the next slot) and `pending`. `<api>_periodic_tx_init` takes no time argument, and
+`<api>_update_tx_period(ctx, period)` re-phases the message to `offset + 1` ticks from the next call.
+`--time-as-tx-callback-arg` cannot be combined with delta timing, as there is no absolute time to pass.
+
 ### Encode All Signals
 Some messages use multiplexes combining many signals in to a single message. This may be particularly true for configuration messages that have many related parameters and use
 multiplexes to fit all parameters in to a single message using many mux groups. If the entire config should be read out and the read back happens periodically, the supervisory controller
@@ -640,6 +665,8 @@ Options:
   `<api>_periodic_tx(tx_signals, now)` then queues every due message through it in one pass and returns the number accepted. A 0 return leaves `last_tx` and
   `send_now` untouched so the message is retried. See [Queueing frames through a bound TX function](#queueing-frames-through-a-bound-tx-function). Only meaningful
   together with `-p`.
+* `--tx-timing [absolute|delta]` — `absolute` (default) passes the current time to `<api>_periodic_tx`; `delta` passes the ticks since the previous call. See
+  [Delta timing](#delta-timing---tx-timing-delta). Only meaningful together with `-p`; cannot be combined with `--time-as-tx-callback-arg`.
 * `--rx-signal-store` — generate the permanent per-message RX signal store (the pre-2.0 default). Without it, global RX is callback-only: no store is
   generated and decoded signals reach the application only through the RX callback. See [Global RX](#global-rx). Only meaningful together with `-r`.
 * `--with-rx-valid` — in callback-only mode, add a `valid` field to `MsgRxContext` and set it on each matched frame, for struct-layout compatibility with
@@ -656,6 +683,8 @@ Options:
   to an existing project's frame struct naming.
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
+* `--seed INT` — seed the random number generator that picks each periodic message's `offset_seed`, so repeated runs produce identical output.
+  Unseeded by default, so every run picks new values.
 * `-v`, `--verbose` — dump the processed message dicts that get fed into the Jinja templates. Useful when debugging template or generator changes.
 * `--help` — show the CLI help and exit.
 
@@ -696,11 +725,15 @@ Options:
 ### Config file
 
 Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
-one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
-underscores both work), and values are the option values (`true`/`false` for flags):
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` or the
+positional argument names (dashes or underscores both work), and values are the option values (`true`/`false` for flags). A relative `db-file` is resolved
+against the config file's directory; output files are still written to the working directory.
 
 ```yaml
 api:
+  db-file: db.kcd
+  library-name: my_api
+  node-name: DUT
   periodic-tx: true
   tx-signal-store: true
   time-as-tx-callback-arg: true
@@ -710,5 +743,5 @@ dyndec:
 ```
 
 Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
-`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
-the command line. An unknown key or an invalid value is an error.
+`can-api-gen api --config can.yaml --no-tx-signal-store`. Positional arguments given on the command line fill from the left and take precedence over the
+file, so `can-api-gen api --config can.yaml other.kcd other_api DUT` ignores all three from the file. An unknown key or an invalid value is an error.

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Alexande Becker <nabla.becker@mailbox.org>
 #
 # SPDX-License-Identifier: LGPL-3.0-only
-__version__ = "2.5.0"
+__version__ = "2.6.0"

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/code_generator.py

@@ -52,6 +52,7 @@ def generate_api_implementation(msgs: list[dict],
                                 tx_function: bool = False,
                                 time_as_rx_callback_arg: bool = False,
                                 time_as_tx_callback_arg: bool = False,
+                                tx_timing: str = "absolute",
                                 ):
     header_template = jinja_env.get_template("header_template.jinja")
     source_template = jinja_env.get_template("source_template.jinja")
@@ -94,6 +95,7 @@ def generate_api_implementation(msgs: list[dict],
         tx_function=tx_function,
         time_as_rx_callback_arg=time_as_rx_callback_arg,
         time_as_tx_callback_arg=time_as_tx_callback_arg,
+        tx_timing=tx_timing,
     )
     source_code = source_template.render(
         messages=msgs,
@@ -123,6 +125,7 @@ def generate_api_implementation(msgs: list[dict],
         tx_function=tx_function,
         time_as_rx_callback_arg=time_as_rx_callback_arg,
         time_as_tx_callback_arg=time_as_tx_callback_arg,
+        tx_timing=tx_timing,
     )
     canframe_header_code = canframe_template.render(
         arb_id_member_name=arb_id_member_name,

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/main.py

@@ -1,6 +1,7 @@
 from can_api_generator.types import SignalDirection
 from importlib.metadata import files
 import hashlib
+import random
 import json
 import click
 import rich
@@ -19,9 +20,10 @@ def _load_config(ctx, param, value):
     """Turn the command's section of a YAML config file into click defaults.
 
     The file maps command names to option tables, e.g. {"api": {"periodic-tx":
-    true}}. Keys are long option names (dashes or underscores). The values
-    become ctx.default_map, so every option given on the command line still
-    takes precedence over the file.
+    true}}. Keys are long option names or positional argument names (dashes
+    or underscores). The values become ctx.default_map, so everything given on
+    the command line still takes precedence over the file. Relative file
+    arguments are resolved against the config file's directory.
     """
     if value is None:
         return
@@ -39,14 +41,17 @@ def _load_config(ctx, param, value):
     if not isinstance(section, dict):
         raise click.BadParameter(
             f"section '{ctx.info_name}' must map option names to values", ctx, param)
-    known = {p.name for p in ctx.command.params
-             if isinstance(p, click.Option) and p.name != "config"}
+    known = {p.name: p for p in ctx.command.params if p.name != "config"}
     defaults = {}
     for key, option_value in section.items():
         name = str(key).replace("-", "_")
         if name not in known:
             raise click.BadParameter(
                 f"unknown option '{key}' in section '{ctx.info_name}'", ctx, param)
+        if (isinstance(known[name], click.Argument)
+                and isinstance(known[name].type, click.Path)
+                and isinstance(option_value, str)):
+            option_value = str(Path(value).parent / option_value)
         defaults[name] = option_value
     ctx.default_map = {**(ctx.default_map or {}), **defaults}
 
@@ -54,9 +59,9 @@ def _load_config(ctx, param, value):
 config_option = click.option(
     "--config", type=click.Path(exists=True, dir_okay=False),
     is_eager=True, expose_value=False, callback=_load_config,
-    help="YAML file providing defaults for this command's options, under a "
-         "section named after the command (api, cbdb, dyndec). Options given "
-         "on the command line override the file.")
+    help="YAML file providing defaults for this command's options and "
+         "arguments, under a section named after the command (api, cbdb, "
+         "dyndec). Anything given on the command line overrides the file.")
 
 
 @click.group()
@@ -171,6 +176,14 @@ def main():
                    "due message to it in a single pass and returns the number "
                    "accepted. A 0 return leaves last_tx and send_now untouched, "
                    "so the message is retried. Only meaningful with -p.")
+@click.option("--tx-timing", type=click.Choice(["absolute", "delta"]),
+              default="absolute", show_default=True,
+              help="Timing argument of the periodic tx function. 'absolute' takes "
+                   "the current time and sends a message when it hits its "
+                   "period/offset slot. 'delta' takes the ticks elapsed since the "
+                   "previous call and counts each message down; without "
+                   "--tx-function the messages that are due are sent one per call "
+                   "and drained by further calls with dt=0. Only meaningful with -p.")
 @click.option("--prefix-signal-struct-names/--no-prefix-signal-struct-names", default=False,
               help="Prefix every per-message signal struct type name with the "
                    "CamelCase API prefix (the same prefix used for "
@@ -182,6 +195,10 @@ def main():
                    "their include-guard tokens) with the CamelCase API prefix, so "
                    "context structs from two coexisting APIs do not share one "
                    "definition.")
+@click.option("--seed", type=int, default=None,
+              help="Seed for the random number generator that picks each "
+                   "message's offset_seed, so repeated runs produce identical "
+                   "output. Unseeded by default.")
 @click.option("-v", "--verbose/--no-verbose", default=False,
               help="Print the Data that is passed to the template that "
               "generates the code")
@@ -191,12 +208,18 @@ def api(db_file, library_name, node_name, force, encode_all_signals_func,
         rx_callback_context, tx_callback_context, msg_as_rx_callback_arg,
         rx_signal_store, with_rx_valid, msg_as_tx_callback_arg,
         tx_signal_store, time_as_rx_callback_arg, time_as_tx_callback_arg,
-        tx_function, prefix_signal_struct_names,
-        prefix_context_struct_names, verbose):
+        tx_function, tx_timing, prefix_signal_struct_names,
+        prefix_context_struct_names, seed, verbose):
     """
     Generate the static C API for NODE_NAME from DB_FILE (.kcd or .yaml)
     """
+    if seed is not None:
+        random.seed(seed)
     db_path = Path(db_file)
+    if tx_timing == "delta" and time_as_tx_callback_arg:
+        raise click.UsageError(
+            "--time-as-tx-callback-arg needs the absolute time and cannot be "
+            "combined with --tx-timing delta")
     try:
         basepath = Path(library_name)
         source_path = basepath.parent / f"{basepath.stem}.c"
@@ -263,6 +286,7 @@ def api(db_file, library_name, node_name, force, encode_all_signals_func,
         tx_function=tx_function,
         time_as_rx_callback_arg=time_as_rx_callback_arg,
         time_as_tx_callback_arg=time_as_tx_callback_arg,
+        tx_timing=tx_timing,
     )
     if not user_supplied_canframe:
         with (header_path.parent / 'canframe.h').open('w+') as canframe_header_file:

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/templates/header_template.jinja

@@ -47,17 +47,22 @@
 {%- endif %}
 {% endif %}
 {%- if periodic_tx %}
-{{ define_tx_context_struct(true, 'uint16_t', 'uint64_t', send_now, tx_callback_context=tx_callback_context, msg_as_tx_callback_arg=msg_as_tx_callback_arg, ctx_name=tx_context_struct_name, time_as_tx_callback_arg=time_as_tx_callback_arg) }}
+{{ define_tx_context_struct(true, 'uint16_t', 'uint64_t', send_now, tx_callback_context=tx_callback_context, msg_as_tx_callback_arg=msg_as_tx_callback_arg, ctx_name=tx_context_struct_name, time_as_tx_callback_arg=time_as_tx_callback_arg, tx_timing=tx_timing) }}
 
 {{ generate_global_tx_struct(messages, api_name_struct_prefix, double_buffered, tx_signal_store=tx_signal_store, ctx_name=tx_context_struct_name, can_frame_type=can_frame_type, tx_function=tx_function) }}
 
-{{ declare_periodic_tx_init_function(api_name, api_name_struct_prefix, 'uint64_t', can_frame_type, tx_function) }};
+{{ declare_periodic_tx_init_function(api_name, api_name_struct_prefix, 'uint64_t', can_frame_type, tx_function, tx_timing) }};
 
 {{ declare_get_msg_tx_context_by_id(messages, api_name, api_name_struct_prefix, 'struct ' ~ tx_context_struct_name) }};
 
-{{ declare_period_update_function(api_name, 'struct ' ~ tx_context_struct_name) }}
+{{ declare_period_update_function(api_name, 'struct ' ~ tx_context_struct_name, tx_timing) }}
+{%- if tx_timing == 'delta' %}
+
+{{ declare_periodic_tx_function(api_name, api_name_struct_prefix, can_frame_type, 'uint16_t', 'uint32_t', 'uint16_t', tx_function, 'dt') }};
+{%- else %}
 
 {{ declare_periodic_tx_function(api_name, api_name_struct_prefix, can_frame_type, 'uint16_t', 'uint64_t', 'uint16_t', tx_function) }};
+{%- endif %}
 {%- if double_buffered and tx_signal_store %}
 {%- for message in messages %}
 {%- if message.direction == 'tx' or message.direction == 'rt' %}

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/templates/source_template.jinja

@@ -7,6 +7,7 @@
 {% from "rx_macros.jinja" import generate_global_rx_frame_process_function -%}
 {% from "rx_macros.jinja" import define_global_rx_init_function -%}
 {% from "tx_macros.jinja" import define_periodic_tx_function -%}
+{% from "tx_macros.jinja" import define_periodic_tx_delta_function -%}
 {% from "tx_macros.jinja" import define_periodic_tx_init_function -%}
 {% from "tx_macros.jinja" import define_get_msg_tx_context_by_id -%}
 {% from "tx_macros.jinja" import define_commit_function -%}
@@ -21,12 +22,17 @@
 {%- endif %}
 {%- endif %}
 {%- if periodic_tx %}
+{%- if tx_timing == 'delta' %}
+
+{{ define_periodic_tx_delta_function(messages, api_name, api_name_struct_prefix, can_frame_type, 'uint16_t', 'uint16_t', true, send_now, double_buffered, tx_callback_context=tx_callback_context, msg_as_tx_callback_arg=msg_as_tx_callback_arg, tx_signal_store=tx_signal_store, tx_function=tx_function) }}
+{%- else %}
 
 {{ define_periodic_tx_function(messages, api_name, api_name_struct_prefix, can_frame_type, 'uint16_t', 'uint64_t', 'uint16_t', true, send_now, double_buffered, tx_callback_context=tx_callback_context, msg_as_tx_callback_arg=msg_as_tx_callback_arg, tx_signal_store=tx_signal_store, ctx_name=tx_context_struct_name, tx_function=tx_function, time_as_tx_callback_arg=time_as_tx_callback_arg) }}
+{%- endif %}
 
 {{ define_get_msg_tx_context_by_id(messages, api_name, api_name_struct_prefix, 'struct ' ~ tx_context_struct_name) }}
 
-{{ define_periodic_tx_init_function(api_name, api_name_struct_prefix, 'uint64_t', messages, '1000', double_buffered, tx_signal_store=tx_signal_store, can_frame_type=can_frame_type, tx_function=tx_function) }}
+{{ define_periodic_tx_init_function(api_name, api_name_struct_prefix, 'uint64_t', messages, '1000', double_buffered, tx_signal_store=tx_signal_store, can_frame_type=can_frame_type, tx_function=tx_function, tx_timing=tx_timing) }}
 {%- if double_buffered and tx_signal_store %}
 {%- for message in messages %}
 {%- if message.direction == 'tx' or message.direction == 'rt' %}

{can_api_generator-2.5.0 → can_api_generator-2.6.0}/src/can_api_generator/templates/tx_macros.jinja

@@ -2,13 +2,18 @@
 {% from "encoding_macros.jinja" import rotate_multiplex_func_call %}
 {% from "callback_macros.jinja" import callback_param_types, callback_args %}
 
-{% macro define_tx_context_struct(tx_callback, flag_type, time_type, send_now, tx_callback_context=false, msg_as_tx_callback_arg=false, ctx_name='MsgTxContext', time_as_tx_callback_arg=false) -%}
+{% macro define_tx_context_struct(tx_callback, flag_type, time_type, send_now, tx_callback_context=false, msg_as_tx_callback_arg=false, ctx_name='MsgTxContext', time_as_tx_callback_arg=false, tx_timing='absolute') -%}
 #ifndef {{ ctx_name | upper }}
 #define {{ ctx_name | upper }}
 struct {{ ctx_name }} {
     uint32_t arb_id;
     {{ flag_type }} enable;
+{%- if tx_timing == 'delta' %}
+    {{ flag_type }} pending;
+    uint32_t remaining;
+{%- else %}
     {{ time_type }} last_tx;
+{%- endif %}
     uint32_t period;
     uint32_t offset;
     uint32_t offset_seed;
@@ -25,10 +30,13 @@ struct {{ ctx_name }} {
 #endif
 {%- endmacro %}
 
-{% macro declare_period_update_function(api_name, context_type) -%}
+{% macro declare_period_update_function(api_name, context_type, tx_timing='absolute') -%}
 static inline void {{ api_name }}_update_tx_period({{ context_type }} *txctx, uint32_t period) {
     txctx->period = period;
     txctx->offset = txctx->offset_seed % period;
+{%- if tx_timing == 'delta' %}
+    txctx->remaining = txctx->offset + 1;
+{%- endif %}
 }
 {%- endmacro %}
 
@@ -92,8 +100,8 @@ void {{ api_name }}_{{ message.name }}_commit(struct {{ api_struct_prefix }}TxSi
 }
 {%- endmacro %}
 
-{% macro declare_periodic_tx_function(api_name, api_struct_prefix, can_frame_type, return_type, time_type, flag_type, tx_function=false) -%}
-{{ return_type }} {{ api_name }}_periodic_tx(struct {{ api_struct_prefix }}TxSignals *tx_signals, {% if not tx_function %}{{ can_frame_type }} *output_frame, {% endif %}{{ time_type }} now)
+{% macro declare_periodic_tx_function(api_name, api_struct_prefix, can_frame_type, return_type, time_type, flag_type, tx_function=false, time_arg='now') -%}
+{{ return_type }} {{ api_name }}_periodic_tx(struct {{ api_struct_prefix }}TxSignals *tx_signals, {% if not tx_function %}{{ can_frame_type }} *output_frame, {% endif %}{{ time_type }} {{ time_arg }})
 {%- endmacro %}
 
 {% macro tx_callback_call(message, msg_arg, tx_callback_context, msg_as_tx_callback_arg, time_as_tx_callback_arg) -%}
@@ -190,14 +198,122 @@ void {{ api_name }}_{{ message.name }}_commit(struct {{ api_struct_prefix }}TxSi
 }
 {%- endmacro %}
 
-{% macro declare_periodic_tx_init_function(api_name, api_struct_prefix, time_type, can_frame_type='CanFrame', tx_function=false) -%}
-void {{ api_name }}_periodic_tx_init(struct {{ api_struct_prefix }}TxSignals *tx_signals, {{ time_type }} now
+{#
+ # --tx-timing delta: dt is the number of ticks since the previous call. Each
+ # message counts down; when its countdown runs out the message is marked
+ # pending (if enabled; a disabled message's slot is skipped, its countdown
+ # keeps running) and rescheduled to its next slot on the original grid, so a
+ # stall over several periods sends once and keeps the phase.
+ # Without a frame sink one pending frame is returned per call, in message
+ # order; the rest are drained by calling again with dt = 0. With a sink
+ # (--tx-function) every pending message is handed over in one pass, and a
+ # frame the sink rejects stays pending for the next call.
+ #}
+{% macro define_periodic_tx_delta_function(messages, api_name, api_struct_prefix, can_frame_type, return_type, flag_type, tx_callback, send_now, double_buffered=False, tx_callback_context=false, msg_as_tx_callback_arg=false, tx_signal_store=false, tx_function=false) -%}
+{%- set tx_messages = messages | selectattr('direction', 'in', ['tx', 'rt']) | list %}
+{%- set frame_arg = '&frame' if tx_function else 'output_frame' -%}
+{{ declare_periodic_tx_function(api_name, api_struct_prefix, can_frame_type, return_type, 'uint32_t', flag_type, tx_function, 'dt') }} {
+{%- if tx_function %}
+    {{ can_frame_type }} frame;
+    {{ return_type }} queued = 0;
+{%- endif %}
+{%- for message in tx_messages %}
+{%- set ctx = 'tx_signals->' ~ message.name ~ '_context' %}
+    if (dt >= {{ ctx }}.remaining) {
+        {{ ctx }}.pending = {{ ctx }}.enable;
+        {{ ctx }}.remaining = {{ ctx }}.period - (dt - {{ ctx }}.remaining) % {{ ctx }}.period;
+    } else {
+        {{ ctx }}.remaining -= dt;
+    }
+{%- endfor %}
+{%- for message in tx_messages %}
+{%- set ctx = 'tx_signals->' ~ message.name ~ '_context' %}
+
+    if ({% if send_now %}{{ ctx }}.send_now || {% endif %}({{ ctx }}.pending && {{ ctx }}.enable)) {
+{%- if not tx_signal_store %}
+{%- if msg_as_tx_callback_arg %}
+        struct {{ message.struct_name }} {{ message.name }}_tx_storage;
+{%- endif %}
+        void *{{ message.name }}_tx_data = 0;
+{%- endif %}
+{%- if not tx_function %}
+{%- if send_now %}
+        {{ ctx }}.send_now = 0;
+{%- endif %}
+        {{ ctx }}.pending = 0;
+{%- endif %}
+{%- if tx_signal_store %}
+{%- set msg_arg = ('tx_signals->' ~ message.name ~ '_signals_committed') if double_buffered else ('&tx_signals->' ~ message.name ~ '_signals') %}
+        {%- if tx_callback %}
+        if ({{ ctx }}.tx_callback) {
+            (void){{ tx_callback_call(message, msg_arg, tx_callback_context, msg_as_tx_callback_arg, false) }};
+        }
+        {%- endif %}
+        {{ message_encoding_function_call(message, msg_arg, frame_arg) }};
+{%- if tx_function %}
+        if ((*tx_signals->tx_function)(tx_signals->tx_function_context, &frame)) {
+{%- if send_now %}
+            {{ ctx }}.send_now = 0;
+{%- endif %}
+            {{ ctx }}.pending = 0;
+{%- endif %}
+        {%- for signal in message.all_signals %}
+        {%- if signal.multiplex %}
+{%- if double_buffered %}
+        {% if tx_function %}    {% endif %}{{ rotate_multiplex_func_call(message, signal, '&tx_signals->' ~ message.name ~ '_signals_committed->' ~ signal.name) }};
+{%- else %}
+        {% if tx_function %}    {% endif %}{{ rotate_multiplex_func_call(message, signal, '&tx_signals->' ~ message.name ~ '_signals.' ~ signal.name) }};
+{%- endif %}
+        {%- endif %}
+        {%- endfor %}
+{%- if tx_function %}
+            queued++;
+        }
+{%- else %}
+        return 1;
+{%- endif %}
+{%- else %}
+        if ({{ ctx }}.tx_callback) {
+            {{ message.name }}_tx_data = {{ tx_callback_call(message, '&' ~ message.name ~ '_tx_storage', tx_callback_context, msg_as_tx_callback_arg, false) }};
+        }
+        if ({{ message.name }}_tx_data) {
+{%- if tx_function %}
+            {{ message_encoding_function_call(message, '(struct ' ~ message.struct_name ~ ' *)' ~ message.name ~ '_tx_data', frame_arg) }};
+            if ((*tx_signals->tx_function)(tx_signals->tx_function_context, &frame)) {
+{%- if send_now %}
+                {{ ctx }}.send_now = 0;
+{%- endif %}
+                {{ ctx }}.pending = 0;
+                queued++;
+            }
+        } else {
+            // nothing to send for this slot; a send_now request stays set
+            {{ ctx }}.pending = 0;
+        }
+{%- else %}
+            {{ message_encoding_function_call(message, '(struct ' ~ message.struct_name ~ ' *)' ~ message.name ~ '_tx_data', frame_arg) }};
+            return 1;
+        }
+{%- endif %}
+{%- endif %}
+    }
+{%- endfor %}
+{%- if tx_function %}
+    return queued;
+{%- else %}
+    return 0;
+{%- endif %}
+}
+{%- endmacro %}
+
+{% macro declare_periodic_tx_init_function(api_name, api_struct_prefix, time_type, can_frame_type='CanFrame', tx_function=false, tx_timing='absolute') -%}
+void {{ api_name }}_periodic_tx_init(struct {{ api_struct_prefix }}TxSignals *tx_signals{% if tx_timing != 'delta' %}, {{ time_type }} now{% endif %}
 {%- if tx_function %}, uint16_t (*tx_function)(void *, const {{ can_frame_type }} *), void *tx_function_context{% endif %})
 {%- endmacro %}
 
-{% macro define_periodic_tx_init_function(api_name, api_struct_prefix, time_type, messages, default_period, double_buffered=False, tx_signal_store=False, can_frame_type='CanFrame', tx_function=false) -%}
+{% macro define_periodic_tx_init_function(api_name, api_struct_prefix, time_type, messages, default_period, double_buffered=False, tx_signal_store=False, can_frame_type='CanFrame', tx_function=false, tx_timing='absolute') -%}
 {% set tx_messages = messages | selectattr('direction', 'in',  '["tx", "rt"]') -%}
-{{ declare_periodic_tx_init_function(api_name, api_struct_prefix, time_type, can_frame_type, tx_function) }} {
+{{ declare_periodic_tx_init_function(api_name, api_struct_prefix, time_type, can_frame_type, tx_function, tx_timing) }} {
     memset(tx_signals, 0, sizeof(*tx_signals));
 {%- if tx_function %}
     tx_signals->tx_function = tx_function;
@@ -205,7 +321,9 @@ void {{ api_name }}_periodic_tx_init(struct {{ api_struct_prefix }}TxSignals *tx
 {%- endif %}
     {%- for msg in tx_messages %}
     tx_signals->{{ msg.name }}_context.arb_id = {{ msg.arb_id }};
+{%- if tx_timing != 'delta' %}
     tx_signals->{{ msg.name }}_context.last_tx = now;
+{%- endif %}
     tx_signals->{{ msg.name }}_context.offset_seed = {{ msg.offset_seed }}ull;
 {%- if double_buffered and tx_signal_store %}
     tx_signals->{{ msg.name }}_signals = &tx_signals->{{ msg.name }}_signals_storage[0];