ATWILC3000 BlueKitchen BTstack User Guide

Size: px

Start display at page:

Download "ATWILC3000 BlueKitchen BTstack User Guide"

Gwen Bond
5 years ago
Views:

1 BlueKitchen BTstack User Guide Introduction The is a single chip IEEE b/g/n RF/Baseband/Medium Access Control (MAC) link controller and Bluetooth 5.0 compliant module. This single-chip solution contains separate Bluetooth and WLAN subsystems that share a single RF section with Bluetooth/Wi-Fi coexistence handled automatically. Each subsystem has its own physical interface: WLAN control and data use Secure Digital Input Output (SDIO)/Serial Peripheral Interface (SPI), while Bluetooth is available via the UART interface. Both subsystems require separate protocol stacks. For WLAN, a TCP/IP stack with IEEE driver for the is used, while Bluetooth uses a Bluetooth stack. This document describes the use of BTstack, a third party Bluetooth Stack provided by BlueKitchen GmbH. BTstack is free for evaluation and non-commercial use. For license information, contact BlueKitchen GmbH. This document also provides a quick overview on the use of the as a BLE Peripheral. BTstack is not limited to this usage and more information can be found in the API documentation and in the BTstack manual, available at: Note: 1. The BlueKitchen BLE stack is supported in ATWILC RTOS Driver Release 4.03 and available from Advanced Software Framework (ASF) 3.42 and later. 2. For more information on BlueKitchen GmbH contact: BlueKitchen GmbH Engelstrasse Zurich Switzerland Web: contact@bluekitchen-gmbh.com 2018 Microchip Technology Inc. User Guide DS A-page 1

2 Table of Contents Introduction BLE Application Related API Advertisement Scanning HCI Event Handling GATT Server Setup LE Counter Application LE Transparent Application LE Wi-Fi Provisioning Application Wi-Fi and BLE Coexistence Application Revision History...18 The Microchip Web Site Customer Change Notification Service...19 Customer Support Microchip Devices Code Protection Feature Legal Notice...20 Trademarks Quality Management System Certified by DNV...21 Worldwide Sales and Service Microchip Technology Inc. User Guide DS A-page 2

3 BLE Application Related API 1. BLE Application Related API This chapter describes the BTstack API used for simple Bluetooth Low Energy (BLE) application development. 1.1 Advertisement The following API is used for BLE advertisement operation: gap_advertisements_set_params gap_advertisements_set_data gap_scan_response_set_data gap_advertisements_enable 1.2 Scanning The following API is used for BLE scanning operation: gap_set_scan_parameters gap_start_scan gap_stop_scan 1.3 HCI Event Handling The user needs to register the HCI Event handler for all HCI events and add it to the handler list. For example, assume a packet handler and a global variable such as: static void packet_handler(uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size); static btstack_packet_callback_registration_t hci_event_callback_registration; The packet handler can be added by the following snippet: hci_event_callback_registration.callback = &packet_handler; hci_add_event_handler(&hci_event_callback_registration); 2018 Microchip Technology Inc. User Guide DS A-page 3

