From 0179ba640fbea214ff06e259b9fca5560341f1f1 Mon Sep 17 00:00:00 2001 From: Milanka Ringwald Date: Thu, 2 Mar 2023 09:36:11 +0100 Subject: [PATCH] doc: update cross-file links --- doc/manual/docs-template/architecture.md | 4 +-- doc/manual/docs-template/how_to.md | 6 ++-- doc/manual/docs-template/integration.md | 6 ++-- doc/manual/docs-template/profiles.md | 36 ++++++++++++------------ doc/manual/docs-template/protocols.md | 12 ++++---- 5 files changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/manual/docs-template/architecture.md b/doc/manual/docs-template/architecture.md index 4598083c5..770a490c1 100644 --- a/doc/manual/docs-template/architecture.md +++ b/doc/manual/docs-template/architecture.md @@ -27,7 +27,7 @@ events and data coming from either the Main Application or from BTstack via registered packet handlers (PH). BTstack’s Run Loop is responsible for providing timers and processing incoming data. -![Architecture of a BTstack-based application.](picts/btstack-architecture.png) {#fig:BTstackArchitecture} +![Architecture of a BTstack-based application.](/picts/btstack-architecture.png) {#fig:BTstackArchitecture} ## Single threaded design @@ -41,7 +41,7 @@ events. During a run loop cycle, the callback functions of all registered data sources are called. Then, the callback functions of timers that are ready are executed. -For adapting BTstack to multi-threaded environments check [here](integration/#sec:multithreadingIntegration). +For adapting BTstack to multi-threaded environments check [here](/integration/#sec:multithreadingIntegration). ## No blocking anywhere diff --git a/doc/manual/docs-template/how_to.md b/doc/manual/docs-template/how_to.md index 0fe681ded..477f89b46 100644 --- a/doc/manual/docs-template/how_to.md +++ b/doc/manual/docs-template/how_to.md @@ -105,7 +105,7 @@ BTstack properties: | ENABLE_L2CAP_ENHANCED_CREDIT_BASED_FLOW_CONTROL_MODE | Enable Enhanced credit-based flow-control mode for L2CAP Channels | | ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL | Enable HCI Controller to Host Flow Control, see below | | ENABLE_HCI_SERIALIZED_CONTROLLER_OPERATIONS | Serialize Inquiry, Remote Name Request, and Create Connection operations | -| ENABLE_ATT_DELAYED_RESPONSE | Enable support for delayed ATT operations, see [GATT Server](profiles/#sec:GATTServerProfile) | +| ENABLE_ATT_DELAYED_RESPONSE | Enable support for delayed ATT operations, see [GATT Server](/profiles/#sec:GATTServerProfile) | | ENABLE_BCM_PCM_WBS | Enable support for Wide-Band Speech codec in BCM controller, requires ENABLE_SCO_OVER_PCM | | ENABLE_CC256X_ASSISTED_HFP | Enable support for Assisted HFP mode in CC256x Controller, requires ENABLE_SCO_OVER_PCM | | Enable_RTK_PCM_WBS | Enable support for Wide-Band Speech codec in Realtek controller, requires ENABLE_SCO_OVER_PCM | @@ -501,7 +501,7 @@ The arguments are: [platform/embedded/hci_transport_h4_embedded.c]() and then getting a pointer to HCI Transport implementation. For more information on adapting HCI Transport to different - environments, see [here](porting/#sec:hciTransportPorting). + environments, see [here](/porting/#sec:hciTransportPorting). @@ -552,7 +552,7 @@ Finally, the HCI implementation requires some form of persistent storage for lin during either legacy pairing or the Secure Simple Pairing (SSP). This commonly requires platform specific code to access the MCU’s EEPROM of Flash storage. For the first steps, BTstack provides a (non) persistent store in memory. -For more see [here](porting/#sec:persistentStoragePorting). +For more see [here](/porting/#sec:persistentStoragePorting). diff --git a/doc/manual/docs-template/integration.md b/doc/manual/docs-template/integration.md index 7671c0b00..75dc66505 100644 --- a/doc/manual/docs-template/integration.md +++ b/doc/manual/docs-template/integration.md @@ -20,7 +20,7 @@ In a single-threaded environment, all application components run on the same (single) thread and use direct function calls as shown in Figure {@fig:BTstackSingle}. -![BTstack in single-threaded environment.](picts/singlethreading-btstack.png) {#fig:BTstackSingle} +![BTstack in single-threaded environment.](/picts/singlethreading-btstack.png) {#fig:BTstackSingle} BTstack provides a basic run loop that supports the concept of data sources and timers, which can be registered centrally. This works well @@ -67,7 +67,7 @@ common options: Communication (IPC) as depicted in Figure {@fig:MTMonolithic}. This option results in less code and quick adaption. - ![BTstack in multi-threaded environment - monolithic solution.](picts/multithreading-monolithic.png) {#fig:MTMonolithic} + ![BTstack in multi-threaded environment - monolithic solution.](/picts/multithreading-monolithic.png) {#fig:MTMonolithic} - BTstack must be extended to run standalone, i.e, as a Daemon, on a dedicated thread and the Main Application controls this daemon via @@ -76,4 +76,4 @@ common options: in Figure {@fig:MTDaemon}. This option requires more code but provides more flexibility. - ![BTstack in multi-threaded environment - solution with daemon.](picts/multithreading-btdaemon.png) {#fig:MTDaemon} + ![BTstack in multi-threaded environment - solution with daemon.](/picts/multithreading-btdaemon.png) {#fig:MTDaemon} diff --git a/doc/manual/docs-template/profiles.md b/doc/manual/docs-template/profiles.md index 12adbcc5b..360a3377a 100644 --- a/doc/manual/docs-template/profiles.md +++ b/doc/manual/docs-template/profiles.md @@ -121,7 +121,7 @@ device implements Bluetooth Specification 2.1 or higher, the *hci_write_inquiry_mode* command enables reporting of this advanced features (0 for standard results, 1 for RSSI, 2 for RSSI and EIR). -A complete GAP inquiry example is provided [here](examples/examples/#sec:gapinquiryExample). +A complete GAP inquiry example is provided [here](/examples/examples/#sec:gapinquiryExample). ### Pairing of Devices @@ -168,7 +168,7 @@ user. Regardless of the authentication mechanism (PIN/SSP), on success, both devices will generate a link key. The link key can be stored either in the Bluetooth module itself or in a persistent storage, see -[here](porting/#sec:persistentStoragePorting). The next time the device connects and +[here](/porting/#sec:persistentStoragePorting). The next time the device connects and requests an authenticated connection, both devices can use the previously generated link key. Please note that the pairing must be repeated if the link key is lost by one device. @@ -186,7 +186,7 @@ bonding via the *gap_dedicated_bonding* function. The SPP profile defines how to set up virtual serial ports and connect two Bluetooth enabled devices. Please keep in mind that a serial port does not preserve packet boundaries if you try to send data as packets and read about -[RFCOMM packet boundaries]({protocols/#sec:noRfcommPacketBoundaries}). +[RFCOMM packet boundaries](/protocols/#sec:noRfcommPacketBoundaries). ### Accessing an SPP Server on a remote device @@ -195,18 +195,18 @@ for its SPP services. Section [on querying remote SDP service](#sec:querySDPProt shows how to query for all RFCOMM channels. For SPP, you can do the same but use the SPP UUID 0x1101 for the query. After you have identified the correct RFCOMM channel, you can create an RFCOMM connection as shown -[here](protocols/#sec:rfcommClientProtocols). +[here](/protocols/#sec:rfcommClientProtocols). ### Providing an SPP Server To provide an SPP Server, you need to provide an RFCOMM service with a specific RFCOMM channel number as explained in section on -[RFCOMM service](protocols/#sec:rfcommServiceProtocols). Then, you need to create +[RFCOMM service](/protocols/#sec:rfcommServiceProtocols). Then, you need to create an SDP record for it and publish it with the SDP server by calling *sdp_register_service*. BTstack provides the *spp_create_sdp_record* function in that requires an empty buffer of approximately 200 bytes, the service channel number, and a service name. -Have a look at the [SPP Counter example](examples/examples/#sec:sppcounterExample). +Have a look at the [SPP Counter example](/examples/examples/#sec:sppcounterExample). ## PAN - Personal Area Networking Profile {#sec:panProfiles} @@ -244,14 +244,14 @@ Currently, BTstack supports only PANU. To access a remote PANU service, you first need perform an SDP query to get the L2CAP PSM for the requested PANU UUID. With these two pieces of information, you can connect BNEP to the remote PANU service with the -*bnep_connect* function. The Section on [PANU Demo example](examples/examples/#sec:panudemoExample) +*bnep_connect* function. The Section on [PANU Demo example](/examples/examples/#sec:panudemoExample) shows how this is accomplished. ### Providing a PANU service To provide a PANU service, you need to provide a BNEP service with the service UUID, e.g. the PANU UUID, and a maximal ethernet frame size, -as explained in Section [on BNEP service](protocols/#sec:bnepServiceProtocols). Then, you need to +as explained in Section [on BNEP service](/protocols/#sec:bnepServiceProtocols). Then, you need to create an SDP record for it and publish it with the SDP server by calling *sdp_register_service*. BTstack provides the *pan_create_panu_sdp_record* function in *src/pan.c* that requires an @@ -404,9 +404,9 @@ Typical HID hosts would be a personal computer, tablets, gaming console, industr Please refer to: -- [HID Host API](appendix/apis/#sec:hidHostAPIAppendix) and [hid_host_demo](examples/examples/#sec:hidhostdemoExample) for the HID Host role +- [HID Host API](/appendix/apis/#sec:hidHostAPIAppendix) and [hid_host_demo](/examples/examples/#sec:hidhostdemoExample) for the HID Host role -- [HID Device API](appendix/apis/#sec:hidDeviceAPIAppendix), [hid_keyboard_demo](examples/examples/#sec:hidkeyboarddemoExample) and [hid_mouse_demo](examples/examples/#sec:hidmousedemoExample) for the HID Device role. +- [HID Device API](/appendix/apis/#sec:hidDeviceAPIAppendix), [hid_keyboard_demo](/examples/examples/#sec:hidkeyboarddemoExample) and [hid_mouse_demo](/examples/examples/#sec:hidmousedemoExample) for the HID Device role. ## GAP LE - Generic Access Profile for Low Energy @@ -435,7 +435,7 @@ with *gap_random_address_set_update_period*. After a connection is established, the Security Manager will try to resolve the peer Bluetooth address as explained in Section on -[SMP](protocols/#sec:smpProtocols). +[SMP](/protocols/#sec:smpProtocols). ### Advertising and Discovery @@ -455,7 +455,7 @@ can also provide Scan Response data, which has to be explicitly queried by the central device. It can be set with *gap_scan_response_set_data*. Please have a look at the [SPP and LE -Counter example](examples/examples/#sec:sppandlecounterExample). +Counter example](/examples/examples/#sec:sppandlecounterExample). The scan parameters can be set with *gap_set_scan_parameters*. The scan can be started/stopped @@ -532,12 +532,12 @@ If the device provides sufficient IO capabilities, a MITM attack can then be pre The following diagrams provide a detailed overview about the GATT Client security mechanisms in different configurations: -- [Reactive Authentication as Central](picts/gatt_client_security_reactive_authentication_central.svg) -- [Reactive Authentication as Peripheral](picts/gatt_client_security_reactive_authentication_peripheral.svg) -- [Proactive Authentication as Central](picts/gatt_client_security_proactive_authentication_central.svg) -- [Proactive Authentication as Peripheral](picts/gatt_client_security_proactive_authentication_peripheral.svg) -- [Mandatory Authentication as Central](picts/gatt_client_security_mandatory_authentication_central.svg) -- [Mandatory Authentication as Peripheral](picts/gatt_client_security_mandatory_authentication_peripheral.svg) +- [Reactive Authentication as Central](/picts/gatt_client_security_reactive_authentication_central.svg) +- [Reactive Authentication as Peripheral](/picts/gatt_client_security_reactive_authentication_peripheral.svg) +- [Proactive Authentication as Central](/picts/gatt_client_security_proactive_authentication_central.svg) +- [Proactive Authentication as Peripheral](/picts/gatt_client_security_proactive_authentication_peripheral.svg) +- [Mandatory Authentication as Central](/picts/gatt_client_security_mandatory_authentication_central.svg) +- [Mandatory Authentication as Peripheral](/picts/gatt_client_security_mandatory_authentication_peripheral.svg) ## GATT Server {#sec:GATTServerProfiles} diff --git a/doc/manual/docs-template/protocols.md b/doc/manual/docs-template/protocols.md index 49ca0b12d..92237ff98 100644 --- a/doc/manual/docs-template/protocols.md +++ b/doc/manual/docs-template/protocols.md @@ -514,8 +514,8 @@ application such that it can manage its receive buffers explicitly, see Listing [below](#lst:explicitFlowControl). Manual credit management is recommended when received RFCOMM data cannot -be processed immediately. In the [SPP flow control example](examples/generated/#sec:sppflowcontrolExample), -delayed processing of received data is +be processed immediately. In the [SPP flow control example](/examples/examples/#spp-server-rfcomm-flow-control +delayed) processing of received data is simulated with the help of a periodic timer. To provide new credits, you call the *rfcomm_grant_credits* function with the RFCOMM channel ID and the number of credits as shown in Listing [below](#lst:NewCredits). @@ -652,7 +652,7 @@ record. ### Query remote SDP service {#sec:querySDPProtocols} BTstack provides an SDP client to query SDP services of a remote device. -The SDP Client API is shown in [here](appendix/apis/#sec:sdpAPIAppendix). The +The SDP Client API is shown in [here](/appendix/apis/#sec:sdpAPIAppendix). The *sdp_client_query* function initiates an L2CAP connection to the remote SDP server. Upon connect, a *Service Search Attribute* request with a *Service Search Pattern* and a *Attribute ID List* is sent. The @@ -744,7 +744,7 @@ To receive BNEP events, please register a packet handler with To connect to a remote BNEP service, you need to know its UUID. The set of available UUIDs can be queried by a SDP query for the PAN profile. -Please see section on [PAN profile](profiles/#sec:panProfiles) for details. +Please see section on [PAN profile](/profiles/#sec:panProfiles) for details. With the remote UUID, you can create a connection using the *bnep_connect* function. You’ll receive a *BNEP_EVENT_CHANNEL_OPENED* on success or failure. @@ -790,7 +790,7 @@ type, and a set of properties. The Generic Attribute (GATT) profile is built upon ATT and provides higher level organization of the ATT attributes into GATT Services and GATT Characteristics. In BTstack, the complete ATT client functionality -is included within the GATT Client. See [GATT client](profiles/#sec:GATTClientProfiles) for more. +is included within the GATT Client. See [GATT client](/profiles/#sec:GATTClientProfiles) for more. On the server side, one ore more GATT profiles are converted ahead of time into the corresponding ATT attribute database and provided by the *att_server* @@ -798,7 +798,7 @@ implementation. The constant data are automatically served by the ATT server upo request. To receive the dynamic data, such is characteristic value, the application needs to register read and/or write callback. In addition, notifications and indications can be sent. Please see Section on -[GATT server](profiles/#sec:GATTServerProfile) for more. +[GATT server](/profiles/#sec:GATTServerProfile) for more. ## SMP - Security Manager Protocol {#sec:smpProtocols}