ports: add link to documentation in btstack_config.h

port/apollo2-em9304/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for EM9304 DVK
+// btstack_config.h for Apollo 2 + EM9304 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/arduino/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for Arduino port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/esp32/components/btstack/include/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for esp32 port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/libusb-intel/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for libusb port
+// btstack_config.h for libusb-intel port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/libusb/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for libusb port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/msp432p401lp-cc256x/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for MSP432P401R + TI CC256B port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef __BTSTACK_CONFIG
 #define __BTSTACK_CONFIG

port/mtk/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for Android mtk port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/nrf5-cinnamon/port/btstack_config.h

@@ -1,5 +1,8 @@
 //
-// btstack_config.h for nRF5x LL
+// btstack_config.h for nrf5-cinnamon port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 //
 
 #ifndef BTSTACK_CONFIG_H

port/nrf5-zephyr/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for mRF5-Zephyr port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/posix-h4-atwilc3000/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for POSIX H4 + ATWILC3000 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/posix-h4-da14581/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for POSIX H4 + DA14581 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/posix-h4-da14585/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for POSIX H4 + DA14585 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/posix-h4-zephyr/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for POSIX H4 + Zephyr HCI Controller port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/posix-h4/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for generic POSIX H4 port
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/posix-h5/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for POSIX H5 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/qt-h4/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for libusb port
+// btstack_config.h for Qt H4 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/qt-usb/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for libusb port
+// btstack_config.h for Qt USB port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/raspi/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for Raspberry Pi port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/renesas-tb-s1ja-cc256x/template/btstack_example/src/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for STM32F103RB Nucleo + TI CC256B port
+// btstack_config.h for Renesas TB-S1JA + TI CC256x port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/samv71-xplained-atwilc3000/btstack_config.h

@@ -1,6 +1,8 @@
 //
 // btstack_config.h for SAMV71 + ATWILC3000
 //
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+//
 
 #ifndef BTSTACK_CONFIG_H
 #define BTSTACK_CONFIG_H

port/stm32-f4discovery-cc256x/port/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for STM32F103RB Nucleo + TI CC256B port
+// btstack_config.h for STM32 F4 Discovery + TI CC256x port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/stm32-f4discovery-usb/port/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for STM32F103RB Nucleo + TI CC256B port
+// btstack_config.h for STM32 F4 Discovery + USB Bluetooth Dongle port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/stm32-l073rz-nucleo-em9304/port/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for EM9304 DVK
+// btstack_config.h for STM32 L073RZ Nucleo + EM9304 Development Kit port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/wiced-h4/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for WICED port
+// btstack_config.h for WICED H4 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/windows-h4-da14585/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for generic POSIX H4 port
+// btstack_config.h for Windows H4 + DA14585 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/windows-h4-zephyr/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for libusb port
+// btstack_config.h for Windows H4 + Zephyr HCI Controller port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/windows-h4/btstack_config.h

@@ -1,5 +1,7 @@
 //
-// btstack_config.h for libusb port
+// btstack_config.h for Windows H4 port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
 //
 
 #ifndef BTSTACK_CONFIG_H

port/windows-winusb-intel/btstack_config.h

