From 9026073a419b5ef68fb46d4f7fae52dbef09dbe1 Mon Sep 17 00:00:00 2001 From: Barry Golden Date: Thu, 6 Aug 2015 20:06:07 -0700 Subject: Remove obsolete readme.htm files --- bluetooth/bthecho/bthecho.htm | 2222 ------------------- .../serialhcibus/BluetoothHCISampleBusDriver.htm | 2333 -------------------- 2 files changed, 4555 deletions(-) delete mode 100644 bluetooth/bthecho/bthecho.htm delete mode 100644 bluetooth/serialhcibus/BluetoothHCISampleBusDriver.htm (limited to 'bluetooth') diff --git a/bluetooth/bthecho/bthecho.htm b/bluetooth/bthecho/bthecho.htm deleted file mode 100644 index 9ea0ff09..00000000 --- a/bluetooth/bthecho/bthecho.htm +++ /dev/null @@ -1,2222 +0,0 @@ - - - - - - - - -BTHECHO - - - - - - - - - - - -
- -

Bluetooth Echo Sample

- -

SUMMARY

- -

This sample demonstrates developing Bluetooth L2CAP -profile drivers using Bluetooth L2CAP DDIs.

- -

The sample includes two drivers. One for a device that -acts as an L2CAP server and another for the device that acts as an L2CAP -client. Server simply echoes back any data that it receives from client on the -same L2CA channel.

- -

These drivers can be used with devices that can be -installed with bth.inf. Such devices get installed as ‘Generic Bluetooth -Radio’. Examples of such devices are Bluetooth USB dongles such as (but not -limited to):

- -

Generic Bluetooth -Radio=                         -BthUsb, USB\Vid_0a12&Pid_0001

- -

CSR Nanosira=                                    -BthUsb, USB\Vid_0a12&Pid_0003

- -

CSR Nanosira -WHQL Reference -Radio=               -BthUsb, USB\Vid_0a12&Pid_0004

- -

CSR Nanosira-Multimedia=                         -BthUsb, USB\Vid_0a12&Pid_0005

- -

CSR Nanosira-Multimedia -WHQL Reference Radio=    BthUsb, -USB\Vid_0a12&Pid_0006

- -

Please refer to bth.inf for the complete list of -devices.

- -

The installation steps below describe how to install -echo server and client with such a device.

- -

Please note that RFCOMM based profiles must be -developed and accessed using user-mode socket APIs.

- -

This sample is applicable to Windows® Vista, Windows® -7 and Windows® Developer Preview operating systems.

- -

BUILDING THE SAMPLE

- -

To build the sample drivers and exe, you must first -set up the WDK environment on your host machine on your Windows Developer -Preview operating system.

- -

Run msbuild command -in the bthecho directory as follows

- -

1.    BthEcho.lib (common library for the -Bluetooth Echo sample)

- -

cd bthecho\common\lib
-msbuild /t:clean /t:build BthEcho.VcxProj

- -

2.    BthEchoSampleSrv.sys (driver for -Bluetooth Echo Server device)

- -

cd ..\..\bthsrv\sys
-msbuild /t:clean -/t:build BthEchoSampleSrv.VcxProj

- -

3.    BthSrvInst.exe (Bluetooth echo -sever installation utility)

- -

cd ..\inst
-msbuild /t:clean -/t:build bthsrvinst.VcxProj

- -

4.    BthEchoSampleCli.sys (driver for -Bluetooth Echo client device)

- -

cd ..\..\bthcli\ sys
-msbuild /t:clean -/t:build BthEchoSampleCli.VcxProj

- -

5.    BthEcho.exe (Bluetooth echo -application used to exercise client device)

- -

cd ..\app
-msbuild /t:clean -/t:build BthEcho.VcxProj

- -

 

- -

INSTALLATION

- -

Note: Bluetooth echo server device and echo client device -must be installed on two different machines.

- -

 

- -

Server Installation

- -

1.    -Copy KMDF coinstaller -(wdfcoinstallerMMmmm.dll, from redist\wdf\ ), BthEchoSampleSrv.Sys, -BthEchoSampleSrv.inf and bthsrvinst.exe on a temporary directory on the -target machine.