4 GATT Server Setup 2. GATT Server Setup To implement a LE Peripheral and to exchange data, a GATT profile containing all GATT services with their characteristics has to be defined. BTstack uses a compact read-only representation of the GATT profile that can be stored in Flash to minimize the RAM requirements. As all the GATT requests are implemented via the ATT protocol in Bluetooth, the GATT services and characteristics are also stored as a list of equivalent ATT Attributes. For this, the tool compile_gatt.py is available at: The following is the format of compile_gatt.py: $ compile_gatt.py input.gatt output.h A few examples can be found in the ASF directory path at: thirdparty\wireless\bt_wilc_sdk\bt_src\ble\gatt-service. For more details about the GATT Server, refer to the manual available at: Server Alternatively, the ATT Database can be created at runtime in RAM using the att_db_util helper functions. Here is a snippet for the GATT definition of the GATT GAP Service that contains the device name: PRIMARY_SERVICE, GAP_SERVICE CHARACTERISTIC, GAP_DEVICE_NAME, READ, LE Counter The binary representation of ATT attribute is structured as follows: Attribute size in byte Flags Handle UUID Value (16 bit) (16 bit) (16 bit) (16/128 bit) (.) The compile_gatt.py tool then creates the following representation: // 0x0001 PRIMARY_SERVICE-GAP_SERVICE 0x0a, 0x00, 0x02, 0x00, 0x01, 0x00, 0x00, 0x28, 0x00, 0x18, // 0x0002 CHARACTERISTIC-GAP_DEVICE_NAME-READ 0x0d, 0x00, 0x02, 0x00, 0x02, 0x00, 0x03, 0x28, 0x02, 0x03, 0x00, 0x00, 0x2a, // 0x0003 VALUE-GAP_DEVICE_NAME-READ-'LE Counter' // READ_ANYBODY 0x12, 0x00, 0x02, 0x00, 0x03, 0x00, 0x00, 0x2a, 0x4c, 0x45, 0x20, 0x43, 0x6f, 0x75, 0x6e, 0x74, 0x65, 0x72, With this, the ATT server can be set up using: * att_server_init * att_server_register_packet_handler 2018 Microchip Technology Inc. User Guide DS A-page 4

5 3. This chapter describes the functional overview of all the applications that are pre-defined in the Atmel Studio. For information about commercial licensing options contact: 3.1 LE Counter Application The LE Counter examples demonstrate how to specify a minimal GATT database with a custom GATT service and custom characteristic that sends periodic notifications Database Details The following table provides the database details for LE Counter application. Table 3-1. Database Details for LE Counter Application Service Battery Custom UUID 180F 0000FF F9B34FB Running the Demo Perform the following steps to run the demo. 1. Open any Terminal Application (TeraTerm, for example). Select the COM Port enumerated on the PC and set the following parameters: Baudrate Parity None One Stop bit One Start bit No Hardware Handshake 2. Press the Reset button on the ATSAMV71 Xplained Ultra board. 3. The device is in Advertising mode. 4. Open the Microchip Bluetooth Data application in the itunes or Google Play Store and click Bluetooth Smart on the application dashboard to scan for the peripheral devices, as illustrated in the following figure Microchip Technology Inc. User Guide DS A-page 5

6 Figure 3-1. Dashboard of Microchip Bluetooth Data Application 5. The scanning page is displayed. Click START SCAN to display the list of discoverable devices. The device name LE Counter is displayed among the list of scanned devices. Figure 3-2. Scanning for Devices 2018 Microchip Technology Inc. User Guide DS A-page 6

service list page. Figure 3-3. Display of Services Supported by the Application 8.

7 6. Select the LE Counter application name for connection. 7. Once the device is connected, a list of supported services for the device is displayed in the service list page. Figure 3-3. Display of Services Supported by the Application 8. From the service list page, click Battery Service to display the Battery simulation page Microchip Technology Inc. User Guide DS A-page 7

Custom Service related information. Figure 3-5. Generic Information Page 10.

8 Figure 3-4. Battery Simulation Page 9. From the service list page, click Unknown Service or Generic Information to access the Custom Service related information. Figure 3-5. Generic Information Page 10. Click Characteristics under Unknown Service to display the characteristic information Microchip Technology Inc. User Guide DS A-page 8

9 Figure 3-6. Characteristic Information Page 11. Click Read to read the characteristic information. 12. Click Notify to trigger continuous notification incremental counter value display on the console log. Figure 3-7. Incremental Counter Value Console Log 3.2 LE Transparent Application The LE Transparent application demonstrates how to perform data exchange between the client and the server Database Details The following table provides the database details for LE Transparent application Microchip Technology Inc. User Guide DS A-page 9

