doc: add simple L2CAP server example #96896

ritesh006 · 2025-10-02T02:49:01Z

Adds a "Creating a simple L2CAP server" section to the L2CAP API docs with
a minimal skeleton example and step-by-step instructions.

Also fixes minor typos (enabled/latter).

Fixes: #96494

bt_l2cap_chan_ops (fixes zephyrproject-rtos#96494) Signed-off-by: Ritesh Kudkelwar <[email protected]>

ritesh006 · 2025-10-02T02:49:18Z

Ready for Review

doc/connectivity/bluetooth/api/l2cap.rst

cvinayak

Please add a sample under samples/bluetooth instead which is CI tested and will not go stale. You can refer to the sample here. And hopefully be able to have directly reference to the code in the sample in this document.

HaavardRei · 2025-10-02T06:46:16Z

Please add a sample under samples/bluetooth instead which is CI tested and will not go stale. You can refer to the sample here. And hopefully be able to have directly reference to the code in the sample in this document.

There is already various bsim test covering this functionality, for instance:

zephyr/tests/bsim/bluetooth/host/l2cap/send_on_connect/src/main_l2cap_send_on_connect.c

Lines 128 to 141 in 0ab4091

    
           static int accept(struct bt_conn *conn, struct bt_l2cap_server *server, 
        
           		  struct bt_l2cap_chan **l2cap_chan) 
        
           { 
        
           	dyn_chan.chan.ops = &l2cap_ops; 
        
           	*l2cap_chan = &dyn_chan.chan; 
        
           	return 0; 
        
           } 
        
           static struct bt_l2cap_server server = { 
        
           	.accept = accept, 
        
           	.sec_level = BT_SECURITY_L1, 
        
           	.psm = PSM, 
        
           };

I don't think adding a sample for the sole purpose of testing this in CI is necessary, though I agree that the functionality should be demonstrated in a sample.

Thalley · 2025-10-02T07:08:31Z

I don't think adding a sample for the sole purpose of testing this in CI is necessary, though I agree that the functionality should be demonstrated in a sample.

I think what Vinayak meant was that a sample is better than just additional documentation, and that we should add a BSIM test of that sample to help ensure that it always works (we've had some samples in the past that stopped working due to changes in the stack, and where only build issue have been fixed).

PavelVPV · 2025-10-02T11:06:02Z

I think the intention of this PR is to show in documentation how to set up a new L2CAP server. The user complains about lack of documentation in this area.

Sample code which is also used for testing isn't always easy to grasp. For example, peripheral_gatt_write and central_gatt_write pair. Why main function looks like this and why some functions that are used by peripheral are located in central part is not clear from a user perspective. For me as a contributor, for example, the intention is clear, but it is not true for people who just came or who aren't involved much into the project.

In this case, short section in documentation is really helpful because it is ready for simple copy-pasting.

What could be a compromise here (keeping doc part and implementing a sample with covering it in CI) is using literalinclude doxygen directive, for example:

zephyr/doc/connectivity/usb/device_next/usb_device.rst

Lines 69 to 73 in 2d72d86

    
           .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c 
        
              :language: c 
        
              :dedent: 
        
              :start-after: doc device instantiation start 
        
              :end-before: doc device instantiation end

zephyr/samples/subsys/usb/common/sample_usbd_init.c

Lines 24 to 33 in 2d72d86

    
           /* doc device instantiation start */ 
        
           /* 
        
            * Instantiate a context named sample_usbd using the default USB device 
        
            * controller, the Zephyr project vendor ID, and the sample product ID. 
        
            * Zephyr project vendor ID must not be used outside of Zephyr samples. 
        
            */ 
        
           USBD_DEVICE_DEFINE(sample_usbd, 
        
           		   DEVICE_DT_GET(DT_NODELABEL(zephyr_udc0)), 
        
           		   ZEPHYR_PROJECT_USB_VID, CONFIG_SAMPLE_USBD_PID); 
        
           /* doc device instantiation end */

cvinayak · 2025-10-02T12:17:02Z

What could be a compromise here (keeping doc part and implementing a sample with covering it in CI) is using literalinclude doxygen directive, for example:

Yes, this is what I want, have the documentation but reference to actual code blocks from samples that are being built in CI (not necessarily CI tested, but that will be great too) and which do not go stale over time. A reader can copy these code blocks as instructed by the documentation.

ritesh006 · 2025-10-03T14:07:37Z

Thank you all! I added a real example at samples/bluetooth/l2cap_server_simple and updated the docs to show the code with literalinclude. The sample shows how to use fixed space for each connection (it uses CONFIG_BT_MAX_CONN and bt_conn_index(conn)). The docs example is now copied from this file.

I am new here and still learning, so please let me know if I missed something or can do better. I’m trying hard to help and get things right.

ritesh006 · 2025-10-05T12:53:41Z

@cvinayak Hi is this changes met with your expectation please let me know.

PavelVPV · 2025-10-07T13:11:27Z

@ritesh006 ,

I think what needs to be done to complete this task is:

another sample that will connect the channels
demonstrate data transmission
- I think it is Ok for sample if it sends some random printable data over channels with some delay, but have no strong opinion what and how exactly samples should send data.
a short readme for both the samples (see any other sample)

I can recommend you to look at l2cap ecred generic babblesim test.
This can look a bit complicated, but can on the other hand help to get the idea what API needs to be used for communication without digging into babblesim API.

The code in both samples should not be overcomplicated (and your current sample in the PR is actually concise). You can look at, for example, peripheral and central samples to see how much code you need for both sample.

Regarding documentation, I suggest to use literalinclude instead of this text so that documentation is automatically corrected if something (e.g. API) changes.

ritesh006 · 2025-10-11T05:45:03Z

@PavelVPV Ready for Review

kartben · 2025-10-11T06:43:38Z

@PavelVPV Ready for Review

There's many CI issues that you need to fix though

kartben

Missing license and copyright headers also need to be added

kartben · 2025-10-11T06:45:15Z

samples/bluetooth/l2cap_coc_acceptor/README.rst

This needs to follow the template for samples
https://github.com/zephyrproject-rtos/zephyr/blob/main/doc/templates/sample.tmpl

Not addressed - please use the template

kartben · 2025-10-11T06:46:32Z

samples/bluetooth/l2cap_server_simple/src/main.c

This is missing a readme altogether

ritesh006 · 2025-10-11T14:46:07Z

Ready for review @kartben

kartben · 2025-10-11T15:27:43Z

Ready for review @kartben

Probably not :) have you seen my message earlier regarding CI failures? There's even more now, it looks like, so please address them

kartben · 2025-10-11T15:30:13Z

Also don't resolve comments yourself especially when things.havent been addressed

https://docs.zephyrproject.org/latest/contribute/contributor_expectations.html#workflow-suggestions-that-help-reviewers

kartben · 2025-10-11T15:32:12Z

Missing license and copyright headers also need to be added

@ritesh006 this too needs to be addressed please

ritesh006 · 2025-10-12T05:49:01Z

Also don't resolve comments yourself especially when things.havent been addressed

https://docs.zephyrproject.org/latest/contribute/contributor_expectations.html#workflow-suggestions-that-help-reviewers

sorry this won't happen again

kartben · 2025-10-12T18:31:40Z

samples/bluetooth/l2cap_client_simple/src/main.c

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2022-2024 Nordic Semiconductor ASA


@ritesh006 are you a Nordic employee? If this is your code it should be your copyright, or a generic clause
https://docs.zephyrproject.org/latest/contribute/guidelines.html#copyright-and-license-notices

This hasn't been applied correctly. Please take some time to read the links shared by reviewers as we are otherwise spending a lot of time on things that should be rather trivial. Thanks!

samples/bluetooth/l2cap_client_simple/src/main.c

samples/bluetooth/l2cap_client_simple/sample.yaml

samples/bluetooth/l2cap_server_simple/sample.yaml

samples/bluetooth/l2cap_server_simple/src/main.c

doc/connectivity/bluetooth/api/l2cap.rst

samples/bluetooth/l2cap_client_simple/prj.conf

samples/bluetooth/l2cap_server_simple/sample.yaml

…ephyrproject-rtos#96494) Signed-off-by: Ritesh Kudkelwar <[email protected]>

kartben · 2025-10-14T15:07:01Z

samples/bluetooth/l2cap_coc_acceptor/src/main.c

@@ -0,0 +1,83 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright The Zephyr Project Contributors


https://docs.zephyrproject.org/latest/contribute/guidelines.html#copyright-and-license-notices
Please fix everywhere

Suggested change

* Copyright The Zephyr Project Contributors

* SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors

kartben · 2025-10-14T15:08:42Z

samples/bluetooth/l2cap_coc_acceptor/README.rst

kartben · 2025-10-14T15:10:22Z

samples/bluetooth/l2cap_client_simple/src/main.c

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2022-2024 Nordic Semiconductor ASA


This hasn't been applied correctly. Please take some time to read the links shared by reviewers as we are otherwise spending a lot of time on things that should be rather trivial. Thanks!

sonarqubecloud · 2025-10-14T15:23:00Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

PavelVPV

I haven't reviewed READMEs yet. Will do this after @kartben comments are resolved there.

PavelVPV · 2025-10-14T19:50:37Z

samples/bluetooth/l2cap_coc_initiator/CMakeLists.txt

+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(l2cap_client_simple)


Needs to be updated

PavelVPV · 2025-10-14T19:52:23Z

samples/bluetooth/l2cap_coc_acceptor/prj.conf

+CONFIG_BT_SMP=y
+CONFIG_BT_L2CAP_DYNAMIC_CHANNEL=y
+# Optional, adjust for sample:
+CONFIG_BT_MAX_CONN=2


Same as here: #96896 (comment)

PavelVPV · 2025-10-14T19:52:37Z

samples/bluetooth/l2cap_coc_acceptor/CMakeLists.txt

+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(l2cap_server_simple)


Needs to be updated

PavelVPV · 2025-10-14T19:55:07Z

doc/connectivity/bluetooth/api/l2cap.rst

+.. literalinclude:: ../../../../samples/bluetooth/l2cap_coc_acceptor/src/main.c
+   :language: c
+   :linenos:
+


This should point to exact lines not to the entire file. What should be demonstrated (based on your previous change) are line 17-48 from l2cap_coc_acceptor/src/main.c.

I also suggest to move the literalinclude up to line 34 (right after paragraph that starts at line 28) and remove the existing lines 34-35 (Creating a simple L2CAP server...).

Then paragraph at line 37 that refers to samples passes perfectly to the entire section. But! I suggest to keep only reference to acceptor (server) role there and move the initiator (client) reference to the end of Client Channels section that you have added (after line 97 at the current change).

PavelVPV · 2025-10-14T19:56:12Z

doc/connectivity/bluetooth/api/l2cap.rst

+.. note::
+   The sample demonstrates allocating one channel per connection using
+   ``CONFIG_BT_MAX_CONN`` and ``bt_conn_index(conn)``. See the initiator sample
+   for how to open a channel and send data to the acceptor.


I think this note doesn't belong to l2cap.rst but to README of the particular sample.

PavelVPV · 2025-10-14T20:01:15Z

doc/connectivity/bluetooth/api/l2cap.rst

+   ``CONFIG_BT_MAX_CONN`` and ``bt_conn_index(conn)``. See the initiator sample
+   for how to open a channel and send data to the acceptor.
+
+Fixed Channels


This is a good change, thanks!

doc: add simple L2CAP server example and explain

3d5b8b0

bt_l2cap_chan_ops (fixes zephyrproject-rtos#96494) Signed-off-by: Ritesh Kudkelwar <[email protected]>

zephyrbot added area: Bluetooth Host Bluetooth Host (excluding BR/EDR) area: Bluetooth labels Oct 2, 2025

zephyrbot requested review from HaavardRei, PavelVPV, Thalley, alwa-nordic, cvinayak, hermabe, jhedberg, rugeGerritsen and sjanc October 2, 2025 02:50

zephyrbot assigned jhedberg and alwa-nordic Oct 2, 2025

HaavardRei requested changes Oct 2, 2025

View reviewed changes

doc/connectivity/bluetooth/api/l2cap.rst Outdated Show resolved Hide resolved

doc/connectivity/bluetooth/api/l2cap.rst Outdated Show resolved Hide resolved

doc/connectivity/bluetooth/api/l2cap.rst Outdated Show resolved Hide resolved

cvinayak requested changes Oct 2, 2025

View reviewed changes

zephyrbot added the area: Samples Samples label Oct 3, 2025

zephyrbot requested review from JarmouniA, kartben and nashif October 3, 2025 14:06

ritesh006 force-pushed the docs/l2cap-server-example-96494 branch from 02920b0 to afcd52a Compare October 11, 2025 05:43

kartben requested changes Oct 11, 2025

View reviewed changes

ritesh006 force-pushed the docs/l2cap-server-example-96494 branch from afcd52a to 0e6fb96 Compare October 11, 2025 14:45

ritesh006 force-pushed the docs/l2cap-server-example-96494 branch from 0e6fb96 to 8975e67 Compare October 12, 2025 16:15

kartben reviewed Oct 12, 2025

View reviewed changes

Thalley removed their request for review October 12, 2025 18:49

PavelVPV requested changes Oct 13, 2025

View reviewed changes

samples: add l2cap_server_simple sample and reference in docs (fixes z…

446aaab

…ephyrproject-rtos#96494) Signed-off-by: Ritesh Kudkelwar <[email protected]>

ritesh006 force-pushed the docs/l2cap-server-example-96494 branch from 8975e67 to 446aaab Compare October 14, 2025 14:55

kartben requested changes Oct 14, 2025

View reviewed changes

PavelVPV reviewed Oct 14, 2025

View reviewed changes

		@@ -0,0 +1,180 @@
		/*
		* Copyright (c) 2022-2024 Nordic Semiconductor ASA

	* Copyright The Zephyr Project Contributors
	* SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors

doc: add simple L2CAP server example #96896

Are you sure you want to change the base?

doc: add simple L2CAP server example #96896

Uh oh!

Conversation

ritesh006 commented Oct 2, 2025

Uh oh!

ritesh006 commented Oct 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cvinayak left a comment

Choose a reason for hiding this comment

Uh oh!

HaavardRei commented Oct 2, 2025

Uh oh!

Thalley commented Oct 2, 2025

Uh oh!

PavelVPV commented Oct 2, 2025

Uh oh!

cvinayak commented Oct 2, 2025

Uh oh!

ritesh006 commented Oct 3, 2025

Uh oh!

ritesh006 commented Oct 5, 2025

Uh oh!

PavelVPV commented Oct 7, 2025

Uh oh!

ritesh006 commented Oct 11, 2025

Uh oh!

kartben commented Oct 11, 2025

Uh oh!

kartben left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ritesh006 commented Oct 11, 2025

Uh oh!

kartben commented Oct 11, 2025

Uh oh!

kartben commented Oct 11, 2025

Uh oh!

kartben commented Oct 11, 2025

Uh oh!

ritesh006 commented Oct 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Oct 14, 2025

Quality Gate passed

Uh oh!

PavelVPV left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

PavelVPV left a comment •

edited

Loading