- -

2.    -Run bthsrvinst.exe /i -to install the echo server device. This enables the Bluetooth Enumerator -(BthEnum.sys) to enumerate echo server device and create a PDO for the device -(please refer to the device tree below).

- -

2.    -Step #2 causes BthEnum.sys to create a PDO. -Consequently hardware installation wizard gets launched. Either go through the UI (Device Manager – Update Driver Software -in Windows® 7, ‘Found New Hardware’ wizard in Windows® Vista) and point it to -the temporary directory where you copied the binaries in step #1, or using -devcon.exe from the tools\devcon folder, run the -following command from the temporary directory:

- -

devcon.exe update BthEchoSampleSrv.inf -BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4}

- -

If devcon.exe fails -check the error level using:

- -

echo %errorlevel%

- -

If errorlevel is 1, you need to reboot the machine for KMDF -update to take effect. If errorlevel is 2, please -make sure that you have the driver files described in #1 available in the -current directory. For more information on installation failure please check -setup logs.

- -

4.    -Upon successful installation you will see ‘Bluetooth -Echo Sample Server’ in Device Manager under Bluetooth devices.

- -

5.    -(This steps in needed only on Windows® Vista) Navigate -to the system tray, right click on the Bluetooth icon, and select ‘Open Settings’. -This launches the ‘Bluetooth Settings’ dialog. On the ‘Options’ tab, check -‘Allow Bluetooth devices to find this Computer’. Note that this will make your -computer discoverable to other Bluetooth devices, and should be disabled again -when no longer required.

- -

 

- -

Device tree for Echo Server device

- -

 

- -

(Drivers for FDOs are shown for each devnode -in the tree.)

- -

 

- -
                   ---------------------
                  |                     |
                  |BthEchoSampleSrv.sys |<---------------Function driver for PDO ejected by BthEnum.sys
                  |                     |
                   ---------------------
                            ^
                            |          ---------------------
                            |         |                     |
                            |         |Bluetooth Enumerator |
                            --------- |    (BthEnum.SYS)    | 
                                      |                     |
                                       ---------------------
                                                 ^
                                                 |
                                                 |          ---------------------            ---------------------
                                                 |         |                     |          |                     |
                                                 ----------|     bthport.SYS     |<-------->|     bthusb.SYS      |       
                                                           |                     |          |                     |
                                                            ---------------------            ---------------------
- -

                                                            -Bth port driver loaded by bthusb.sys -       ^

- -

                                                                                                        -|

- -

                                                              -                                          V

- -

                                                                                               ----------------------

- -

                                                                                              -|                     -|

- -

                                                                                              -|      USB Stack      |

- -

                                                                                              -|                    - |

- -

                                                                                               ----------------------

- -

                                                         -                                               ^

- -

                                                                                                        -|   

- -

                                                                                                 -       V

- -

                                                                                               -----------------------

- -

                                                                                              -| USB Bluetooth Dongle |

- -

          -                                                                                     ----------------------

- -

Client Installation

- -

1.    Important: This must be done on a -separate machine from the one where echo server device was installed.

- -

2.    Copy KMDF coinstaller -(wdfcoinstallerMMmmm.dll, from redist\wdf\), BthEchoSampleCli.Sys, -BthEchoSampleCli.inf and bthecho.exe on a temporary directory on the target -machine.

- -

3.    Run bthprops.cpl from a command line or right -click on the Bluetooth icon in the system tray and select ‘Show Devices' to -bring up a list of installed Bluetooth devices.

- -

4.   Windows® 7:  In the ‘Bluetooth Devices’ window click the ‘Add a -device’ button. Windows® Vista: In the ‘Devices’ tab, click Add button.

- -

5.    In the Add a Device wizard select the server machine (the machine where -you installed the echo server) as a Bluetooth device. If the server machine -does not appear, please check the echo server installation and make sure that -you have enabled ‘Allow Bluetooth device to find this computer’ on the server -machine as explained above. When the server machine is correctly displayed, -select it and pick ‘Next’.

- -