@@ -1,56 +1,58 @@
-//
+//
-// btstack_config.h for libusb port
+// btstack_config.h for Windows-winusb + Intel USB Controller port
-//
+//
-
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
-#ifndef BTSTACK_CONFIG_H
+//
-#define BTSTACK_CONFIG_H
+
-
+#ifndef BTSTACK_CONFIG_H
-// Port related features
+#define BTSTACK_CONFIG_H
-#define HAVE_ASSERT
+
-#define HAVE_BTSTACK_STDIN
+// Port related features
-#define HAVE_MALLOC
+#define HAVE_ASSERT
-#define HAVE_POSIX_FILE_IO
+#define HAVE_BTSTACK_STDIN
-#define HAVE_POSIX_TIME
+#define HAVE_MALLOC
-
+#define HAVE_POSIX_FILE_IO
-// BTstack features that can be enabled
+#define HAVE_POSIX_TIME
-#define ENABLE_BLE
+
-#define ENABLE_CLASSIC
+// BTstack features that can be enabled
-#define ENABLE_HFP_WIDE_BAND_SPEECH
+#define ENABLE_BLE
-#define ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
+#define ENABLE_CLASSIC
-#define ENABLE_LE_CENTRAL
+#define ENABLE_HFP_WIDE_BAND_SPEECH
-#define ENABLE_L2CAP_LE_CREDIT_BASED_FLOW_CONTROL_MODE
+#define ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
-#define ENABLE_LE_DATA_LENGTH_EXTENSION
+#define ENABLE_LE_CENTRAL
-#define ENABLE_LE_PERIPHERAL
+#define ENABLE_L2CAP_LE_CREDIT_BASED_FLOW_CONTROL_MODE
-#define ENABLE_LE_SECURE_CONNECTIONS
+#define ENABLE_LE_DATA_LENGTH_EXTENSION
-#define ENABLE_LOG_ERROR
+#define ENABLE_LE_PERIPHERAL
-#define ENABLE_LOG_INFO
+#define ENABLE_LE_SECURE_CONNECTIONS
-#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS
+#define ENABLE_LOG_ERROR
-#define ENABLE_PRINTF_HEXDUMP
+#define ENABLE_LOG_INFO
-#define ENABLE_SCO_OVER_HCI
+#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS
-#define ENABLE_SDP_DES_DUMP
+#define ENABLE_PRINTF_HEXDUMP
-#define ENABLE_SOFTWARE_AES128
+#define ENABLE_SCO_OVER_HCI
-
+#define ENABLE_SDP_DES_DUMP
-// BTstack configuration. buffers, sizes, ...
+#define ENABLE_SOFTWARE_AES128
-#define HCI_ACL_PAYLOAD_SIZE (1691 + 4)
+
-#define HCI_INCOMING_PRE_BUFFER_SIZE 14 // sizeof BNEP header, avoid memcpy
+// BTstack configuration. buffers, sizes, ...
-
+#define HCI_ACL_PAYLOAD_SIZE (1691 + 4)
-#define NVM_NUM_DEVICE_DB_ENTRIES      16
+#define HCI_INCOMING_PRE_BUFFER_SIZE 14 // sizeof BNEP header, avoid memcpy
-#define NVM_NUM_LINK_KEYS              16
+
-
+#define NVM_NUM_DEVICE_DB_ENTRIES      16
-// Mesh Configuration
+#define NVM_NUM_LINK_KEYS              16
-#define ENABLE_MESH
+
-#define ENABLE_MESH_ADV_BEARER
+// Mesh Configuration
-#define ENABLE_MESH_GATT_BEARER
+#define ENABLE_MESH
-#define ENABLE_MESH_PB_ADV
+#define ENABLE_MESH_ADV_BEARER
-#define ENABLE_MESH_PB_GATT
+#define ENABLE_MESH_GATT_BEARER
-#define ENABLE_MESH_PROVISIONER
+#define ENABLE_MESH_PB_ADV
-#define ENABLE_MESH_PROXY_SERVER
+#define ENABLE_MESH_PB_GATT
-
+#define ENABLE_MESH_PROVISIONER
-#define MAX_NR_MESH_SUBNETS            2
+#define ENABLE_MESH_PROXY_SERVER
-#define MAX_NR_MESH_TRANSPORT_KEYS    16
+
-#define MAX_NR_MESH_VIRTUAL_ADDRESSES 16
+#define MAX_NR_MESH_SUBNETS            2
-
+#define MAX_NR_MESH_TRANSPORT_KEYS    16
-// allow for one NetKey update
+#define MAX_NR_MESH_VIRTUAL_ADDRESSES 16
-#define MAX_NR_MESH_NETWORK_KEYS      (MAX_NR_MESH_SUBNETS+1)
+
-
+// allow for one NetKey update
-#endif
+#define MAX_NR_MESH_NETWORK_KEYS      (MAX_NR_MESH_SUBNETS+1)
+
+#endif

port/windows-winusb/btstack_config.h