Table 3-2. Database Details for LE Transparent Application Service Transparent UUID 49535343-FE7D-4AE5-8FA9-9FAFD205E455 3.2.2 Running the Demo Perform the following steps to run the demo. 1.

Select the COM Port enumerated on the PC and set the following parameters: Baudrate 115200 Parity None One Stop bit One Start bit No Hardware Handshake 2.

10 Table 3-2. Database Details for LE Transparent Application Service Transparent UUID FE7D-4AE5-8FA9-9FAFD205E Running the Demo Perform the following steps to run the demo. 1. Open any Terminal Application (TeraTerm, for example). Select the COM Port enumerated on the PC and set the following parameters: Baudrate Parity None One Stop bit One Start bit No Hardware Handshake 2. Press the Reset button on ATSAMV71 Xplained Ultra board. 3. The device is in Advertising mode. 4. Open the Microchip Bluetooth Data application and click Bluetooth Smart on the application dashboard to scan for the peripheral devices, as illustrated in Figure The scanning page is displayed. Click Scan (To scan devices around you) and it opens another scan page with the SCAN tab. Click SCAN to display the list of discoverable devices. The device name LE-TRANSPARENT is displayed among the list of scanned devices. Figure 3-8. Scanning for Devices 2018 Microchip Technology Inc. User Guide DS A-page 10

11 6. Select the LE-Transparent application name for connection. 7. Once the device is connected, LE-TRANSPARENT page is displayed and the user needs to click the Transparent (Transfer data to device) tab for Transparent service functionality. Figure 3-9. Display of Services Supported by the Application 8. In the Transparent service functionality, enter any text message in the text box and click SEND to send the data to another device. By default, the RAW tab is enabled for sending the data. The user can select the Timer tab to send the data in an interval. Figure LE-Transparent Page 3.3 LE Wi-Fi Provisioning Application The LE Wi-Fi Provisioning application demonstrates how to provision Wi-Fi via BLE using the Wi-Fi BLE module Database Details The following table provides the database details for LE Provisioning application Microchip Technology Inc. User Guide DS A-page 11

Table 3-3. Database Details for LE Provisioning Application Service Provisioning service Scanning service UUID 77880001-D229-11E4-8689-0002A5D5C51B FB8C0001-D224-11E4-85A1-0002A5D5C51B 3.3.2 Running the Demo Perform the following steps to run the demo.

12 Table 3-3. Database Details for LE Provisioning Application Service Provisioning service Scanning service UUID D229-11E A5D5C51B FB8C0001-D224-11E4-85A1-0002A5D5C51B Running the Demo Perform the following steps to run the demo. 1. Open any Terminal Application (TeraTerm, for example). Select the COM Port enumerated on the PC and set the following parameters: Baudrate Parity None One Stop bit One Start bit No Hardware Handshake 2. Press the Reset button on ATSAMV71 Xplained Ultra board. 3. The device is in Advertising mode. 4. Open the Microchip Bluetooth Data application and click BLE Provisioner on the application dashboard to scan for the peripheral devices, as illustrated in the following figure. Figure Dashboard of Microchip Bluetooth Data Application 5. The device name MCHP_WIFI is displayed among the list of scanned devices Microchip Technology Inc. User Guide DS A-page 12

Figure 3-12. Scan Page 6. Select MCHP_WIFI for BLE connection. Figure 3-13.

When scanning for the AP list, the Scan button is disabled and it will be enabled

13 Figure Scan Page 6. Select MCHP_WIFI for BLE connection. Figure Provisioning Connection Page 7. Select Scan to scan for the AP list. When scanning for the AP list, the Scan button is disabled and it will be enabled again once the application receives the AP list Microchip Technology Inc. User Guide DS A-page 13

Figure 3-14. Scanning in Process for Provisioning 8. Once the AP list is displayed, select the AP from the scanned list.

Once the user selects the AP and provides the information (Network Key), the Provision tab is displayed to start the