6. The wizard should default to a numeric compare -ceremony for pairing the machines. When this happens, ensure the numbers match -on both the client and the server, select ‘Yes’ on both machines to indicate -they match, and click ‘Next’ on both machines to complete the pairing.

- -

7. The ‘Found New Hardware’ wizard will be launched on -Windows® Vista. On Windows® 7 and Windows® Developer Preview you will need to -go through Device Manager and update driver software for it. Either point the -wizard to the temporary directory created in step #2, or use devcon.exe from -the tools\devcon folder to install the client device:

- -

Devcon.exe update BthEchoSampleCli.inf BTHENUM\{c07508f2-b970-43ca-b5dd-cc4f2391bef4}

- -

Check for any error from devcon.exe as described in -server installation.

- -

If the installation is successful, you will see -‘Bluetooth Echo Sample Client’ in Device Manager under Bluetooth devices.

- -

 

- -

The device tree for echo client device is similar to -the one shown for the echo server device, since both client and server are -enumerated by BthEnum.sys (although the installation mechanism and properties -of client and server are different).

- -

 

- -

Uninstalling Server

- -

1.  Uninstall the device and delete driver -software using the Bluetooth Devices window by running bthprops.cpl, -right clicking on the device, and selecting ‘Remove Device’

- -

2.  Run bthsrvinst.exe /u to -uninstall the echo server. This would make bthenum.sys stop enumerating the -echo server. Without this step ‘Found New Hardware’ wizard will be launched -again when you reconnect the device.

- -

Uninstalling Client

- -

1.  Uninstall the device and delete driver -software using the Bluetooth Devices window by running bthprops.cpl, -right clicking on the device, and selecting ‘Remove Device’

- -

TESTING

- -

Run BthEcho.exe on the client machine. You should see -client sending data to the server and receiving the same data echoed back. -Press Ctrl+c to terminate the application. You will -see output similar to below:

- -

D:\bth\wdfcli>BthEcho.exe

- -

DevicePath: -\\?\bthenum#{c07508f2-b970-43ca-b5dd-cc4f2391bef4}_localmfg&000a#7&3

- -

62d0a3&0&000c55ff727a_c00000001#{fc71b33d-d528-4763-a86c-78777c7bcd7b}

- -

Opened device successfully

- -

Written                 -26 bytes: WDF Bluetooth Sample Echo

- -

Reply from server       26 bytes: WDF -Bluetooth Sample Echo

- -

Written                 -26 bytes: WDF Bluetooth Sample Echo

- -

Reply from server       26 bytes: WDF -Bluetooth Sample Echo

- -

Written                 -26 bytes: WDF Bluetooth Sample Echo

- -

Reply from server       26 bytes: WDF -Bluetooth Sample Echo

- -

Written                 -26 bytes: WDF Bluetooth Sample Echo

- -

Reply from server       26 bytes: WDF -Bluetooth Sample Echo

- -

Written                 -26 bytes: WDF Bluetooth Sample Echo

- -

^C

- -

You can launch multiple instances of BthEcho.exe. Each -client application would cause echo client device to have an independent -connection to the echo server and thereby have an independent echo session. You -can also have echo client devices and apps installed on multiple machines and -talking to a single echo server.

- -

DIRECTORY MANIFEST

- -
File           Description
 
bthcli         contains files for Bluetooth echo sample client
bthcli\sys     contains driver code for echo client (produces BthEchoSampleCli.sys and BthEchoSampleCli.inf)
bthcli\app     contains code for echo test application (produces BthEcho.exe)
bthsrv         contains files for Bluetooth echo sample server
bthsrv\sys     contains driver code for echo server (produces BthEchoSampleSrv.sys and BthEchoSampleSrv.inf)
bthsrv\inst    contains code for server installation utility (produces bthsrvinst.exe)
common         contains headers and code shared by client and server
common\inc     contains common headers
common\lib     contains common code (produces bthecho.lib used while building BthEchoSampleSrv.sys and BthEchoSampleCli.sys)
- -

FILE MANIFEST

- -

(build related files and inx files omitted for brevity)

- -

 

- -

bthcli\sys

- -

 

