feat(isotp): enhance ISO-TP transport with callback support and thread safety features

Author: eternal-echo

esp_isotp/README.md

@@ -54,13 +54,12 @@ void app_main(void) {
     twai_node_handle_t twai_node;
     ESP_ERROR_CHECK(twai_new_node_onchip(&twai_cfg, &twai_node));
 
-    // 2) Create ISO-TP (11-bit IDs)
+    // 2) Create ISO-TP (11-bit IDs, auto-detected)
     esp_isotp_config_t config = {
-        .tx_id = 0x7E0,                // request ID
-        .rx_id = 0x7E8,                // response ID
+        .tx_id = 0x7E0,                // request ID (11-bit, auto-detected)
+        .rx_id = 0x7E8,                // response ID (11-bit, auto-detected)
         .tx_buffer_size = 4096,
         .rx_buffer_size = 4096,
-        .use_extended_id = false,   // Use 11-bit standard IDs
     };
     esp_isotp_handle_t isotp_handle;
     ESP_ERROR_CHECK(esp_isotp_new_transport(twai_node, &config, &isotp_handle));
@@ -87,16 +86,15 @@ void app_main(void) {
 
 ## Extended (29-bit) IDs
 
-- Set `use_extended_id = true`; use IDs ≤ 0x1FFFFFFF.
-- `tx_id` and `rx_id` must differ and match peer IDE.
+- ID format is auto-detected: IDs > 0x7FF use 29-bit extended format, others use 11-bit standard format.
+- `tx_id` and `rx_id` must differ and match peer's expected format.
 
 ```c
 esp_isotp_config_t cfg = {
-    .tx_id = 0x18DAF110,
-    .rx_id = 0x18DA10F1,
+    .tx_id = 0x18DAF110,    // 29-bit ID (auto-detected as extended)
+    .rx_id = 0x18DA10F1,    // 29-bit ID (auto-detected as extended)
     .tx_buffer_size = 4096,
     .rx_buffer_size = 4096,
-    .use_extended_id = true, // Set to true for 29-bit IDs
 };
 ```
 

esp_isotp/inc/esp_isotp.h

@@ -28,6 +28,38 @@
 extern "C" {
 #endif
 
+/**
+ * @brief ISO-TP receive callback function type
+ *
+ * Called when a complete message has been received successfully.
+ *
+ * @warning This callback executes in the same context as isotp_on_can_message(),
+ *          which is typically ISR context. Keep callback execution time minimal
+ *          and avoid blocking operations.
+ * @note The data pointer is only valid during the callback execution.
+ *       Copy data immediately if needed beyond the callback scope.
+ *
+ * @param[in] data Pointer to received data (valid only during callback)
+ * @param[in] size Size of received data in bytes
+ * @param[in] user_arg User argument provided during configuration
+ */
+typedef void (*esp_isotp_rx_callback_t)(const uint8_t *data, uint32_t size, void *user_arg);
+
+/**
+ * @brief ISO-TP transmit callback function type
+ *
+ * Called when a complete message has been transmitted successfully.
+ *
+ * @note Execution context depends on message type:
+ *       - Single-frame: Called immediately from isotp_send() in caller's context
+ *       - Multi-frame: Called from isotp_poll() in task context
+ * @note Keep callback execution time minimal to avoid affecting system performance.
+ *
+ * @param[in] tx_size Size of transmitted data in bytes
+ * @param[in] user_arg User argument provided during configuration
+ */
+typedef void (*esp_isotp_tx_callback_t)(uint32_t tx_size, void *user_arg);
+
 /**
  * @brief ISO-TP link handle
  */
@@ -37,11 +69,15 @@ typedef struct esp_isotp_link_t *esp_isotp_handle_t;
  * @brief Configuration structure for creating a new ISO-TP link
  */
 typedef struct {
-    uint32_t tx_id;                  /*!< TWAI ID for transmitting ISO-TP frames (11-bit or 29-bit) */
-    uint32_t rx_id;                  /*!< TWAI ID for receiving ISO-TP frames (11-bit or 29-bit) */
+    uint32_t tx_id;                  /*!< TWAI ID for transmitting ISO-TP frames (11-bit or 29-bit, auto-detected from value) */
+    uint32_t rx_id;                  /*!< TWAI ID for receiving ISO-TP frames (11-bit or 29-bit, auto-detected from value) */
     uint32_t tx_buffer_size;         /*!< Size of the transmit buffer (max message size to send) */
     uint32_t rx_buffer_size;         /*!< Size of the receive buffer (max message size to receive) */
-    bool use_extended_id;            /*!< true: use 29-bit extended ID, false: use 11-bit standard ID */
+    uint32_t tx_frame_pool_size;     /*!< Size of TX frame pool (0 for default: 8) */
+
+    esp_isotp_rx_callback_t rx_callback; /*!< Receive completion callback (NULL for polling mode) */
+    esp_isotp_tx_callback_t tx_callback; /*!< Transmit completion callback (NULL to disable) */
+    void *callback_arg;               /*!< User argument passed to callbacks */
 } esp_isotp_config_t;
 
 /**
@@ -63,11 +99,16 @@ typedef struct {
 esp_err_t esp_isotp_new_transport(twai_node_handle_t twai_node, const esp_isotp_config_t *config, esp_isotp_handle_t *out_handle);
 
 /**
- * @brief Send data over an ISO-TP link (non-blocking)
+ * @brief Send data over an ISO-TP link (non-blocking, ISR-safe)
  *
  * Immediately sends first/single frame and returns. For multi-frame messages,
  * remaining frames are sent during subsequent esp_isotp_poll() calls.
  *
+ * @note This function is ISR-safe and can be called from interrupt context.
+ * @note TX completion callback timing:
+ *       - Single-frame: Called immediately from isotp_send()
+ *       - Multi-frame: Called from isotp_poll() when last frame is sent
+ *
  * @param handle ISO-TP handle
  * @param data Data to send
  * @param size Data length in bytes
@@ -83,12 +124,17 @@ esp_err_t esp_isotp_new_transport(twai_node_handle_t twai_node, const esp_isotp_
 esp_err_t esp_isotp_send(esp_isotp_handle_t handle, const uint8_t *data, uint32_t size);
 
 /**
- * @brief Send data over an ISO-TP link with specified TWAI ID (non-blocking)
+ * @brief Send data over an ISO-TP link with specified TWAI ID (non-blocking, ISR-safe)
  *
  * Similar to esp_isotp_send(), but allows specifying a different TWAI ID for transmission.
  * This function is primarily used for functional addressing where multiple nodes
  * may respond to the same request.
  *
+ * @note This function is ISR-safe and can be called from interrupt context.
+ * @note TX completion callback timing:
+ *       - Single-frame: Called immediately from isotp_send_with_id()
+ *       - Multi-frame: Called from isotp_poll() when last frame is sent
+ *
  * @param handle ISO-TP handle
  * @param id TWAI identifier to use for transmission (overrides configured tx_id)
  * @param data Data to send
@@ -99,19 +145,24 @@ esp_err_t esp_isotp_send(esp_isotp_handle_t handle, const uint8_t *data, uint32_
  *     - ESP_ERR_NO_MEM: Data too large for buffer or no space available
  *     - ESP_ERR_INVALID_SIZE: Invalid data size
  *     - ESP_ERR_TIMEOUT: Send operation timed out
- *     - ESP_ERR_INVALID_ARG: Invalid parameters
+ *     - ESP_ERR_INVALID_ARG: Invalid parameters or ID exceeds maximum value
  *     - ESP_FAIL: Other send errors
  */
 esp_err_t esp_isotp_send_with_id(esp_isotp_handle_t handle, uint32_t id, const uint8_t *data, uint32_t size);
 
 /**
- * @brief Extract a complete received message (non-blocking)
+ * @brief Extract a complete received message (non-blocking, task context only)
  *
  * This function only extracts data that has already been assembled by esp_isotp_poll().
  * It does NOT process incoming TWAI frames - that happens in esp_isotp_poll().
  *
  * Process: TWAI frames → esp_isotp_poll() assembles → esp_isotp_receive() extracts
  *
+ * @warning This function is NOT ISR-safe and must only be called from task context.
+ * @note When using callback mode (rx_callback != NULL), received messages are
+ *       automatically delivered via callback. This function should only be used
+ *       in polling mode (rx_callback == NULL).
+ *
  * @param handle ISO-TP handle
  * @param data Buffer to store received data
  * @param size Buffer size in bytes
@@ -125,10 +176,10 @@ esp_err_t esp_isotp_send_with_id(esp_isotp_handle_t handle, uint32_t id, const u
  *     - ESP_ERR_INVALID_ARG: Invalid parameters
  *     - ESP_FAIL: Other receive errors
  */
-esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, uint32_t size, uint32_t *received_size);
+esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, const uint32_t size, uint32_t *received_size);
 
 /**
- * @brief Poll the ISO-TP link to process messages (CRITICAL - call regularly!)
+ * @brief Poll the ISO-TP link to process messages (CRITICAL - call regularly, task context only)
  *
  * This function drives the ISO-TP state machine. Call every 1-10ms for proper operation.
  *
@@ -137,9 +188,13 @@ esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, uint32_t s
  * - Processes incoming TWAI frames and assembles complete messages
  * - Handles flow control and timeouts
  * - Updates internal state machine
+ * - Triggers TX completion callbacks for multi-frame messages
  *
  * Without regular polling: multi-frame sends will stall and receives won't complete.
  *
+ * @warning This function is NOT ISR-safe and must only be called from task context.
+ * @note TX completion callbacks for multi-frame messages are triggered from this function.
+ *
  * @param handle ISO-TP handle
  * @return
  *     - ESP_OK: Processing successful