@@ -1,58 +1,60 @@
-//
+//
-// btstack_config.h for libusb port
+// btstack_config.h for Windows-winusb port
-//
+//
-
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
-#ifndef BTSTACK_CONFIG_H
+//
-#define BTSTACK_CONFIG_H
+
-
+#ifndef BTSTACK_CONFIG_H
-// Port related features
+#define BTSTACK_CONFIG_H
-#define HAVE_ASSERT
+
-#define HAVE_BTSTACK_STDIN
+// Port related features
-#define HAVE_MALLOC
+#define HAVE_ASSERT
-#define HAVE_POSIX_FILE_IO
+#define HAVE_BTSTACK_STDIN
-#define HAVE_POSIX_TIME
+#define HAVE_MALLOC
-
+#define HAVE_POSIX_FILE_IO
-// BTstack features that can be enabled
+#define HAVE_POSIX_TIME
-#define ENABLE_BLE
+
-#define ENABLE_CLASSIC
+// BTstack features that can be enabled
-#define ENABLE_CROSS_TRANSPORT_KEY_DERIVATION
+#define ENABLE_BLE
-#define ENABLE_HFP_WIDE_BAND_SPEECH
+#define ENABLE_CLASSIC
-#define ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
+#define ENABLE_CROSS_TRANSPORT_KEY_DERIVATION
-#define ENABLE_LE_CENTRAL
+#define ENABLE_HFP_WIDE_BAND_SPEECH
-#define ENABLE_L2CAP_LE_CREDIT_BASED_FLOW_CONTROL_MODE
+#define ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
-#define ENABLE_LE_DATA_LENGTH_EXTENSION
+#define ENABLE_LE_CENTRAL
-#define ENABLE_LE_PERIPHERAL
+#define ENABLE_L2CAP_LE_CREDIT_BASED_FLOW_CONTROL_MODE
-#define ENABLE_LE_PRIVACY_ADDRESS_RESOLUTION
+#define ENABLE_LE_DATA_LENGTH_EXTENSION
-#define ENABLE_LE_SECURE_CONNECTIONS
+#define ENABLE_LE_PERIPHERAL
-#define ENABLE_LOG_ERROR
+#define ENABLE_LE_PRIVACY_ADDRESS_RESOLUTION
-#define ENABLE_LOG_INFO
+#define ENABLE_LE_SECURE_CONNECTIONS
-#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS
+#define ENABLE_LOG_ERROR
-#define ENABLE_PRINTF_HEXDUMP
+#define ENABLE_LOG_INFO
-#define ENABLE_SCO_OVER_HCI
+#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS
-#define ENABLE_SDP_DES_DUMP
+#define ENABLE_PRINTF_HEXDUMP
-#define ENABLE_SOFTWARE_AES128
+#define ENABLE_SCO_OVER_HCI
-
+#define ENABLE_SDP_DES_DUMP
-// BTstack configuration. buffers, sizes, ...
+#define ENABLE_SOFTWARE_AES128
-#define HCI_ACL_PAYLOAD_SIZE (1691 + 4)
+
-#define HCI_INCOMING_PRE_BUFFER_SIZE 14 // sizeof BNEP header, avoid memcpy
+// BTstack configuration. buffers, sizes, ...
-
+#define HCI_ACL_PAYLOAD_SIZE (1691 + 4)
-#define NVM_NUM_DEVICE_DB_ENTRIES      16
+#define HCI_INCOMING_PRE_BUFFER_SIZE 14 // sizeof BNEP header, avoid memcpy
-#define NVM_NUM_LINK_KEYS              16
+
-
+#define NVM_NUM_DEVICE_DB_ENTRIES      16
-// Mesh Configuration
+#define NVM_NUM_LINK_KEYS              16
-#define ENABLE_MESH
+
-#define ENABLE_MESH_ADV_BEARER
+// Mesh Configuration
-#define ENABLE_MESH_GATT_BEARER
+#define ENABLE_MESH
-#define ENABLE_MESH_PB_ADV
+#define ENABLE_MESH_ADV_BEARER
-#define ENABLE_MESH_PB_GATT
+#define ENABLE_MESH_GATT_BEARER
-#define ENABLE_MESH_PROVISIONER
+#define ENABLE_MESH_PB_ADV
-#define ENABLE_MESH_PROXY_SERVER
+#define ENABLE_MESH_PB_GATT
-
+#define ENABLE_MESH_PROVISIONER
-#define MAX_NR_MESH_SUBNETS            2
+#define ENABLE_MESH_PROXY_SERVER
-#define MAX_NR_MESH_TRANSPORT_KEYS    16
+
-#define MAX_NR_MESH_VIRTUAL_ADDRESSES 16
+#define MAX_NR_MESH_SUBNETS            2
-
+#define MAX_NR_MESH_TRANSPORT_KEYS    16
-// allow for one NetKey update
+#define MAX_NR_MESH_VIRTUAL_ADDRESSES 16
-#define MAX_NR_MESH_NETWORK_KEYS      (MAX_NR_MESH_SUBNETS+1)
+
-
+// allow for one NetKey update
-#endif
+#define MAX_NR_MESH_NETWORK_KEYS      (MAX_NR_MESH_SUBNETS+1)
+
+#endif

tool/misc/update_btstack_config_docu_link.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+import re
+
+config_header_template = """// btstack_config.h for PORT_NAME port
+//
+// Documentation: https://bluekitchen-gmbh.com/btstack/#how_to/
+"""
+
+btstack_root = os.path.abspath(os.path.dirname(sys.argv[0]) + '/../../port/')
+
+def write_configuration(full_path, configuration):
+    if configuration:
+        with open(full_path, "wb") as fout:
+            bytes = configuration.encode('utf-8')
+            fout.write(bytes)
+
+def get_line_ending(full_path):
+    with open(full_path, "r", newline='') as fin:
+        line = fin.readline()
+        if line.endswith('\r\n'):
+            return '\r\n'
+        if line.endswith('\r'):
+            return '\r'
+        return '\n'
+
+def read_and_update_configuration(full_path, line_ending, root):
+    configuration = ""
+
+    port_name = root.split("port/")[1].split("/")[0]
+    if port_name.startswith("archive"):
+        return
+
+    with open(full_path, "rt") as fin:
+        for unstripped_line in fin:
+            line = unstripped_line.strip()
+
+            parts = re.match('(//\s*btstack_config.h\s)(\w*)', line)
+            if parts and len(parts.groups()) == 2:
+                configuration += config_header_template.replace("PORT_NAME", port_name).replace("\r\n", line_ending)
+            else:
+                configuration += unstripped_line
+    return configuration
+
+for root, dirs, files in os.walk(btstack_root, topdown=True):
+    for f in files:
+        if f.endswith("btstack_config.h"):
+            config_file = root + "/" + f
+            line_ending = get_line_ending(config_file)
+            configuration = read_and_update_configuration(config_file, line_ending, root)
+            write_configuration(config_file, configuration)