- -
File           Description
 
driver.*       contains WDF driver functionality
device.*       contains Bluetooth echo client device functionality
client.*       contains reusable code for Bluetooth L2CAP client, this code is used by device.*
queue.*        contains code for WDF queue used for read/write operations
 
- -

bthcli\app

- -

 

- -
File           Description
 
main.cpp       contains code for writing to and reading from Bluetooth echo client
 
bthsrv\sys
 
File           Description
 
driver.*       WDF driver functionality
device.*       contains Bluetooth echo server device functionality
server.*       contains reusable code for Bluetooth L2CAP server, this code is used by device.*
echo.*         contains functionality for sending echo to the client
sdp.*          contains code for building server SDP record
 
bthsrv\inst
 
File           Description
 
main.cpp       contains code for installing and uninstalling echo sample server
 
common\inc
 
File           Description
 
clisrv.h       header for common functions used by both echo client and echo server drivers
connection.h   contains header for connection object used by both echo client and echo server drivers
public.h       definitions used by echo client and server drivers as well as install and echo apps
trace.h        tracing related definitions
 
common\lib
 
File           Description
 
clisrv.c       code for common functions used by both echo client and echo server drivers
connection.c   contains code for connection object used by both echo client and echo server drivers
- -

CODE TOUR

- -

Common code

- - - -

Server

- -

·         -Startup: Server -registers PSM and L2CA server and published SDP record on startup in BthEchoSrvEvtDeviceSelfManagedIoInit (this callback is -invoked by WDF during device start). While registering the L2CA server it -passes BthEchoSrvIndicationCallback as the callback -for incoming connection notifications.

- -

·         -Server SDP record creation: The sample uses dynamic creation of server SDP record -using Bluetooth DDIs. Please note that for your particular device you may be -able to use static data for the SDP record.

- -

·         -Incoming connections: Bluetooth stack invokes BthEchoSrvIndicationCallback -for the incoming connections from clients. In response server accepts the -connection and passes BthEchoSrvConnectionIndicationCallback -callback to Bluetooth stack for disconnect notification. It is possible to use -the same indication callback for server and connection but the sample uses -different callbacks for clarity. Server adds the accepted connection to the -connection list it maintains. Please see below for connection rundown details.

- -

·         -Connection rundown: Server maintains a list of all the connections it has accepted. This -allows server to properly close down these connections on orderly removal. On -surprise removal bthport.sys itself gets removed and takes care of running down -the connections, but in case of orderly removal driver has to make sure to -rundown the connections.

- -

·         -Connection state machine:

- -

                                                                   -                            ConnectFailed

- -
                                                     ^
                                                     |
                                                     |          
                                                     | (connection failure)
- -

                         - Uninitialized   ------> Connecting ------> Connected

- -
                                                     | (disconnect)  /  ^ 
                                                     |              /  /
                                                     |             /  /
                                                     V            V  / (connection complete)
- -

                                                  -Disconnecting   

- -
                                                     | (disconnect complete)
                                                     |          
                                                     |             
                                                     V           
- -

                                                  -Disconnected

- -

 

- -

One transition to note here is that if disconnect is -received in the connecting state (i.e. when the connection is not completed) we -wait for connection to completed (transition to connected state) and then -invoke -disconnect.                                         -

- -

 

- -

Important: Such state machine is needed only if Disconnect is initiated by -something other than Bluetooth stack (for example device removal in our case). -Bluetooth stack itself would not send disconnect before connect completion. If -you adapt this sample for your device please evaluate whether your driver would -require such state machine. For example, the echo client device does not need -such state machine (although we use common connection code for client and the -server).

- -

 

- - - -

Client

- - - -

RESOURCES

- -

For the latest release of the Windows device Driver -Development Kit, see http://www.microsoft.com/whdc/. -For Bluetooth user mode APIs used in BthSrvInst.exe please see MSDN (http://msdn.microsoft.com).

- -

Please see the latest WDK release for documentation on -Bluetooth and WDF.

- -

If you have questions on using or adapting this sample -for your project, you can post your questions in the Microsoft -driver development newsgroup.

- -

 

- -

