Skip to content

feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296)#535

Merged
suda-morris merged 3 commits into
espressif:masterfrom
eternal-echo:feat/isotp
Sep 2, 2025
Merged

feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296)#535
suda-morris merged 3 commits into
espressif:masterfrom
eternal-echo:feat/isotp

Conversation

@eternal-echo
Copy link
Copy Markdown
Contributor

@eternal-echo eternal-echo commented Aug 6, 2025 •
edited
Loading

Checklist

Required Items

  • Component contains License
  • Component contains README.md
  • Component contains idf_component.yml with url field
  • Component added to upload job (NEEDS MANUAL ADDITION)
  • Component added to build job (NEEDS MANUAL ADDITION)
  • CI passing

Optional Items

  • Component contains unit tests (pytest)
  • QEMU testing support
  • Multiple examples

Change Description

This PR introduces a complete ISO-TP (ISO 15765-2) protocol implementation for ESP-IDF, enabling standard-compliant communication over the CAN bus with payloads up to 4095 bytes.

This component integrates the lightweight isotp-c library as a submodule and provides a straightforward ESP-IDF driver interface, handling the complexities of the ISO-TP state machine.

  • Examples:
    • Added echo example with pytest for demonstrating basic send/receive.
    • In-progress: utils (CLI tools like isotpsend/isotprecv) and ota (firmware update over CAN).
  • esp_isotp:
    • Future work: Add support for CAN FD.

Features

  • Full ISO-TP protocol support (Single-Frame, Multi-Frame, Flow Control).
  • Seamless integration with the ESP-IDF esp_driver_twai.
  • Compatible with standard Linux can-utils for easy testing and integration.
  • Automated patch management for the upstream isotp-c library via build-time patches.
  • QEMU testing support for robust CI/CD (currently works with a patched QEMU version).

Structure

isotp/
├── esp_isotp/          # ESP-IDF integration layer
├── isotp-c/            # Upstream library (git submodule)
├── patch/              # Build-time patches for isotp-c
└── examples/
    ├── echo/           ✓ Message echo service
    ├── utils/          ⏳ CLI tools (isotpsend/recv)
    └── ota/            ⏳ Firmware upgrade system

Protocal

Single Frame Transmission Sequence

image

Multi-frame Transmission Sequence

image

Dependencies

  • ESP-IDF v5.1 or later (esp_driver_twai support)
  • isotp-c library (included as a git submodule)

Testing Status

  • Unit tests pass using the pytest framework.
  • QEMU integration testing is operational.
  • Verified compatibility with Linux can-utils (isotpsend / isotprecv).
  • Multi-frame transmission and reception (up to 4095 bytes) successfully tested.
  • Flow Control (Wait, Continue, Overflow) handling verified.

Known Limitations

  • The underlying isotp-c library is designed for a single transport link instance. To manage multiple, distinct ISO-TP communications, one would need to instantiate multiple esp_isotp_handle_t handles, each tied to a unique set of CAN IDs.

Related

  • Closes IEC-296

@github-actions github-actions Bot changed the title feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296) feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296) (IEC-346) Aug 6, 2025
@anastasia-be anastasia-be added the Component: new request Set this label for issues which request a new component to be added label Aug 6, 2025
@eternal-echo eternal-echo changed the title feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296) (IEC-346) feat(isotp): Add ISO-TP (ISO 15765-2) Protocol Component with Examples and Testing Infrastructure (IEC-296) Aug 6, 2025
@eternal-echo eternal-echo force-pushed the feat/isotp branch 2 times, most recently from 7c48f74 to 9a7585f Compare August 8, 2025 08:17
@eternal-echo eternal-echo marked this pull request as ready for review August 8, 2025 08:19

This comment was marked as outdated.

Sign in to view

@suda-morris
Copy link
Copy Markdown
Collaborator

suda-morris commented Aug 11, 2025

@Dazza0 Please take a look if you're interested in. 😄

@suda-morris
Copy link
Copy Markdown
Collaborator

suda-morris commented Aug 11, 2025

The upstream code is not actively maintained and may even contain security issues: lishen2/isotp-c#36

I suggest we don't use git submodule but just directly copy the upstream source code and form our component. The proposed file structure could be:

esp_isotp/
├── include/      # esp_isotp.h
├── src/             # esp_isotp wrapper
├── isotp-c/      # Upstream library (source code with our patch)
├── test_apps/
└── examples/

@eternal-echo

suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread .github/ISSUE_TEMPLATE/bug-report.yml Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/CMakeLists.txt Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.c Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.c Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 11, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 12, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 12, 2025
View reviewed changes
Comment thread isotp/esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 12, 2025
View reviewed changes
Comment thread isotp/examples/echo/main/isotp_echo_main.c Outdated
suda-morris
suda-morris reviewed Aug 12, 2025
View reviewed changes
Comment thread isotp/examples/echo/main/isotp_echo_main.c Outdated
@eternal-echo eternal-echo force-pushed the feat/isotp branch 2 times, most recently from 91019c3 to b9d7f21 Compare August 12, 2025 15:28
This was referenced Aug 24, 2025
Merged
Merged
@eternal-echo eternal-echo force-pushed the feat/isotp branch 2 times, most recently from ac5dec3 to 08ddeaf Compare August 28, 2025 10:49
github-advanced-security[bot]
github-advanced-security AI found potential problems Aug 28, 2025
View reviewed changes
Comment thread esp_isotp/isotp-c/isotp.c
static int isotp_send_flow_control(const IsoTpLink *link, uint8_t flow_status, uint8_t block_size, uint32_t st_min_us)
{
IsoTpCanMessage message;
(void)memset(&message, 0, sizeof(message));

Check warning

Code scanning / clang-tidy

Call to function 'memset' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memset_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memset' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memset_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
Comment thread esp_isotp/isotp-c/isotp.c
/* setup message */
message.as.single_frame.type = ISOTP_PCI_TYPE_SINGLE;
message.as.single_frame.SF_DL = (uint8_t)link->send_size;
(void)memcpy(message.as.single_frame.data, link->send_buffer, link->send_size);

Check warning

Code scanning / clang-tidy

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
Comment thread esp_isotp/isotp-c/isotp.c
if (data_length > sizeof(message.as.consecutive_frame.data)) {
data_length = sizeof(message.as.consecutive_frame.data);
}
(void)memcpy(message.as.consecutive_frame.data, link->send_buffer + link->send_offset, data_length);

Check warning

Code scanning / clang-tidy

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
Comment thread esp_isotp/isotp-c/isotp.c
}

/* copying data */
(void)memcpy(link->receive_buffer, message->as.single_frame.data, message->as.single_frame.SF_DL);

Check warning

Code scanning / clang-tidy

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
Comment thread esp_isotp/isotp-c/isotp.c
}

/* copying data */
(void)memcpy(link->receive_buffer + link->receive_offset, message->as.consecutive_frame.data, remaining_bytes);

Check warning

Code scanning / clang-tidy

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
Comment thread esp_isotp/isotp-c/isotp.c
/* copy into local buffer */
link->send_size = size;
link->send_offset = 0;
(void)memcpy(link->send_buffer, payload, size);

Check warning

Code scanning / clang-tidy

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling] Warning

Call to function 'memcpy' is insecure as it does not provide security checks introduced in the C11 standard. Replace with analogous functions that support length arguments or provides boundary checks such as 'memcpy_s' in case of C11 [clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling]
@eternal-echo eternal-echo force-pushed the feat/isotp branch 2 times, most recently from 4e5c8e6 to 712f781 Compare August 29, 2025 03:04
@suda-morris suda-morris requested a review from Copilot August 29, 2025 08:50
Copilot AI reviewed Aug 29, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR introduces a complete ISO-TP (ISO 15765-2) protocol implementation for ESP-IDF, enabling transmission of data payloads up to 4095 bytes over CAN/TWAI networks with automatic segmentation and reassembly.

  • Integrates the upstream isotp-c library as a submodule with ESP-IDF-specific wrapper and configuration
  • Provides a high-level ESP-IDF API with non-blocking operations and ISR-based frame processing
  • Includes comprehensive testing infrastructure and an echo example for demonstration

Reviewed Changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
esp_isotp/isotp-c/* Complete isotp-c library files added as submodule content
esp_isotp/esp_isotp.h ESP-IDF specific header providing high-level ISO-TP API
esp_isotp/esp_isotp.c ESP-IDF wrapper implementation with TWAI integration
esp_isotp/CMakeLists.txt Build configuration for the component
esp_isotp/Kconfig Configuration options for ISO-TP protocol parameters
.idf_build_apps.toml Added esp_isotp to build test configuration
.github/workflows/upload_component.yml Added esp_isotp to upload workflow

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

Comment thread esp_isotp/isotp-c/isotp_defines.h
Comment thread esp_isotp/isotp-c/isotp_defines.h
Comment thread esp_isotp/isotp-c/isotp.c
Comment thread esp_isotp/isotp-c/isotp.c
Comment thread esp_isotp/isotp-c/isotp.c
Comment thread esp_isotp/esp_isotp.c
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/CMakeLists.txt Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/CMakeLists.txt Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/README.md Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/README.md Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/README.md Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/esp_isotp.h Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/esp_isotp.c Outdated
suda-morris
suda-morris reviewed Aug 29, 2025
View reviewed changes
Comment thread esp_isotp/esp_isotp.c
@suda-morris suda-morris merged commit 82441ca into espressif:master Sep 2, 2025
87 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@suda-morris suda-morris suda-morris approved these changes

+1 more reviewer

@Dazza0 Dazza0 Dazza0 left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@eternal-echo eternal-echo

Labels

Component: new request Set this label for issues which request a new component to be added Resolution: Done Status: Done

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@eternal-echo @suda-morris @Dazza0 @github-advanced-security @espressif-bot @anastasia-be