14 Figure Scanning in Process for Provisioning 8. Once the AP list is displayed, select the AP from the scanned list. Based on security type used, enter the information in the Enter Network Key section. Figure Scan AP List 9. Once the user selects the AP and provides the information (Network Key), the Provision tab is displayed to start the connection procedure. Click Provision for starting the connection Microchip Technology Inc. User Guide DS A-page 14

Figure 3-16. Provision Page 10. A notification Provisioning Complete pop-up is displayed once the Wi-Fi connection is established.

4 Wi-Fi and BLE Coexistence Application The coexistence application demonstrates concurrent operation of Wi-Fi in Station (STA) and AP mode along with an active

15 Figure Provision Page 10. A notification Provisioning Complete pop-up is displayed once the Wi-Fi connection is established. Click OK, and the BLE connection is disconnected and Wi-Fi connection remains active. Figure Provision Complete Page 3.4 Wi-Fi and BLE Coexistence Application The coexistence application demonstrates concurrent operation of Wi-Fi in Station (STA) and AP mode along with an active BLE connection. The BLE connection advertises an LE Counter service. The LE Counter examples demonstrate how to specify a minimal GATT database with a custom GATT service 2018 Microchip Technology Inc. User Guide DS A-page 15

and custom characteristic that sends periodic notifications. The value in the notification is updated in the AP web server as well as the Microchip Bluetooth Data application. 3.4.

16 and custom characteristic that sends periodic notifications. The value in the notification is updated in the AP web server as well as the Microchip Bluetooth Data application Running the Demo Perform the following steps to run the demo. 1. Load the Coexistence application on the after entering the details of AP with internet connection in sta.h. 2. Open any Terminal Application (TeraTerm, for example). Select the COM Port enumerated on the PC and set the following parameters: Baudrate Parity None One Stop bit One Start bit No Hardware Handshake 3. Press the Reset button on ATSAMV71 Xplained Ultra board. 4. Enter in the web browser to connect to the web server hosted on the. The battery counter is updated as shown in the following figure. Figure Web server 5. The device is in Advertising mode. 6. Open the Microchip Bluetooth Data application and click BLE Smart on the application dashboard to scan for the peripheral devices, as illustrated in Figure Microchip Technology Inc. User Guide DS A-page 16

17 7. The scanning page is displayed. Click START SCAN to display the list of discoverable devices. The device name LE Counter is displayed among the list of scanned devices, as illustrated in Figure Select LE Counter application name for connection. 9. Once the device connected, list of supported services for the device is displayed in service list page, see Figure From the service list page, click Battery Service to display the battery simulation page, see Figure The two counters in the web page and the Microchip Bluetooth application are in sync demonstrating the coexistence functionality Microchip Technology Inc. User Guide DS A-page 17

18 Revision History 4. Revision History Revision Date Section Description A 09/2018 Document Initial Release 2018 Microchip Technology Inc. User Guide DS A-page 18

19 The Microchip Web Site Microchip provides online support via our web site at This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: Product Support Data sheets and errata, application notes and sample programs, design resources, user s guides and hardware support documents, latest software releases and archived software General Technical Support Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing Business of Microchip Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives Customer Change Notification Service Microchip s customer notification service helps keep customers current on Microchip products. Subscribers will receive notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at Under Support, click on Customer Change Notification and follow the registration instructions. Customer Support Users of Microchip products can receive assistance through several channels: Distributor or Representative Local Sales Office Field Application Engineer (FAE) Technical Support Customers should contact their distributor, representative or Field Application Engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: Microchip Devices Code Protection Feature Note the following details of the code protection feature on Microchip devices: Microchip products meet the specification contained in their particular Microchip Data Sheet. Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. Microchip is willing to work with the customer who is concerned about the integrity of their code Microchip Technology Inc. User Guide DS A-page 19