Top of page

- - - - - -
- -

© 2009 Microsoft Corporation. All rights reserved.

- -
- - - - diff --git a/bluetooth/serialhcibus/BluetoothHCISampleBusDriver.htm b/bluetooth/serialhcibus/BluetoothHCISampleBusDriver.htm deleted file mode 100644 index 375b609d..00000000 --- a/bluetooth/serialhcibus/BluetoothHCISampleBusDriver.htm +++ /dev/null @@ -1,2333 +0,0 @@ - - - - - - - - -BluetoothHciSampleBusDriver - - - - - - - - - -
- -

README—Bluetooth Serial HCI Sample Bus Driver

- -

 

- -

VERSION 0.2

- -

 

- -

Note: The sample driver & this documentation are -in their pre-release versions, thus they are both subject to change at any time

- -

 

- -

6/22/2011

- -

AUTHOR - Windows Bluetooth

- -

1       Document purpose

- -

 

- -

The purpose of this -sample is to demonstrate how to implement a basic bus driver to support the new -Bluetooth Extensibility transport DDIs over the UART transport. Such a serial -bus driver can support a multi-radio device over the UART transport and utilize -a common Bluetooth HCI packet for communication. The lower edge of this driver -interfaces with a UART controller following the Bluetooth SIG’s UART (H4) -transport protocol.

- -

 

- -

Note:

- -

·         This sample driver is generic—i.e. it is -not designed for a specific device and allows for a vendor to adopt and enhance -it for supporting Bluetooth

- -

·         This sample driver, as is, may not -properly function for a device until all vendor-specific device requirements -(e.g. device initialization) have been incorporated

- -

·         It is recommended to use WDK whose -version matches the target Windows build version or newer for the development -of the serial bus driver

- -

 

- -

2       Building the sample

- -

 

- -

1.       Open the project file (SerialHciBus\WDK\SerialBusWDK VC++ -project) from Visual Studio Dev11 to build this project.

- -

2.       After rebuilding the driver, you can -find SerialBusWDK.sys/pdb/inf -files.

- -

 

- -

3       Directory Manifest

- -

 

- -

File Description

- -

SerialHciBus – contains files for the Bluetooth -serial HCI bus driver

- -

SerialHciBus\Wdk – -contains driver code for device specific functions (produces SerialBusWdk.sys -and SerialBusWdk.inf)

- -

 

- -

4       File Manifest

- -

4.1        WDK header file

- -

·         BthXDDI.h – this has the constants, -struct, and IOCTL definitions for the Bluetooth extensibility transport. This -header file is included in WDK.

- -

4.2        Common code section

- -
    -
  1. driver.c – driver initialization
    2. -
  2. driver.h – common header file for driver.c and includes other header files
    3. -
  3. Fdo.c – functions for function - device object (FDO) and BTHX DDI processing
    4. -
  4. io.c – functions that perform IO - read pump via UART controller
    5. -
  5. Io.h – header for io.c
    6. -
  6. pdo.c – PDO (Bluetooth function) - enumeration and IOCTL processing
    7. -
  7. public.h – header to share with - application to support Radio On/Off (“Airplane mode”)
    8. -
- -

 

- -

Note: The goal is to -keep the common code section the same, so the vendor will only need to update -those code sections in the device specific directory.

- -

4.3        Device-specific code section

- -
    -
  1. Debugdef.h – WPP trace GUID; user should - use a new GUID (unique per driver)
    2. -
  2. device.c – device specific functions to - implement
    3. -
      -
    1. DeviceInitialize() - – to perform UART and Bluetooth device initialization;
      2. -
    2. DeviceEnable() - – (optional) to bring serial bus device out of disable/reset state.
      3. -
    3. DevicePowerOn() - – (optional) to power on the device.
      4. -
    4. DeviceEnableWakeControl() – (optional) to arm for device wake signal
      5. -
    5. DeviceDisableWakeControl() – (optional) to disarm for device wake signal
      6. -
    -
  3. device.h – header file for device.c
    4. -
  4. driver.rc – driver version and name
    5. -
  5. SerialBusWdk.inx – device specific INF file to - install this driver. The vendor will need to add the hardware ID to match - the “_HID” for the Serial Bus Device (Bluetooth) in the DSDT.asl file. For example, in SerialBusWDK.inx, - the hardware ID is “ACPI\<Vendor>_BTH0” where “<vendor>” could - be a 4 digit vendor name
    6. -
- -

 

- -

5       Installation

- -

 

- -

The vendor can adopt -this driver to add device specific functions, e.g. vendor-specific device -initialization. After this is completed, the following steps can be followed to -perform device installation in order to test the driver:

- -

·         Copy driver and inf file to a directory on the test system

- -

·         Perform “Update Driver” on the devnode corresponding to the hardware ID in the DSDT.asl file for this multifunction serial bus driver

- -

·         Point the installation to the -directory to find the INF and sys files

- -

·         Upon successful installation, you will -see “Serial Bus Driver over UART Bus Enumerator" in Device Manager under -the Ports device class

- -

·         Upon successful installation of the -serial bus driver, a PDO will be created with a compat ID of “MS_BTHX_BTHMINI.” -This will cause PnP to find the match in bth.inf to perform the installation of -the Bluetooth core components with its extensibility transport

- -

 

- -

Pre-requisite: -DSDT.ASL

- -

A multifunction serial -bus device is a peripheral device on a SoC platform. Its configuration is often -defined in the DSDT.asl (Differentiated System -Description Table) file to reflect its configuration and interconnection with a -UART controller and other optional dependent controllers, e.g. I2C, GPIO, etc. -for additional control.

- -

Here is an -(incomplete) sample system bus device section of a DSDT.ASL file for a UART -controller and a multifunction serial bus device that supports Bluetooth. For -details, please reference the document “Minimum WOA ACPI Requirements.docx” -from Microsoft.

- -

 

- -

//

- -

// -UART where a serial bus device is connected to

- -

//

- -

Device -(UAR1)

- -

{

- -

    -Name (_HID, "ABCD_UART")      // where -“ABCD” is vendor name;

- -

    -// …

- -

 

- -

    -Name (_CID, "ACPI\ABCD_UART")

- -

    -Name (_UID, 6)

- -

 

- -

    -Method (_CRS, 0x0, NotSerialized) {

- -

        -Name (RBUF, ResourceTemplate ()

- -

        -{

- -

                     -…

- -

        -})

- -

        -Return (RBUF)

- -

    -}

- -

}

- -

 

- -

//

- -

// -Multifunction serial bus device to support Bluetooth function

- -

//

- -

Device(BTH0)

- -

{

- -

    -// ACPI enumerate will generate a hardware ID “ACPI\ABCD_BTH0”

- -

    -Name (_HID, "ABCD_BTH0") // where “ABCD” is vendor name; 

- -

       - 

- -

    -Method(_CRS, 0x0, NotSerialized)

- -

    -{

- -

        -Name (RBUF, ResourceTemplate ()

- -

        -{

- -

        -// GPIO Descriptor

- -

        -// (optional)

- -

 

- -

        -// I2C Serial Bus Descriptor

- -

        -// (optional)

- -

 

- -

        -// UART Serial Bus Descriptor

- -

        -UARTSerialBus (

- -

      0xC0, // RTS | -CTS

- -

      LittleEndian,

- -

      DataBitsEight,

- -

      StopBitsOne,

- -

      FlowControlHardware,

- -

      115200, // -Initial Baudrate

- -

      480, // Rx FIFO -size

- -

      32, // Tx FIFO size

- -

      ParityTypeNone,

- -

      -"\\_SB.UAR1", , )

- -

        -})

- -

        -Return -(RBUF)            

- -

    -}

- -

}

- -

 

- -

6       Resources

- -

 

- -

For the latest release -of the Windows device Driver Development Kit, see http://www.microsoft.com/whdc/. -

- -

 

- -

Please see the latest -WDK release for documentation on Bluetooth and WDF.

- -

 

- -

Bus Driver Development -Based on KMDF http://msdn.microsoft.com/en-us/windows/hardware/gg463281.aspx

- -
- - - - -- cgit v1.3.1