20 Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as unbreakable. Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Legal Notice Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer s risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights unless otherwise stated. Trademarks The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BitCloud, chipkit, chipkit logo, CryptoMemory, CryptoRF, dspic, FlashFlex, flexpwr, Heldo, JukeBlox, KeeLoq, Kleer, LANCheck, LINK MD, maxstylus, maxtouch, MediaLB, megaavr, MOST, MOST logo, MPLAB, OptoLyzer, PIC, picopower, PICSTART, PIC32 logo, Prochip Designer, QTouch, SAM-BA, SpyNIC, SST, SST Logo, SuperFlash, tinyavr, UNI/O, and XMEGA are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, mtouch, Precision Edge, and Quiet-Wire are registered trademarks of Microchip Technology Incorporated in the U.S.A. Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dspicdem, dspicdem.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, membrain, Mindi, MiWi, motorbench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies Microchip Technology Inc. User Guide DS A-page 20

21 2018, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: Quality Management System Certified by DNV ISO/TS Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company s quality system processes and procedures are for its PIC MCUs and dspic DSCs, KEELOQ code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip s quality system for the design and manufacture of development systems is ISO 9001:2000 certified Microchip Technology Inc. User Guide DS A-page 21

22 Worldwide Sales and Service AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE Corporate Office 2355 West Chandler Blvd. Chandler, AZ Tel: Fax: Technical Support: support Web Address: Atlanta Duluth, GA Tel: Fax: Austin, TX Tel: Boston Westborough, MA Tel: Fax: Chicago Itasca, IL Tel: Fax: Dallas Addison, TX Tel: Fax: Detroit Novi, MI Tel: Houston, TX Tel: Indianapolis Noblesville, IN Tel: Fax: Tel: Los Angeles Mission Viejo, CA Tel: Fax: Tel: Raleigh, NC Tel: New York, NY Tel: San Jose, CA Tel: Tel: Canada - Toronto Tel: Fax: Australia - Sydney Tel: China - Beijing Tel: China - Chengdu Tel: China - Chongqing Tel: China - Dongguan Tel: China - Guangzhou Tel: China - Hangzhou Tel: China - Hong Kong SAR Tel: China - Nanjing Tel: China - Qingdao Tel: China - Shanghai Tel: China - Shenyang Tel: China - Shenzhen Tel: China - Suzhou Tel: China - Wuhan Tel: China - Xian Tel: China - Xiamen Tel: China - Zhuhai Tel: India - Bangalore Tel: India - New Delhi Tel: India - Pune Tel: Japan - Osaka Tel: Japan - Tokyo Tel: Korea - Daegu Tel: Korea - Seoul Tel: Malaysia - Kuala Lumpur Tel: Malaysia - Penang Tel: Philippines - Manila Tel: Singapore Tel: Taiwan - Hsin Chu Tel: Taiwan - Kaohsiung Tel: Taiwan - Taipei Tel: Thailand - Bangkok Tel: Vietnam - Ho Chi Minh Tel: Austria - Wels Tel: Fax: Denmark - Copenhagen Tel: Fax: Finland - Espoo Tel: France - Paris Tel: Fax: Germany - Garching Tel: Germany - Haan Tel: Germany - Heilbronn Tel: Germany - Karlsruhe Tel: Germany - Munich Tel: Fax: Germany - Rosenheim Tel: Israel - Ra anana Tel: Italy - Milan Tel: Fax: Italy - Padova Tel: Netherlands - Drunen Tel: Fax: Norway - Trondheim Tel: Poland - Warsaw Tel: Romania - Bucharest Tel: Spain - Madrid Tel: Fax: Sweden - Gothenberg Tel: Sweden - Stockholm Tel: UK - Wokingham Tel: Fax: Microchip Technology Inc. User Guide DS A-page 22

PL360G55CB-EK Quick Start Guide

PL360G55CB-EK Quick Start Guide Quick Start Guide Overview is an evaluation kit for the PL360 modem, a multi-protocol device to implement standard and customized PLC solutions. includes a SAMG55 ARM Cortex -M4 microcontroller, which