User's Guide

ManualsBrandsCHAMPION ManualsElectronicsBluetooth Module

Table Of Contents

EZ-Serial BLE Firmware Platform User Guide, Doc. No. 002-11259 Rev. *E 3

Contents

1. Introduction .................................................................................................................................................................... 5

1.1 How to Use This Guide .......................................................................................................................................... 5

1.2 Block Diagram ....................................................................................................................................................... 6

1.3 Functional Overview .............................................................................................................................................. 7

1.4 Cypress BLE Device Support ................................................................................................................................ 8

2. Getting Started ............................................................................................................................................................... 9

2.1 Prerequisites.......................................................................................................................................................... 9

2.2 Factory Default Behavior ....................................................................................................................................... 9

2.3 Connecting a Host Device ................................................................................................................................... 10

2.4 Communicating with a Host Device ..................................................................................................................... 13

2.5 Configuration Settings, Storage, and Protection .................................................................................................. 25

2.6 Where to Find Related Material ........................................................................................................................... 27

3. Operational Examples ................................................................................................................................................. 28

3.1 System Setup Examples ..................................................................................................................................... 28

3.2 Cable Replacement Examples with CYSPP ........................................................................................................ 37

3.3 Remote Control Examples with CYCommand ..................................................................................................... 41

3.4 GAP Peripheral Examples ................................................................................................................................... 43

3.5 GAP Central Examples ........................................................................................................................................ 47

3.6 GATT Server Examples ....................................................................................................................................... 50

3.7 GATT Client Examples ........................................................................................................................................ 57

3.8 Security and Encryption Examples ...................................................................................................................... 60

3.9 Beacon Examples ................................................................................................................................................ 66

3.10 Performance Testing Examples........................................................................................................................... 67

3.11 Device Firmware Update Examples .................................................................................................................... 71

4. Application Design Examples .................................................................................................................................... 73

4.1 Smart MCU Host with 4-Wire UART and Full GPIO Connections ....................................................................... 73

4.2 Dumb Terminal Host with CYSPP and Simple GPIO State Indication ................................................................. 74

4.3 Module-Only Application with Beacon Functionality ............................................................................................ 75

5. Host API Library .......................................................................................................................................................... 76

5.1 Host API Library Overview................................................................................................................................... 76

5.2 Implementing a Project Using the Host API Library ............................................................................................. 77

5.3 Porting the Host API Library to Different Platforms .............................................................................................. 80

5.4 Using the API Definition JSON File to Create a Custom Library .......................................................................... 81

6. Troubleshooting .......................................................................................................................................................... 82

6.1 UART Communication Issues.............................................................................................................................. 82

Summary of content (241 pages)

PAGE 1
Contents 1. Introduction.................................................................................................................................................................... 5 1.1 1.2 1.3 1.4 2. Getting Started............................................................................................................................................................... 9 2.1 2.2 2.3 2.4 2.5 2.6 3. Smart MCU Host with 4-Wire UART and Full GPIO Connections ..................................
PAGE 2
Contents 6.2 6.3 7. API Protocol Reference ............................................................................................................................................... 85 7.1 7.2 7.3 7.4 7.5 8. GPIO Pin Map for Supported Modules .............................................................................................................. 218 GPIO Pin Functionality ..........................................................................................................................
PAGE 3
1. Introduction < This document provides a complete guide to the EZ-Serial platform on EZ-BLE modules.
PAGE 4
Introduction Find at least one design example from Chapter 4 (Application Design Examples) that is similar to the type of system you intend to use an EZ-Serial-based EZ-BLE module with, especially noting the functional capabilities provided by the configuration and GPIO connections. If you are combining EZ-Serial with an external host microcontroller, read through Chapter 5 (Host API Library) to understand how the external MCU will need to communicate with the module.
PAGE 5
Introduction 1.3 Functional Overview EZ-Serial provides an easy way to access the most commonly needed hardware and communication features in BLEbased applications. To accomplish this, the firmware implements an intuitive API protocol over the UART interface and exposes a number of status and control signals through the module’s GPIO pins. 1.3.1 BLE Communication Features The EZ-Serial platform has the following BLE-related features: • Bluetooth 4.
PAGE 6
Introduction 1.4 Cypress BLE Device Support As of the current release (v1.1.1 build 26), EZ-Serial firmware images exist for the following devices: Table 1-1.
PAGE 7
2. Getting Started EZ-Serial allows for rapid integration of BLE wireless communication into your designs. Its support for multiple API protocol formats enables easy testing of functions by typing commands into a serial terminal from your computer. Once the intended functionality is confirmed, the exact same behavior can be achieved with a compact binary protocol on a host microcontroller. 2.
PAGE 8
Getting Started This text-mode string of data indicates: • @E – an event has occurred • 003B – there are 59 bytes (0x3B) of content to follow • BOOT – the event which occurred is the BOOT event • E=0101011A – the EZ-Serial application version is 1.1.1 build 26 (0x1A) • S=03030035 – the BLE stack component version is 3.3.0 build 53 (0x35) • P=0103 – the protocol version is 1.3 • H=05 – the hardware platform is CYBLE-2120XX-X0 (e.g.
PAGE 9
Getting Started Figure 2-1. Virtual Serial Port from BLE Pioneer Kit Note: COM11 is shown here, but your port number may be different. You can then use this serial port in any compatible application on your PC, such as Tera Term, Realterm, or PuTTY. NOTE: The PSoC 5LP microcontroller on the BLE Pioneer Kit board will only provide the expected USB-to-UART bridge functionality if it is running the default KitProg firmware that Cypress ships on the evaluation board.
PAGE 10
Getting Started prevents unintentional communication lockouts. Refer to Section 2.5.3 (Protected Configuration Settings) for details concerning protected settings. If you experience any problems communicating over the serial interface, refer to Chapter 6 (Troubleshooting) for solutions to common issues. 2.3.3 Connecting GPIO Pins EZ-Serial also supports GPIO connections for status signals (output) and control signals (input).
PAGE 11
Getting Started unexpected behavior with some external devices that have equal or stronger pulls in input mode, you can change the drive mode of special-function output pins to use strong drive instead with the gpio_set_function (SIOF, ID=9/3) API command. Only the UART_TX pin is strongly driven by default, because it cannot function properly with any other configuration. For more details on GPIO functionality, please refer to Chapter 8 (GPIO Reference). 2.
PAGE 12
Getting Started • Events always begin with “@E,” followed by a 16-bit “length” value similar to responses described above. • Responses and events are terminated with carriage return (0x0D) and line feed (0x0A) bytes. • Lines beginning with a “#” symbol are treated as comments and discarded by the parser. 2.4.1.2 Text Mode API Command Categories There are four main categories of commands in text mode: ACTION, SET, GET, and PROFILE.
PAGE 13
Getting Started Figure 2-2. Text Command Mode Session with PuTTY Table 2-3 describes the various protocol methods shown in the figure above. Table 2-3. Text Mode Communication Example Direction Content Detail ←RX @E,003B,BOOT,E=0101011A,S=03030035, P=0103,H=05,C=01,A=00A050421A63 system_boot (BOOT, ID=2/1) API event received: app = 1.1.1 build 26 stack = 3.3.0 build 53 protocol = 1.
PAGE 14
Getting Started 2.4.2 Using the API Protocol in Binary Mode EZ-Serial also implements a binary-format API protocol that allows the same control of the platform using compact binary commands, responses, and events. This mode is typically preferable when controlling the EZ-Serial-based module from an external microcontroller. The binary byte stream is much easier to parse and generate from MCU application code than human-readable text strings.
PAGE 15
Getting Started • The binary command header includes a single bit in the first byte which performs the same duty as the ‘$’ character in text mode, to cause changed settings to be written to flash immediately instead of just RAM. 2.4.2.2 Binary Mode API Example The easiest way to use binary command mode is with a host MCU or other application that has a complete parser and generator implementation available, such as the host API library provided by Cypress and discussed in Chapter 5 (Host API Library).
PAGE 16
Getting Started Direction Content Detail ←RX C0 08 02 01 00 00 03 00 00 00 47 42 F0 system_ping (/PING, ID=2/1) API response received: result = 0 (success) runtime = 3 seconds fraction = 16967/32768 TX→ C0 00 04 10 6D (not visible) gap_get_device_name (GDN, ID=4/16) API command sent to get the configured device name ←RX C0 5A 20 33 gap_get_device_name (GDN, ID=4/16) API response received: result = 0 (success) name = “EZ-Serial 42:1A:63” ←RX 80 0F 04 05 04 50 16 42 50 A0 00 00 06 00 00 00 64 00
PAGE 17
Getting Started • Binary is more efficient for MCU-based communication, while text mode is easier for manual entry in a terminal. • Binary commands are never echoed back to the host, while text mode commands are (by default). 2.4.4 API Protocol Format Auto-Detection EZ-Serial uses text mode for API protocol communication by default, but you can change this setting with the protocol_set_parse_mode (SPPM, ID=1/1) API command.
PAGE 18
Getting Started 2.4.5.2 Sending and Receiving Data in CYSPP Data Mode Once you have started CYSPP mode, the EZ-Serial platform will take care of the rest of the connection process and data pipe construction on the module side.
PAGE 19
Getting Started 2.4.5.4 Customizing CYSPP Behavior for Specific Needs While the default behavior is suitable in many cases, there are configuration settings that allow a great deal of control over this behavior. The following list describes which options can be changed, and how to do so: • CYSPP mode uses the system’s configured UART host transport settings for sending and receiving serial data. To change these settings, use the system_set_uart_parameters (STU, ID=2/25) API command.
PAGE 20
Getting Started WARNING: EZ-Serial will only incorporate the CYSPP peripheral connection key into the advertising packet if you have not enable user-defined advertisement content. If you have configured user-defined advertisement content instead as described in Section 3.4.3 (How to Customize Advertisement and Scan Response Data), then changing this value will have no effect.
PAGE 21
Getting Started 2.4.5.8 CYSPP Configuration and Pin States Table 2-8 below describes the relationship between the state of the CYSPP pin and the CYSPP firmware configuration managed with the p_cyspp_set_parameters (.CYSPPSP, ID=10/3) API command. Note these two key behaviors concerning hardware control vs. software control: • Asserting the CYSPP pin externally will always trigger automatic CYSPP operation in the configured role (or the role dictated by externally driving the CP_ROLE pin).
PAGE 22
Getting Started 2.4.5.9 CYSPP State Machine Figure 2-4 describes the way EZ-Serial manages CYSPP operation, depending on firmware configuration and the logic states of the CYSPP and CP_ROLE pins. Figure 2-4.
PAGE 23
Getting Started 2.5 Configuration Settings, Storage, and Protection The EZ-Serial platform provides methods to customize its many built-in functions. It’s important to understand how these settings are stored and changed in different contexts to avoid unexpected behavior. 2.5.1 Factory, Boot, Runtime, and Automatic Settings EZ-Serial implements four different “layers” of configuration data, each of which serves a unique purpose. Table 2-9 below describes each type of configuration storage in detail.
PAGE 24
Getting Started Layer Details Automatic (RAM) Description: Automatic settings are set by the firmware based on detected external behavior, and EZ-Serial uses these values to augment the settings in the runtime configuration block.
PAGE 25
Getting Started 2.6 Where to Find Related Material This guide refers to firmware images and example source code files that must be accessed separately from this document. 2.6.1 Latest EZ-Serial Firmware Image You can find the latest available EZ-Serial firmware image files on Cypress’s website: http://www.cypress.
PAGE 26
3. Operational Examples EZ-Serial provides a great platform on which to build a wide variety of BLE applications. The sections below describe many common operations that you can experiment with or combine together to create the behavior needed for your application. 3.1 System Setup Examples These examples demonstrate basic platform behavior and configuration of the system.
PAGE 27
Operational Examples Text Code A Text Data “00A050421A63” Binary Data 63 1A 42 50 A0 00 Details Interpretation MAC address 00:A0:50:42:1A:63 3.1.1.2 Getting Version Details On Demand Use the system_query_firmware_version (/QFV, ID=2/6) API command to request version details at any time. The response to this command contains the same initial information in the system_boot (BOOT, ID=2/1) API event, but it does not include the boot cause or the module’s Bluetooth MAC address.
PAGE 28
Operational Examples rates. Refer to Section 2.3.2 (Connecting the Serial Interface) for detailed instructions and specific requirements for proper functionality when connecting an external UART device to the BLE Pioneer Kit. WARNING: Selecting a baud rate below 9600 and using API protocol communication can result in a situation where EZ-Serial generates API response and event packets faster than the UART interface can transmit them to the host.
PAGE 29
Operational Examples The device appearance value is a 16-bit field made up of a 10-bit and 6-bit subfield. Allowed values are defined by the Bluetooth SIG and can be found at developer.bluetooth.org. Changes made to the device name and appearance values take effect immediately.
PAGE 30
Operational Examples 3.1.5 How to Manage Sleep States EZ-Serial manages transitions between active CPU and sleep states automatically. It chooses the mode requiring the lowest safe power consumption according to the current operational state and configuration, including transitioning into sleep mode between BLE radio events (advertising, scanning, or while connected). Table 3-4 provides a high-level summary of the four power states used by the platform. Table 3-4.
PAGE 31
Operational Examples 3. Select the lowest value (0 = no sleep, 1 = normal sleep, 2 = deep sleep) among the following: a. The system sleep level configured with system_set_sleep_parameters (SSLP, ID=2/19) API command. b. The CYSPP-specific sleep level configured with the p_cyspp_set_parameters (.CYSPPSP, ID=10/3) API command, if the CYSPP data pipe is open (connected and in CYSPP data mode). c.
PAGE 32
Operational Examples Example 1: Limit CYSPP-specific sleep level to normal sleep Direction Content Effect TX→ .CYSPPSP,S=1 Set new CYSPP sleep level to “normal sleep” ←RX @R,000E,.CYSPPSP,0000 Response indicates success 3.1.5.3 Preventing Sleep with the LP_MODE Pin Assert (LOW) the LP_MODE control pin to prevent the module from sleeping under any circumstances other than a forced shutdown via the ATEN_SHDN pin.
PAGE 33
Operational Examples Table 3-5. Wake-on-RX Bit Misalignment from Deep Sleep at 115200 Baud Host transmits 0x2F (0b00101111 in LSB order) Start 1 1 1 1 5-bit misalignment CPU wakes Host idle (HIGH) 0 1 0 0 Stop Start 1 0 0 1 Wait for start 5-bit misalignment 1 1 1 1 Stop Module receives 0xF9 (0b11111001 in LSB order) While the above case describes one possible outcome, the exact nature of received data corruption depends on the transmitted bytes, baud rate, and other UART parameters.
PAGE 34
Operational Examples Figure 3-3. Deep Sleep Wake-on-RX With Dummy Byte at 115200 Baud, 8/N/1 In the example shown in Figure 3-3, the CPU has fully transitioned to active mode before the host begins sending the forward slash (‘/’) character, allowing correct data reception into the module. WARNING: Although the API parser will safely ignore as many 0x00 dummy bytes as the host transmits even if the CPU is already awake, CYSPP data mode does not have this same guarantee.
PAGE 35
Operational Examples 5. Host CPU wakes up 6. Host sets the module CTS pin LOW to allow UART transmission 7. Module transmits data to the host for processing 3.1.6 How to Perform a Factory Reset You can perform a factory reset using either GPIO signals or an API command. EZ-Serial will generate the system_factory_reset_complete (RFAC, ID=2/3) API event immediately after erasing all settings, and before performing the final module reset to boot to the factory default state.
PAGE 36
Operational Examples 3.2.1 How to Get Started in CYSPP Mode with Zero Custom Configuration The factory default configuration enables the CYSPP profile in “auto-start” mode. With this configuration, the module begins advertising or scanning as soon as it has power, depending on the state of the CP_ROLE pin. If you are using the BLE Pioneer Kit for evaluation, perform the following steps: 1. Open the kit-provided COM port in your terminal software of choice, being sure to use the correct port settings.
PAGE 37
Operational Examples 3.2.1.1 How to Start CYSPP Out of the Box in Peripheral Mode EZ-Serial’s factory default configuration automatically starts CYSPP operation in the peripheral role after booting. To establish a CYSPP data pipe, simply scan and connect from a remote device, then subscribe to RX flow control (optional) and the desired acknowledged or unacknowledged data characteristic as described in Section 2.4.5.2 (Sending and Receiving Data in CYSPP Data Mode).
PAGE 38
Operational Examples Direction Content Effect ←RX @E,0045,DR,C=04,H=000E,R=0000,T=0000,P=00, U=01A10C2000089A9EE21115A133333365 GATT discovery result (CYSPP ack’d data) ←RX @E,0029,DR,C=04,H=000F,R=0000,T=2902,P=00,U=0229 GATT discovery result (configuration descriptor) ←RX @E,0029,DR,C=04,H=0010,R=0000,T=2803,P=00,U=0328 GATT discovery result (characteristic declaration) ←RX @E,0045,DR,C=04,H=0011,R=0000,T=0000,P=00, U=02A10C2000089A9EE21115A133333365 GATT discovery result (CYSPP unack’d dat
PAGE 39
Operational Examples 3.3 Remote Control Examples with CYCommand CYCommand provides a way to control EZ-Serial from a remote GATT client, using the same API protocol exposed over the wired serial interface. This allows use cases like remote provisioning during manufacturing, and GPIO control. You can optionally require a password and/or a specific level of encryption and bonding before a remote peer can control the module.
PAGE 40
Operational Examples Figure 3-5. CYCommand GATT Structure shown in CySmart Application To use CYCommand from a client, perform the steps outlined below. These instructions assume that you have already enabled CYCommand and placed the module into a connectable advertising state. This is the factory default state after applying power to the module. NOTE: While CYCommand data mode is active, you cannot send any API commands over the wired serial interface.
PAGE 41
Operational Examples 3.4 GAP Peripheral Examples GAP peripheral operation is one of the most common use cases for BLE designs, since it is usually the simplest way to communicate with a smartphone operating as a central device.
PAGE 42
Operational Examples Example 2: Start advertising with custom parameters Direction Content Effect TX→ /A,M=2,T=0,I=A0,C=6,F=0,O=1E Begin advertising with custom arguments ←RX @R,0008,/A,0000 Response indicates success ←RX @E,000E,ASC,S=01,R=00 Event indicates advertising state changed to “active” 3.4.2 How to Stop Advertising as Peripheral Device To explicitly stop advertising, use the gap_stop_adv (/AX, ID=4/9) API command, or open a connection to the module from a remote BLE central device.
PAGE 43
Operational Examples Table 3-7.
PAGE 44
Operational Examples Example 1: Set custom advertisement and scan response data Direction Content Effect TX→ SAP,F=2 Enable user-defined advertisement and scan response content ←RX @R,0009,SAP,0000 Response indicates success TX→ SAD,D=020106060209180D18 Set new advertisement content (RAM only), Flags and 16-bit UUID fields ←RX @R,0009,SAD,0000 Response indicates success TX→ SSRD,D=0708576964676574 Set new scan response content (RAM only), Complete local name field ←RX @R,000A,SSRD,0000
PAGE 45
Operational Examples 3.5 GAP Central Examples Running as a GAP central allows you to scan for and connect to remote peripheral devices. You can also operate as a GAP observer by scanning without any subsequent connection attempts. For further discussion of various link-layer, GAP, and GATT roles, refer to the material at the beginning of Section 3.4 (GAP Peripheral Examples). 3.5.1 How to Scan for Peripheral Devices Use the gap_start_scan (/S, ID=4/10) API command to begin scanning for devices.
PAGE 46
Operational Examples Example 2: Start 5-second active scan with duplicate filtering enabled Direction Content Effect TX→ /S,M=2,A=1,D=1,O=5 Begin “observation” scanning, active mode, 5-second timeout, duplicate filter enabled ←RX @R,0008,/S,0000 Response indicates success ←RX @E,000E,SSC,S=01,R=00 Event indicates scanning state has changed to “active” due to user request ←RX @E,0052,S,R=00,A=00A050E3835E,T=00,S=D1,B=00 D=0201061107CA366D7D5BCC0288B14DE541D9FF652F Event indicates scan result f
PAGE 47
Operational Examples 5. Connection is fully established The API command used to initiate a connection includes arguments for scan parameters, because scanning is the first operation that the stack must perform on the GAP central device during a connection process.
PAGE 48
Operational Examples 3.6 GATT Server Examples BLE data transfer operations between two connected devices most often occur through the GATT layer, with a server on one side and a client on the other side. The GATT server makes use of a pre-defined attribute structure, which the client may remotely discover and use as needed.
PAGE 49
Operational Examples Table 3-10.
PAGE 50
Operational Examples • • • o Write permissions = 0x00, to prevent attempted changes o Characteristic properties = Characteristic value attributes (type = 0x0000) o Read permissions = o Write permissions = o Characteristic properties = Characteristic user description attributes (type = 0x2901) o Read permissions = 0x01, to allow reading description o Write permissions = 0x00, to pre
PAGE 51
Operational Examples 3.6.2.1 Discovering Local GATT Services Use the gatts_discover_services (/DLS, ID=5/6) API command to obtain a list of services in the local GATT database.
PAGE 52
Operational Examples Direction Content Effect ←RX @E,0024,DL,H=0017,R=0018,T=2803,P=28,U=0328 UUID 0x2803 (Characteristic), decl=23, value handle=24, perm=0x28 ←RX @E,0040,DL,H=0018,R=0000,T=0000,P=28, U=01A20C2000089A9EE21115A133333365 UUID 0x6533…A201 (CYCommand Challenge), handle=24, perm=0x28 ←RX @E,0024,DL,H=0019,R=0000,T=2902,P=0A,U=0229 UUID 0x2902 (CCCD), handle=25, perm=0x0A ←RX @E,0024,DL,H=001A,R=001B,T=2803,P=28,U=0328 UUID 0x2803 (Characteristic), decl=26, value handle=27, perm=0
PAGE 53
Operational Examples Example 1: Write “ABCD” at beginning of local Device Name characteristic Direction Content Effect TX→ /WLH,H=3,D=41424344 Write “ABCD” (hex) into attribute with handle = 3 ←RX @R,000A,/WLH,0000 Response indicates success TX→ /RLH,H=3 Read attribute with handle = 3 to verify ←RX @R,0031,/RLH,0000,D=41424344 Response indicates success, data shows expected value 3.6.
PAGE 54
Operational Examples NOTE: Indicating data to a client requires an active connection. Example 1: Indicate a start/end handle range to a client through the Service Changed characteristic Direction Content Effect TX→ /IH,H=A,D=1D002500 Write 1D002500 via attribute with handle = 10 (0x0A) ←RX @R,0009,/IH,0000 Response indicates success ←RX @E,000F,IC,C=04,H=0009 Event indicates client has confirmed receipt of data 3.6.
PAGE 55
Operational Examples 3.7 GATT Client Examples EZ-Serial provides GATT client operational support through a variety of API methods. All methods described in the sections below require an active connection to a remote peer device, and will generate an error result if attempted without one. 3.7.1 How to Discover a Remote Server’s GATT Structure EZ-Serial’s remote GATT discovery methods function the same as the local discovery methods, with the addition of a connection handle in the discovery result output.
PAGE 56
Operational Examples Direction Content Effect ←RX @E,0029,DR,C=04,H=0004,R=0005,T=2803,P=02, U=012A Char 0x2A01, decl handle=4, value handle=5, perm=0x02 ←RX @E,0029,DR,C=04,H=0006,R=0007,T=2803,P=02, U=042A Char 0x2A04, decl handle=6, value handle=7, perm=0x02 ←RX @E,0029,DR,C=04,H=0009,R=000A,T=2803,P=22, U=052A Char 0x2A05, decl handle=9, value handle=10, perm=0x22 ←RX @E,0045,DR,C=04,H=000D,R=000E,T=2803,P=28, U=01A10C2000089A9EE21115A133333365 Char 0x6533…A101, decl handle=13, value hand
PAGE 57
Operational Examples 3.7.2 How to Read and Write Remote GATT Attribute Values Reading and writing local GATT values may be accomplished with the gattc_read_handle (/RRH, ID=6/4) and gattc_write_handle (/WRH, ID=6/5) API commands, respectively. 3.7.3 How to Detect Notified or Indicated Values from a Remote GATT Server A remote GATT server may push data updates to a client at unpredictable times, if the client has subscribed to notifications or indication on a supported remote GATT server characteristic.
PAGE 58
Operational Examples 3.8 Security and Encryption Examples EZ-Serial supports built-in Bluetooth security technologies for safeguarding sensitive data transmitted wirelessly, including privacy and encryption. 3.8.1 How to Use Peripheral and Central Privacy GAP privacy randomizes the Bluetooth connection address visible to remote devices in while in certain operating modes. Use the smp_set_privacy_mode (SPRV, ID=7/9) API command to enable or disable peripheral or central privacy.
PAGE 59
Operational Examples Table 3-13.
PAGE 60
Operational Examples Table 3-14.
PAGE 61
Operational Examples 3.8.2.3 Pairing and Bonding in “Just Works” Mode Without MITM Protection The simplest way to bond requires no special passkey entry or display. If your device has no input or output capabilities, you must use this mode for pairing since MITM protection requires numeric display or entry (or both) to function correctly. The example below assumes that you have already connected to a remote peer device. An active connection is required for any type of pairing operation to succeed.
PAGE 62
Operational Examples NOTE: The fixed passkey will take effect only if you enable fixed passkey use by setting Bit 1 (0x02) of the security flags parameter and set the “Display Only” I/O capabilities value (0x00) using the smp_set_security_parameters (SSBP, ID=7/11) API command. If both of these conditions are not met, then the stack will revert to the default behavior of using a random passkey. The example below assumes that you have already connected to a remote peer device.
PAGE 63
Operational Examples Device Direction Content Effect #2 #1 ←RX @E,000E,ENC,C=04,S=01 Event indicates connection is encrypted ←RX @E,000F,PR,C=04,R=0000 Event indicates pairing completed successfully #2 ←RX @E,000F,PR,C=04,R=0000 Event indicates pairing completed successfully 3.8.4 How to Encrypt and Decrypt Arbitrary Data The EZ-Serial platform exposes the internal AES encryption engine via two simple API commands to allow encryption and decryption of arbitrary data.
PAGE 64
Operational Examples 3.9 Beacon Examples EZ-Serial provides simple configuration commands for beacon broadcast management. Most BLE-based beaconing technologies require only a specially formed advertisement packet, but implementing this manually requires additional tracking and modification of advertising behavior and does not allow scheduled interleaving with other types of behavior simultaneously. 3.9.1 How to Configure iBeacon Transmissions Use the p_ibeacon_set_parameters (.
PAGE 65
Operational Examples 3.10 Performance Testing Examples This section covers techniques to achieve optimal performance in specific contexts. 3.10.1 How to Maximize Throughput to a Remote Peer Throughput concerns how much data you can move across a link within a specific period of time, usually expressed in bytes per second or bits per second (8 bits per byte). In the case of BLE, the following guidelines will help improve average throughput: • Minimize the connection interval.
PAGE 66
Operational Examples • iOS 5 added support for GAP peripheral role operation, which includes support for 7.5 ms intervals as required by the Bluetooth specification. However, switching GAP roles may not be suitable depending on other application requirements, and requires a notably different mobile app development approach with its own side effects. Refer to the Core Bluetooth Programming Guide on the Apple Developer website for official guidelines.
PAGE 67
Operational Examples • o Scanning devices are less likely to detect advertisement packets for the same reason as above—there are fewer advertisement packets being transmitted, which reduces the probability of actively receiving on the correct channel at the correct time. o The advertising device cannot combat RF interference as effectively.
PAGE 68
Operational Examples Side effects: • o If the slave has no data to send, the master must wait until the slave latency period passes before it can send or request data to or from the slave. The slave will not be aware of any requests from the master until it enables its radio again. This can result in noticeable delays especially when using long connection intervals.
PAGE 69
Operational Examples Device Direction Content Effect #1 ←RX @R,0009,/LC,0000 Response indicates success #2 ←RX @E,002C,LCR,C=04,N=0041,L=0073,M=0017,P=0017 Event indicates incoming L2CAP connection #2 TX→ /LCR,C=0,N=41,R=0,M=17,Z=3 Accept connection, 3 TX credits for peer #2 ←RX @R,000A,/LCR,0000 Response indicates success #1 ←RX @E,002B,LC,C=04,R=0000,N=0041,M=0017,P=0017, Z=0003 Event indicates connection request accepted #1 TX→ /LD,N=41,D=11223344 Send 4-byte data packet to pe
PAGE 70
Operational Examples • Updating the BLE stack requires that the application be updated after the stack update completes, since the old application will have been overwritten by the temporary stack image. • If the application update process stops or fails mid-transfer, the stack will remain intact, and a reset will automatically return to the same DFU mode attempted previously.
PAGE 71
4. Application Design Examples < The examples in this section describe the hardware design and platform configuration necessary for some common types of applications. You can use any of these exactly as described for your design, or modify as needed. 4.1 Smart MCU Host with 4-Wire UART and Full GPIO Connections This design takes allows maximum functionality with an external host microcontroller, including efficient sleep state control and optional CYSPP communication. 4.1.
PAGE 72
Application Design Examples 4.2 Dumb Terminal Host with CYSPP and Simple GPIO State Indication This design takes advantage of the factory default EZ-Serial configuration and support for automatic CYSPP connectivity. It is best suited for applications where the external host cannot or does not need to impose any control over the EZ-Serial platform via API commands or events. 4.2.1 Hardware Design Include the following design elements in your hardware: 1.
PAGE 73
Application Design Examples 4.3 Module-Only Application with Beacon Functionality This design requires no special external hardware and only minimal initial configuration to define the type of beaconing desired. 4.3.1 Hardware Design For correct operation, the module only requires power to the supply pins. You may also wish to include test pad or header access to the UART interface and status pins such as LP_STATUS or CONNECTION during prototyping, as this can greatly simplify debugging if necessary. 4.
PAGE 74
5. Host API Library The host library implements a protocol parser/generator that communicates with the EZ-Serial firmware using the API protocol. The provided library is written in standard C and wraps all API methods into easy-to-use command functions or response/event callbacks. This section describes how to use the library as designed, how to port it to other platforms, or how to create your own library if the provided code is not suited for direct use or porting for any reason. 5.
PAGE 75
Host API Library 5.2 Implementing a Project Using the Host API Library 5.2.1 Basic Application Architecture Any host application which uses the EZ-Serial API library must follow the same basic behavior: 1. Set up UART peripheral for incoming and outgoing data 2. Assign hardware-specific input/output callback methods 3. Monitor UART for incoming data, and send to parser 4. Handle event/response packets sent to callback handler 5.
PAGE 76
Host API Library Function Description EZSerial_FillPacketMetaFromBinary Fills binary packet metadata in ezs_packet_t structure based on 4byte binary packet header content (used internally within EZSerial_Parse) EZSerial_SendPacket Sends binary packet and checksum byte using host-specific output callback function EZSerial_WaitForPacket Reads data using host-specific input callback function in a blocking or non-blocking way depending on timeout argument (calls EZSerial_Parse as part of its functionali
PAGE 77
Host API Library This macro-based approach means it is not possible for to perform type checking at compile time, but it also means that the entire command generator implementation uses a tiny quantity of flash memory (well under one kByte as measured on one 8-bit MCU). 5.2.4 Convenience Macros If the hardware-specific input and output functions are correctly defined, the library also provides macros to further abstract common behavior into simpler code.
PAGE 78
Host API Library 5.3 Porting the Host API Library to Different Platforms Since the API protocol uses a packet byte stream, the API host library expects matching byte ordering and packet structure mapping in order to avoid any extra processing overhead. The module (and low-level Bluetooth spec) uses littleendian byte ordering, so the host must as well for all multi-byte integer data.
PAGE 79
Host API Library 5.4 Using the API Definition JSON File to Create a Custom Library The JSON schema used for the API definition has the following structure: • • info (single dictionary) o date – Definition revision date o version – API protocol definition version groups (list of dictionaries) [ … o id – Numeric ID assigned to group o name – Alpha name assigned to group (e.g. “gap”) o commands (list of dictionaries) […  id – Numeric ID assigned to command  name – Alpha name assigned to command (e.g.
PAGE 80
6. Troubleshooting EZ-Serial is designed to be as robust and intuitive as possible, but it is always possible for something to go wrong. The instructions below can help narrow down the cause of failure in identify solutions in some cases. 6.1 UART Communication Issues If you are unable to send or receive data as expected over the UART interface, perform the following steps: 1. Ensure VDD, VDDR, and GND pins are properly connected (VDDR also requires power) 2.
PAGE 81
Troubleshooting 6.2 BLE Connection Issues If you are unable to connect to or from a remote device, perform the following steps: 1. 2. If attempting to initiate a connection to a remote peripheral/slave device: a. Ensure that the local device is in an idle state, not advertising or scanning or connected to another device.
PAGE 82
Troubleshooting 6.3 GPIO Signal Issues If you are not observing the expected behavior for GPIO input and/or output signals, perform the following steps: 1. Ensure that the pins you have connected are correct based on your chosen module. See Section 8.1 (GPIO Pin Map for Supported Modules) for per-device pin map details. 2. If a special-function pin is not generating or responding to an external signal as expected, ensure that the function is enabled using the 3.
PAGE 83
7. API Protocol Reference This section describes the API protocol that EZ-Serial uses. This protocol allows an external host to control the module, in addition to any GPIO signals involved in the design. The protocol follows a strict set of rules to make deterministic hostside behavior possible. The material in this revision of the User Guide describes version 1.3 of the API protocol. 7.1 Protocol Structure and Communication Flow 7.1.
PAGE 84
API Protocol Reference Table 7-1. API Protocol Data Types Type Bytes Description Example uint8 1 Unsigned 8-bit integer. Range is 0 to 255. Text Mode: “10” = 0x10, decimal 16 “9A” = 0x9A, decimal 154 Binary Mode: [ 10 ] = 0x10, decimal 16 [ 9A ] = 0x9A, decimal 154 int8 1 Signed 8-bit integer. Range is -128 to 127. Text Mode: “10” = 0x10, decimal 16 “9A” = 0x9A, decimal -102 Binary Mode: [ 10 ] = 0x10, decimal 16 [ 9A ] = 0x9A, decimal -102 uint16 2 Unsigned 16-bit integer.
PAGE 85
API Protocol Reference Type Bytes Description Example longuint8a 2+ Array of uint8 bytes, with prefixed two-byte length value. Supported length is 0-65535 bytes.
PAGE 86
API Protocol Reference 7.1.3.2 Binary Packet Header The binary packet 4-byte header structure is described in the table below: Table 7-2. Binary Packet Header Structure Byte Field(s) Description 0 [7:6] - Type [5:4] - Memory [2:0] - Length MSB Type: The “Type” field is a 2-bit value (MSB aligned) indicating whether the packet is a command, response, or event.
PAGE 87
API Protocol Reference 7.2 API Commands and Responses All commands and responses implemented in the API protocol are described in detail below. API events are documented separately in Section 7.3 ). A master list of all possible error codes resulting from commands can be found in Section 7.4 (Error Codes).
PAGE 88
API Protocol Reference 7.2.1.1 protocol_set_parse_mode (SPPM, ID=1/1) Configure new protocol parse mode. In binary mode, all API packets to and from the module must use a binary format with a fixed header and payload structure, as described in the reference material. In text mode, all commands, responses, and events use a humanreadable format that is suitable for typing in a terminal. See Section 7.1 (Protocol Structure and Communication Flow) for details.
PAGE 89
API Protocol Reference 7.2.1.3 protocol_set_echo_mode (SPEM, ID=1/3) Configure new protocol echo mode. The protocol echo mode applies when using text mode API protocol over UART to communicate with the module. Enabling echo will result in each input byte being sent back to the host after it is parsed. Local echo may be desirable during a terminal session, but it is typically simpler disable it for MCU communication so that the MCU only needs to parse response and event data.
PAGE 90
API Protocol Reference 7.2.2 System Group (ID=2) System methods relate to the core device and describe functionality such as boot status, setting or obtaining device address info, and resetting to an initial state.
PAGE 91
API Protocol Reference Command Arguments: None. Response Parameters: Data Type Name Text Description uint32 runtime R Number of seconds since boot uint16 fraction F Fraction of a second (units are 1/32768) 7.2.2.2 system_reboot (/RBT, ID=2/2) Reboot module. A module reboot takes effect immediately.
PAGE 92
API Protocol Reference Command Arguments: Data Type uint8 Name Text type Description Type of information to dump: • 0 = Runtime configuration data (default) • 1 = Boot-level configuration data • 2 = Factory-level configuration data • 3 = System state data T Response Parameters: Data Type Name Text uint16 length L Description Number of bytes to be dumped: • Configuration data is 674 bytes (0x02A2) • State data is 1,955 bytes (0x07A3) Related Commands: • system_store_config (/SCFG, ID=2/4) Re
PAGE 93
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 00 02 05 None. RSP C0 02 02 05 None. Text Info: Text Name Response Length Category /RFAC 0x000B ACTION Notes None. Command Arguments: None. Response Parameters: None. Related Events: • • system_factory_reset_complete (RFAC, ID=2/3) – Occurs after the settings are reset system_boot (BOOT, ID=2/1) – Occurs after the system reboots Example Usage: • Section 3.1.6.2 (Factory Reset via API Command) 7.2.2.
PAGE 94
API Protocol Reference Related Events: • system_boot (BOOT, ID=2/1) 7.2.2.7 system_query_unique_id (/QUID, ID=2/7) Query EZ-Serial module unique identifier. The module’s unique identifier comes from factory-stored data in the chipset’s supervisory flash (SFLASH) area. The four bytes returned are: 1. 2. 3. 4. Die X position Die Y position Die wafer number Die lot number Binary Header: Type Length Group ID CMD C0 00 02 07 Notes None. RSP C0 07 02 07 None.
PAGE 95
API Protocol Reference 7.2.2.9 system_aes_encrypt (/AESE, ID=2/9) Generate AES-encrypted cyphertext using provided key, initialization info, and cleartext. This command provides access to the internal hardware AES engine inside the EZ-BLE module’s chipset. The encryption process takes a 16-byte key and 13-byte nonce to initialize the engine, and can encrypt up to 27 bytes at a time. Encrypted data may be decrypted with the system_aes_decrypt (/AESD, ID=2/10) API command, using the same key and nonce.
PAGE 96
API Protocol Reference Command Arguments: Data Type uint8a Name Text I* in_struct Description Input structure (29-56 bytes): • Bytes 0-15 = 16-byte Key • Bytes 16-28 = 13-byte Nonce • Bytes 29+ = Cyphertext data to be decrypted (1 byte minimum, 27 bytes maximum) NOTE: uint8a data type requires one prefixed “length” byte before binary parameter payload Response Parameters: Data Type Name Text uint8a out O Description Cleartext output (1-27 bytes) NOTE: uint8a data type requires one prefixed “le
PAGE 97
API Protocol Reference NOTE: You must specify a data offset and length which do not exceed 256 when combined. For example, if you are reading 32 bytes of data, the specified “offset” argument must be 224 (0xE0) or less. Binary Header: Type Length Group ID Notes CMD C0 03 02 0C None. RSP C0 03 02 0C Variable-length response payload, minimum of 3 (0x3), maximum of 35 (0x23).
PAGE 98
API Protocol Reference Related Commands: • • • system_get_bluetooth_address (GBA, ID=2/14) smp_set_privacy_mode (SPRV, ID=7/9) smp_query_random_address (/QRA, ID=7/4) Example Usage: • Section 3.8.1 (How to Use Peripheral and Central Privacy) 7.2.2.14 system_get_bluetooth_address (GBA, ID=2/14) Obtain the current public Bluetooth address. Binary Header: Type Length Group ID Notes CMD C0 00 02 0E None. RSP C0 08 02 0E None.
PAGE 99
API Protocol Reference • system_get_wco_parameters (GWCO, ID=2/18) 7.2.2.16 system_get_eco_parameters (GECO, ID=2/16) Obtain the current External Clock Oscillator (ECO) trim value. Binary Header: Type Length Group ID Notes CMD C0 00 02 10 None. RSP C0 04 02 10 None. Text Info: Text Name Response Length Category GECO 0x0011 GET Notes None. Command Arguments: None.
PAGE 100
API Protocol Reference • • system_get_eco_parameters (GECO, ID=2/16) system_get_wco_parameters (GWCO, ID=2/18) 7.2.2.18 system_get_wco_parameters (GWCO, ID=2/18) Obtain the current Watch Clock Oscillator (WCO) accuracy value. Binary Header: Type Length Group ID Notes CMD C0 00 02 12 None. RSP C0 03 02 12 None. Text Info: Text Name Response Length Category GWCO 0x000F GET Notes None. Command Arguments: None.
PAGE 101
API Protocol Reference Command Arguments: Data Type uint8 Name level Text Description New maximum system-wide sleep level: • 0 = Sleep disabled • 1 = Normal sleep when possible (factory default) • 2 = Deep sleep when possible L Response Parameters: None. Related Commands: • • • system_get_sleep_parameters (GSLP, ID=2/20) gpio_set_pwm_mode (SPWM, ID=9/11) – Configure PWM output p_cyspp_set_parameters (.
PAGE 102
API Protocol Reference Command Arguments: Data Type uint8 Name power Text Description New transmit power: • 1 = -18 dBm • 2 = -12 dBm (default/maximum for CYBLE-2X20XX-X1) • 3 = -6 dBm (default/maximum for CYBLE-224110-00 and CYBLE-224116-01) • 4 = -3 dBm • 5 = -2 dBm • 6 = -1 dBm • 7 = +0 dBm (factory default) • 8 = +3 dBm P Response Parameters: None. Related Commands: • system_get_tx_power (GTXP, ID=2/22) 7.2.2.
PAGE 103
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 01 02 17 None. RSP C0 02 02 17 None. Text Info: Text Name Response Length Category ST 0x0008 SET Notes None. Command Arguments: Data Type Name Text uint8 interface I Description New host transport interface: • 1 = UART (factory default) Response Parameters: None. Related Commands: • • system_get_transport (GT, ID=2/24) system_set_uart_parameters (STU, ID=2/25) 7.2.2.
PAGE 104
API Protocol Reference stored settings that the connected host cannot use. For detail, refer to Section 2.5.3 (Protected Configuration Settings). WARNING: If you have deep sleep enabled using the system_set_sleep_parameters (SSLP, ID=2/19) API command and you are relying on UART data reception to wake the module from deep sleep, the number of dummy bytes needed for wake-up depends on the baud rate chosen, and the recommended dummy byte depends on whether you have enabled even parity or not.
PAGE 105
API Protocol Reference Data Type uint8 Name Text stopbits Description UART stop bits: • 1 = 1 stop bit (factory default) • 2 = 1.5 stop bits • 3 = 2 stop bits • 4 = 2.5 stop bits • 5 = 3 stop bits • 6 = 3.5 stop bits • 7 = 4 stop bits S Response Parameters: None. Related Commands: • • system_set_transport (ST, ID=2/23) system_get_uart_parameters (GTU, ID=2/26) Example Usage: • • Section 3.1.2 (How to Change the Serial Communication Parameters) Section 3.1.5.
PAGE 106
API Protocol Reference Data Type Name uint8 Text stopbits Description UART stop bits: • 1 = 1 stop bit (factory default) • 2 = 1.5 stop bits • 3 = 2 stop bits • 4 = 2.5 stop bits • 5 = 3 stop bits • 6 = 3.5 stop bits • 7 = 4 stop bits S Related Commands: • • system_get_transport (GT, ID=2/24) system_set_uart_parameters (STU, ID=2/25) 7.2.3 DFU Group (ID=3) DFU methods relate to the firmware update process, using either wired UART or over-the-air GATT-based firmware transfer.
PAGE 107
API Protocol Reference Response Parameters: None. Related Events: • dfu_boot (BDFU, ID=3/1) Example Usage: • Section 3.11.2 (How to Update Firmware Using the DFU Bootloader) 7.2.4 GAP Group (ID=4) GAP methods relate to the Generic Access Protocol layer of the Bluetooth stack, which includes management of scanning and advertising, connection establishment, and connection maintenance.
PAGE 108
API Protocol Reference NOTE: If scan_timeout is set to zero, the connection attempt will persist forever until it succeeds or it is cancelled intentionally. The supervision_timeout parameter governs link loss detection after a connection is established, and does not affect the connection attempt itself. Binary Header: Type Length Group ID Notes CMD C0 13 04 01 None. RSP C0 03 04 01 None. Text Info: Text Name Response Length Category /C 0x000D ACTION Notes None.
PAGE 109
API Protocol Reference Example Usage: • Section 3.5.3 (How to Connect to a Peripheral Device) 7.2.4.2 gap_cancel_connection (/CX, ID=4/2) Cancel a pending connection attempt. Use this command to manually end a pending connection attempt to a remote peer device which you previously initiated with the gap_connect (/C, ID=4/1) API command. This command takes no parameters because it is not possible to have more than one pending outgoing connection attempt at a time.
PAGE 110
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 07 04 03 None. RSP C0 02 04 03 None. Text Info: Text Name Response Length Category /UCP 0x000A ACTION Notes None.
PAGE 111
API Protocol Reference Related Events: • gap_connection_update_requested (UCR, ID=4/7) 7.2.4.5 gap_disconnect (/DIS, ID=4/5) Close an open connection to a remote device. Use this command to cleanly close an established connection with a remote peer device. The connection must first have been fully opened, indicated by the gap_connected (C, ID=4/5) API event. NOTE: This command only applies when closing a connection that is fully open.
PAGE 112
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 07 04 06 None. RSP C0 03 04 06 None. Text Info: Text Name Response Length Category /WLA 0x000F ACTION Notes None.
PAGE 113
API Protocol Reference Response Parameters: Data Type Name Text uint8 count C Description Updated whitelist entry count Related Commands: • gap_add_whitelist_entry (/WLA, ID=4/6) 7.2.4.8 gap_start_adv (/A, ID=4/8) Start advertising. This command begins advertising using the specified parameters, or using the pre-configured default advertising parameters if in text mode and some arguments are omitted. EZ-Serial must not already be advertising in order for this command to succeed.
PAGE 114
API Protocol Reference Data Type Name Text Description uint8 filter F Advertisement filter policy: • 0 = Scan request and connect request from any • 1 = Scan request whitelist-only, connect request from any • 2 = Scan request from any, connect request whitelist-only • 3 = Scan request and connect request whitelist-only uint16 timeout O Advertisement timeout (seconds): • 0 to disable Response Parameters: None.
PAGE 115
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 0A 04 0A None. RSP C0 02 04 0A None. Text Info: Text Name Response Length Category /S 0x0008 ACTION Notes None. Command Arguments: Data Type Name Text Description uint8 mode M Discovery mode: • 0 = Observation mode • 1 = Limited discovery mode • 2 = General discovery mode uint16 interval I Scan interval (625 µs units): • Minimum = 0x0004 (4 * 0.625 ms = 2.5 ms) • Maximum = 0x4000 (16384 * 0.
PAGE 116
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 00 04 0B None. RSP C0 02 04 0B None. Text Info: Text Name Response Length Category /SX 0x0009 ACTION Notes None. Command Arguments: None. Response Parameters: None. Related Commands: • gap_start_scan (/S, ID=4/10) Related Events: • gap_scan_state_changed (SSC, ID=4/3) 7.2.4.12 gap_query_peer_address (/QPA, ID=4/12) Query remote peer Bluetooth address.
PAGE 117
API Protocol Reference The RSSI value returned in the response is expressed as a signed 8-bit integer. In text mode, it will appear in two’s complement form. Positive numbers in this form fall in the range [0, 127] and are as they appear. Negative numbers fall in the range [128, 255] and should have 256 subtracted from them to obtain the real value.
PAGE 118
API Protocol Reference Related Events: • gap_whitelist_entry (WL, ID=4/1) 7.2.4.15 gap_set_device_name (SDN, ID=4/15) Configure a new device name. This is typically a UTF-8 string value that is stored in the Device Name characteristic (UUID 0x2A00) in the local GATT structure. This characteristic is part of the GAP service (UUID 0x1800). The GAP service is mandatory for all Bluetooth Smart devices, and the Device Name characteristic is a mandatory part of the GAP service.
PAGE 119
API Protocol Reference 7.2.4.17 gap_set_device_appearance (SDA, ID=4/17) Configure a new device name. Define the device appearance value. This is a 16-bit value which is stored in the Appearance characteristic (UUID 0x2A01) in the local GATT structure. This characteristic is part of the GAP service (UUID 0x1800). The GAP service is mandatory for every Bluetooth Smart device, and the Appearance characteristic is a mandatory part of the GAP service.
PAGE 120
API Protocol Reference NOTE: EZ-Serial automatically manages advertisement content unless you enable the use of userdefined data with the gap_set_adv_parameters (SAP, ID=4/23) API command. If you only set custom data but do not enable user-defined content, the data here will remain unused. Binary Header: Type Length Group ID Notes CMD C0 01-20 04 13 Variable-length command payload, minimum of 1 (0x01), maximum of 32 (0x20) RSP C0 02 04 13 None.
PAGE 121
API Protocol Reference 7.2.4.21 gap_set_sr_data (SSRD, ID=4/21) Configure new custom scan response packet payload. This command defines a new byte sequence for the scan response packet. This content will be visible to all scanning devices performing an active scan when the EZ-BLE module is in a scannable advertising state. NOTE: EZ-Serial automatically manages scan response content unless you enable the use of userdefined data with the gap_set_adv_parameters (SAP, ID=4/23) API command.
PAGE 122
API Protocol Reference Related Commands: • gap_set_sr_data (SSRD, ID=4/21) 7.2.4.23 gap_set_adv_parameters (SAP, ID=4/23) Configure new default advertisement parameters. These parameters will be used when sending the gap_start_adv (/A, ID=4/8) API command in text mode without specifying non-default arguments. NOTE: Setting Bit 0 (0x01) of the flags value using this command will enable automatic advertisement on boot, as described.
PAGE 123
API Protocol Reference Related Commands: • • gap_start_adv (/A, ID=4/8) gap_get_adv_parameters (GAP, ID=4/24) 7.2.4.24 gap_get_adv_parameters (GAP, ID=4/24) Obtain the current advertisement parameters. Binary Header: Type Length Group ID CMD C0 00 04 18 None. Notes RSP C0 0B 04 18 None. Text Info: Text Name Response Length Category GAP 0x0030 GET Notes None. Command Arguments: None.
PAGE 124
API Protocol Reference 7.2.4.25 gap_set_scan_parameters (SSP, ID=4/25) Configure new default scan parameters. These parameters will be used when sending the gap_start_scan (/S, ID=4/10) API command in text mode without specifying non-default arguments. Binary Header: Type Length Group ID Notes CMD C0 0A 04 19 None. RSP C0 02 04 19 None. Text Info: Text Name Response Length Category SSP 0x0009 SET Notes None.
PAGE 125
API Protocol Reference 7.2.4.26 gap_get_scan_parameters (GSP, ID=4/26) Obtain the current scan parameters. Binary Header: Type Length Group ID Notes CMD C0 00 04 1A None. RSP C0 0C 04 1A None. Text Info: Text Name Response Length Category GSP 0x0032 GET Notes None. Command Arguments: None.
PAGE 126
API Protocol Reference 7.2.4.27 gap_set_conn_parameters (SCP, ID=4/27) Configure new default connection parameters. These parameters will be used when sending the gap_connect (/C, ID=4/1) API command in text mode without specifying non-default arguments. Binary Header: Type Length Group ID Notes CMD C0 0C 04 1B None. RSP C0 02 04 1B None. Text Info: Text Name Response Length Category SCP 0x0009 SET Notes None.
PAGE 127
API Protocol Reference Text Info: Text Name Response Length Category GCP 0x0033 GET Notes None. Command Arguments: None. Response Parameters: Data Type Name Text uint16 interval I Connection interval (1.25 ms units): • Minimum = 0x0006 (6 * 1.25 ms = 7.5 ms, factory default) • Maximum = 0x0C80 (3200 * 1.
PAGE 128
API Protocol Reference 7.2.5 GATT Server Group (ID=5) GATT server methods relate to the server role of the Generic Attribute Protocol layer of the Bluetooth stack. These methods are used for working with the local GATT structure.
PAGE 129
API Protocol Reference control using the system_set_uart_parameters (STU, ID=2/25) API command, EZ-Serial will block incoming data flow during flash writes to prevent serial data corruption or loss. Binary Header: Type Length Group ID Notes CMD C0 09 05 01 Variable-length command payload, value specified is minimum RSP C0 06 05 01 None. Text Info: Text Name Response Length Category /CAC 0x0018 ACTION Notes None.
PAGE 130
API Protocol Reference Response Parameters: Data Type Name Text Description uint16 handle H New attribute handle (0x0001-0xFFFF) uint16 valid V GATT database validity status Related Commands: • • • gatts_delete_attr (/CAD, ID=5/2) gatts_validate_db (/VGDB, ID=5/3) gatts_dump_db (/DGDB, ID=5/5) Related Events: • gatts_db_entry_blob (DGATT, ID=5/4) Example Usage: • • Section 3.6.1 (How to Define Custom Local GATT Services and Characteristics) Section 10.
PAGE 131
API Protocol Reference Response Parameters: Data Type Name Text Description uint16 count C Number of attributes deleted from GATT structure uint16 next_handle H Next available attribute handle after removal uint16 valid V GATT database validity status Related Commands: • • • gatts_create_attr (/CAC, ID=5/1) gatts_validate_db (/VGDB, ID=5/3) gatts_dump_db (/DGDB, ID=5/5) 7.2.5.
PAGE 132
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 00 05 04 None. RSP C0 02 05 04 None. Text Info: Text Name Response Length Category /SGDB 0x000B ACTION Notes None. Command Arguments: None. Response Parameters: None. Related Commands: • • • • gatts_create_attr (/CAC, ID=5/1) gatts_delete_attr (/CAD, ID=5/2) gatts_validate_db (/VGDB, ID=5/3) gatts_dump_db (/DGDB, ID=5/5) 7.2.5.5 gatts_dump_db (/DGDB, ID=5/5) List current local GATT database attributes.
PAGE 133
API Protocol Reference 7.2.5.6 gatts_discover_services (/DLS, ID=5/6) Request a list of all services in the local GATT structure. This allows convenient discovery of services within the local GATT database. This command does not require an active connection, since it concerns only local resources. Normally, you should not need to use this command except during development, since the application should already know all relevant details about its own local GATT structure.
PAGE 134
API Protocol Reference The gatts_discover_result (DL, ID=5/1) API events resulting from this command have the same format as the client-side gattc_discover_result (DR, ID=6/1) events which result from the gattc_discover_characteristics (/DRC, ID=6/2) API command for discovering remote GATT characteristics. For local GATT database information that more closely matches the input format required for the gatts_create_attr (/CAC, ID=5/1) API command, use the gatts_dump_db (/DGDB, ID=5/5) API command instead.
PAGE 135
API Protocol Reference Text Info: Text Name Response Length Category /DLD 0x0011 ACTION Notes None.
PAGE 136
API Protocol Reference 7.2.5.10 gatts_write_handle (/WLH, ID=5/10) Write a new value to an attribute in the local GATT server. This command does not require an active connection, since it concerns only local resources. To write a value to a remote attribute on a connected peer, use the gattc_write_handle (/WRH, ID=6/5) API command.
PAGE 137
API Protocol Reference Command Arguments: Data Type Name Text Description uint8 conn_handle C Connection handle to use for notification (Ignored in current release due to internal BLE stack functionality, set to 0) uint16 attr_handle H* Handle of attribute to notify uint8a data D* Data to push to remote client via notification NOTE: uint8a data type requires one prefixed “length” byte before binary parameter payload Response Parameters: None.
PAGE 138
API Protocol Reference • gattc_confirm_indication (/CI, ID=6/6) – Used on remote client to confirm receipt of the indication Related Events: • • gatts_indication_confirmed (IC, ID=5/3) - Occurs on the server after the remote client confirms receipt of indicated data gattc_data_received (D, ID=6/3) – Occurs on the remote client when indicated data is received 7.2.5.13 gatts_send_writereq_response (/WRR, ID=5/13) Respond to a GATT client’s acknowledged write request.
PAGE 139
API Protocol Reference Command Arguments: Data Type Name Text uint8 flags F Description GATT server behavior flags bitmask: • Bit 0 (0x01) = Enable automatic response to acknowledged writes • NOTE: Factory default is 0x01 (all bits set) Response Parameters: None. Related Commands: • • gatts_send_writereq_response (/WRR, ID=5/13) – Necessary to use for acknowledged client writes if flags Bit 0 is clear gatts_get_parameters (GGSP, ID=5/15) 7.2.5.
PAGE 140
API Protocol Reference 7.2.6 GATT Client Group (ID=6) GATT client methods relate to the client role of the Generic Attribute Protocol layer of the Bluetooth stack. These methods are used for working with the GATT structures on remote devices, and can only be used while a device is connected.
PAGE 141
API Protocol Reference 7.2.6.2 gattc_discover_characteristics (/DRC, ID=6/2) Request a list of GATT characteristics from a connected remote GATT server. This command performs a GATT client operation, and requires a connection to a remote peer. To discover the local GATT structure instead, use the gatts_discover_characteristics (/DLC, ID=5/7) API command. NOTE: Because this command works with remote data, it cannot determine the number of records to be returned in advance.
PAGE 142
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 09 06 03 None. RSP C0 02 06 03 None. Text Info: Text Name Response Length Category /DRD 0x000A ACTION Notes None.
PAGE 143
API Protocol Reference Response Parameters: None. Related Commands: • gattc_write_handle (/WRH, ID=6/5) Related Events: • • gattc_remote_procedure_complete (RPC, ID=6/2) – Occurs if the client read operation fails (parameters include error code) gattc_data_received (D, ID=6/3) – Occurs if the client read operation succeeds 7.2.6.5 gattc_write_handle (/WRH, ID=6/5) Write a new value to an attribute on a remote GATT server.
PAGE 144
API Protocol Reference NOTE: If indicated data arrives and requires manual confirmation, you must use this command to confirm it before performing any other GATT operations. Binary Header: Type Length Group ID Notes CMD C0 01 06 06 None. RSP C0 02 06 06 None. Text Info: Text Name Response Length Category /CI 0x0009 ACTION Notes None.
PAGE 145
API Protocol Reference 7.2.6.8 gattc_get_parameters (GGCP, ID=6/8) Get current GATT client parameters. Binary Header: Type Length Group ID Notes CMD C0 00 06 08 None. RSP C0 03 06 08 None. Text Info: Text Name Response Length Category GGCP 0x000F GET Notes None. Command Arguments: None.
PAGE 146
API Protocol Reference 7.2.7 SMP Group (ID=7) SMP methods relate to the Security Manager Protocol layer of the Bluetooth stack. These methods are used for working with privacy, encryption, pairing, and bonding between two devices.
PAGE 147
API Protocol Reference 7.2.7.2 smp_delete_bond (/BD, ID=7/2) Remove a bonded device. This command removes the stored encryption key data for a device that has previously paired (exchanged encryption data) and bonded (stored the exchanged encryption data). Binary Header: Type Length Group ID Notes CMD C0 07 07 02 None. RSP C0 03 07 02 None. Text Info: Text Name Response Length Category /BD 0x000E ACTION Notes None.
PAGE 148
API Protocol Reference Data Type Name Text Description uint8 mode M Security level setting reported to peer: • 0x10 = Mode 1, Level 1 – No security • 0x11 = Mode 1, Level 2 – Unauthenticated pairing with encryption (no MITM, factory default) • 0x12 = Mode 1, Level 3 – Authenticated pairing with encryption (with MITM) • 0x13 = Mode 1, Level 4 – LE Secure Connections (reported by remote peers only, not locally implemented in current EZ-Serial firmware) • 0x21 = Mode 2, Level 2 – Unauthenticated pairin
PAGE 149
API Protocol Reference Related Commands: • smp_set_privacy_mode (SPRV, ID=7/9) 7.2.7.5 smp_send_pairreq_response (/PR, ID=7/5) Send a response to a pairing request from a remote device. EZ-Serial will automatically accept pairing requests unless Bit 0 of the security behavior flags is cleared using the flags field in the smp_set_security_parameters (SSBP, ID=7/11) API command. If the auto-accept feature is disabled, use this command to manually accept or deny a remotely initiated pairing process.
PAGE 150
API Protocol Reference Response Parameters: None. Related Commands: • smp_pair (/P, ID=7/3) Related Events: • • smp_passkey_display_requested (PKD, ID=7/5) smp_passkey_entry_requested (PKE, ID=7/6) 7.2.7.7 smp_generate_oob_data (/GOOB, ID=7/7) Generate out-of-band data for pairing. EZ-Serial supports the use of out-of-band (OOB) encryption key sharing for added security during pairing with compatible devices. This command does not directly set OOB data.
PAGE 151
API Protocol Reference security data set, pairing will always fail. To clear OOB data and revert to the standard pairing and key generation/exchange process, use this command or else reset the module via hardware or software. Binary Header: Type Length Group ID Notes CMD C0 01 07 08 None. RSP C0 02 07 08 None. Text Info: Text Name Response Length Category /COOB 0x000B ACTION Notes None. Command Arguments: None.
PAGE 152
API Protocol Reference 7.2.7.10 smp_get_privacy_mode (GPRV, ID=7/10) Obtain current privacy settings. Binary Header: Type Length Group ID Notes CMD C0 00 07 0A None. RSP C0 05 07 0A None. Text Info: Text Name Response Length Category GPRV 0x0016 GET Notes None. Command Arguments: None.
PAGE 153
API Protocol Reference Command Arguments: Data Type Name Text Description uint8 mode M Security level setting reported to peer: • 0x10 = Mode 1, Level 1 – No security • 0x11 = Mode 1, Level 2 – Unauthenticated pairing with encryption (no MITM, factory default) • 0x12 = Mode 1, Level 3 – Authenticated pairing with encryption (with MITM) • 0x13 = Mode 1, Level 4 – LE Secure Connections (reported by remote peers only, not locally implemented in current EZ-Serial firmware) • 0x21 = Mode 2, Level 2 – Una
PAGE 154
API Protocol Reference Command Arguments: None.
PAGE 155
API Protocol Reference Command Arguments: Data Type uint32 Name Text passkey Description Fixed passkey value • Minimum = 0 (‘000000’ decimal entry during pairing) • Maximum = 0xF423F (‘999999’ decimal entry during pairing) • NOTE: Factory default is 0 P Response Parameters: None. Related Commands: • • • • • • smp_pair (/P, ID=7/3) smp_send_pairreq_response (/PR, ID=7/5) Example Usage: Section 3.8.2.
PAGE 156
API Protocol Reference 7.2.8 L2CAP Group (ID=8) L2CAP methods relate to the Logical Link Control and Adaptation Protocol layer of the Bluetooth stack. These methods are used for working directly with low-level data transfer between two connected devices. NOTE: L2CAP communication features within EZ-Serial are only available on devices with 256K of flash memory. The API methods described in this section will not function on devices with only 128K of flash.
PAGE 157
API Protocol Reference Response Parameters: None.
PAGE 158
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 04 08 03 None. RSP C0 02 08 03 None. Text Info: Text Name Response Length Category /LRP 0x000A ACTION Notes None. Command Arguments: Data Type Name Text Description uint16 channel N* Local PSM channel to register uint16 watermark W Low credit watermark (default = 0) Response Parameters: None.
PAGE 159
API Protocol Reference Related Commands: • l2cap_connect (/LC, ID=8/1) – Used to initiate an L2CAP connection Related Events: • • l2cap_connection_requested (LCR, ID=8/1) – Occurs locally when a remote device initiates an L2CAP connection l2cap_connection_response (LC, ID=8/2) – Occurs on the remote device after sending the response to a connection request Example Usage: • Section 3.10.3 (How to Communicate Using an L2CAP Channel) 7.2.8.
PAGE 160
API Protocol Reference Each transmission with this command uses one TX credit, regardless of length. To maximize throughput, make sure you fill the packet with as many bytes as possible based on the data available in your transmission buffer. Binary Header: Type Length Group ID Notes CMD C0 05 08 06 Variable-length command payload, value specified is minimum RSP C0 02 08 06 None. Text Info: Text Name Response Length Category /LD 0x0009 ACTION Notes None.
PAGE 161
API Protocol Reference Some ports do not have all pins physically exposed on the module. If you select any non-exposed pins, the command processor will silently ignore them (they will be cleared from the mask value and the affected return value). Some pins have special functions assigned to them and enabled by default from the factory.
PAGE 162
API Protocol Reference Related Commands: • • gpio_set_logic (SIOL, ID=9/7) – Use to set output/pull logic state internally (may be overridden by external connections) gpio_get_logic (GIOL, ID=9/8) – Use to get output logic settings (not the same as actual logic levels) Related Events: • gpio_interrupt (INT, ID=9/1) – Includes port logic state at moment interrupt occurred 7.2.9.2 gpio_query_adc (/QADC, ID=9/2) Read the immediate analog voltage level on the selected channel.
PAGE 163
API Protocol Reference Command Arguments: Data Type Name Text Description uint8 port P* GPIO port (0-5) uint8 mask M* Pin selection mask (set bit to select pin for modification) uint8 enable E Pin function mask (set bit to enable, clear to disable) uint8 drive D Pin function drive mode (set bit for strong drive, clear for 5.
PAGE 164
API Protocol Reference D W U A Drive mode 0 1 1 0 Digital input, pull-up/down 1 0 0 0 Digital output, strong drive 1 0 1 0 Digital output, open-drain drives high 1 1 0 0 Digital output, open-drain drives low 1 1 1 0 Digital output, strong drive (same as 1/0/0/0) See Section 8.1 (GPIO Pin Map for Supported Modules) for a pin map table showing pin availability and default assignment. Refer to the general overview in Section 7.2.
PAGE 165
API Protocol Reference Command Arguments: Data Type Name Text uint8 port P* Description GPIO port (0-5) Response Parameters: Data Type Name Text Description uint8 direction D Pin digital direction mask (set bit for output, clear for input) uint8 pulldrive_down W Pin digital pull-down/drive-low mask (set bit to enable pull-down/drive-low, clear to disable) uint8 pulldrive_up U Pin digital pull-up/drive-high mask (set bit to enable pull-up/drive-high, clear to disable) uint8 analog A
PAGE 166
API Protocol Reference 7.2.9.8 gpio_get_logic (GIOL, ID=9/8) Obtain current output logic for selected pins. See Section 8.1 (GPIO Pin Map for Supported Modules) for a pin map table showing pin availability and default assignment. NOTE: This command does not return the immediate logic level of any pins. Instead, it returns the configured logic values set using the gpio_set_logic (SIOL, ID=9/7) API command.
PAGE 167
API Protocol Reference Command Arguments: Data Type Name Text Description uint8 port P* GPIO port (0-5) uint8 mask M* Pin selection mask (set bit to select pin) uint8 rising R Rising-edge interrupts (set bit to enable, clear to disable) uint8 falling F Falling-edge interrupts (set bit to enable, clear to disable) Response Parameters: Data Type Name Text uint8 affected A Description Affected pin mask (set bit for affected, clear for unaffected) Related Commands: • gpio_get_interr
PAGE 168
API Protocol Reference See Section 8.1 (GPIO Pin Map for Supported Modules) for a pin map table showing pin availability and default assignment. NOTE: Enabling PWM output on one or more channels will automatically prevent the CPU from entering deep sleep under any circumstances. This happens because the high-frequency clock required to generate the PWM signal cannot operate while the CPU is in deep sleep. To allow deep sleep mode again, you must disable all PWM output. Refer to Section 3.1.
PAGE 169
API Protocol Reference Text Info: Text Name Response Length Category GPWM 0x0027 GET Notes None.
PAGE 170
API Protocol Reference Binary Header: Type Length Group ID Notes CMD C0 00 0A 01 None. RSP C0 02 0A 01 None. Text Info: Text Name Response Length Category .CYSPPCHECK 0x0011 ACTION Notes None. Command Arguments: None. Response Parameters: None. Related Commands: • • • p_cyspp_start (.CYSPPSTART, ID=10/2) p_cyspp_set_parameters (.CYSPPSP, ID=10/3) p_cyspp_set_client_handles (.CYSPPSH, ID=10/5) Related Events: • p_cyspp_status (.CYSPP, ID=10/1) 7.2.10.2 p_cyspp_start (.
PAGE 171
API Protocol Reference 7.2.10.3 p_cyspp_set_parameters (.CYSPPSP, ID=10/3) Configure new CYSPP behavior settings. Use this command to control how CYSPP behaves. You can find example usage and practical explanations of how these settings affect behavior in Section 2.4.5 (Using CYSPP Mode) and Section 3.2 (Cable Replacement Examples with CYSPP) NOTE: Disabling CYSPP with this API method will cause EZ-Serial to hide the relevant GATT database attributes from client discovery.
PAGE 172
API Protocol Reference • p_cyspp_set_client_handles (.CYSPPSH, ID=10/5) Related Events: • • • gap_adv_state_changed (ASC, ID=4/2) – May occur if CYSPP is set to start automatically in peripheral role gap_scan_state_changed (SSC, ID=4/3) – May occur if CYSPP is set to start automatically in central role p_cyspp_status (.CYSPP, ID=10/1) Example Usage: • • • Section 2.4.5 (Using CYSPP Mode) Section 3.1.5.2 (Configuring the CYSPP Data Mode Sleep Level) Section 3.
PAGE 173
API Protocol Reference 7.2.10.5 p_cyspp_set_client_handles (.CYSPPSH, ID=10/5) Configure new preset attribute handles for CYSPP central/client operation. Use this command to specify the remote GATT server handles manually for data and optional RX flow control. If you know these handles in advance and can guarantee that they will not change, then configuring them here causes EZ-Serial to skip the GATT discovery process that normally occurs during CYSPP client operation.
PAGE 174
API Protocol Reference 7.2.10.6 p_cyspp_get_client_handles (.CYSPPGH, ID=10/6) Obtain current preset attribute handles for CYSPP central/client operation. Binary Header: Type Length Group ID Notes CMD C0 00 0A 06 None. RSP C0 0A 0A 06 None. Text Info: Text Name Response Length Category .CYSPPGH 0x002A GET Notes None. Command Arguments: None.
PAGE 175
API Protocol Reference • Mode 1: Anticipate (factory default with 5 ms wait and 20 byte length) This mode waits up to [wait] milliseconds in anticipation for at least [length] bytes to arrive from the external host. If the target byte count is reached before the wait time expires, all available bytes will be transmitted immediately. If the configured wait time expires before reaching the target byte count, all available bytes will be transmitted at that time.
PAGE 176
API Protocol Reference Table 7-4. Common UART Timing for 20-Byte Packets Baud Rate Single Bit Duration 20 Bytes at 8/N/1 (200 Bits) Safe Wait Value Example 9600 104 us ~21 ms 32 ms (0x20) 38400 26.1 us ~5.2 ms 10 ms (0x0A) 57600 17.4 us ~3.5 ms 5 ms (0x05) 115200 8.68 us ~1.7 ms 5 ms (0x05) 230400 4.34 us 868 us 2 ms (0x02) 460800 2.17 us 434 us 1 ms (0x01) 921600 1.
PAGE 177
API Protocol Reference 7.2.10.8 p_cyspp_get_packetization (.CYSPPGK, ID=10/8) Obtain current CYSPP packetization settings. Binary Header: Type Length Group ID Notes CMD C0 00 0A 08 None. RSP C0 05 0A 08 None. Text Info: Text Name Response Length Category .CYSPPGK 0x001D GET Notes None. Command Arguments: None.
PAGE 178
API Protocol Reference 7.2.11 CYCommand Group (ID=11) CYCommand methods relate to CYCommand remote configuration channel behavior. Commands within this group are listed below: • • p_cycommand_set_parameters (.CYCOMSP, ID=11/1) p_cycommand_get_parameters (.CYCOMGP, ID=11/2) Events within this group are documented in Section 7.3.11 CYCommand Group (ID=11). 7.2.11.1 p_cycommand_set_parameters (.CYCOMSP, ID=11/1) Configure new CYCommand remote configuration channel behavior.
PAGE 179
API Protocol Reference Data Type Name Text uint8 security S uint8a secret R Description CYCommand security requirement to allow writing API protocol data from a client: • 0 = No security required (factory default) • 1 = Encryption required • 2 = Bonding required • 3 = Encryption and bonding required CYCommand secret (0-20 bytes) NOTE: uint8a data type requires one prefixed “length” byte before binary parameter payload Response Parameters: None. Related Commands: • p_cycommand_get_parameters (.
PAGE 180
API Protocol Reference Data Type Name Text uint8 security S uint8a secret R Description CYCommand security requirement to allow writing API protocol data from a client: • 0 = No security required (factory default) • 1 = Encryption required • 2 = Bonding required • 3 = Encryption and bonding required CYCommand secret (0-20 bytes) NOTE: uint8a data type requires one prefixed “length” byte before binary parameter payload Related Commands: • p_cycommand_set_parameters (.CYCOMSP, ID=11/1) 7.2.
PAGE 181
API Protocol Reference Response Parameters: None. Related Commands: • p_ibeacon_get_parameters (.IBGP, ID=12/2) Related Events: • gap_adv_state_changed (ASC, ID=4/2) – May occur if iBeacon is set to start automatically Example Usage: • Section 3.9.1 (How to Configure iBeacon Transmissions) 7.2.12.2 p_ibeacon_get_parameters (.IBGP, ID=12/2) Sets up iBeacon behavior. Binary Header: Type Length Group ID Notes CMD C0 00 0C 02 None. RSP C0 1C 0C 02 None.
PAGE 182
API Protocol Reference 7.2.13 Eddystone Group (ID=13) Eddystone methods relate to Eddystone beacon setup and operation. Commands within this group are listed below: • • p_eddystone_set_parameters (.EDDYSP, ID=13/1) p_eddystone_get_parameters (.EDDYGP, ID=13/2) Events within this group are documented in Section 7.3.13, Eddystone Group (ID=13). 7.2.13.1 p_eddystone_set_parameters (.EDDYSP, ID=13/1) Configure new Eddystone beacon behavior.
PAGE 183
API Protocol Reference 7.2.13.2 p_eddystone_get_parameters (.EDDYGP, ID=13/2) Obtain current Eddystone beacon behavior. Binary Header: Type Length Group ID Notes CMD C0 00 0D 02 None. RSP C0 07-1A 0D 02 Variable-length response payload, minimum of 7 (0x07), maximum of 26 (0x1A) Text Info: Text Name Response Length Category .EDDYGP 0x0021-0x0047 GET Notes Variable-length response payload, minimum of 33 (0x21), maximum of 71 (0x47) Command Arguments: None.
PAGE 184
API Protocol Reference 7.3 API Events All events implemented in the API protocol are described in detail below. API commands and responses are documented separately in Section 7.2 (API Commands and Responses). A master list of all possible error codes appearing in certain events can be found in Section 7.4 (Error Codes).
PAGE 185
API Protocol Reference Data Type uint8 Name Text hardware Description H Hardware identifier: • 0x01 = CYBLE-01201X-X0 • 0x02 = CYBLE-014008-00 • 0x03 = CYBLE-022001-00 • 0x04 = CYBLE-2X20XX-X1 • 0x05 = CYBLE-2120XX-X0 • 0x06 = CYBLE-212020-01 • 0x07 = CYBLE-214009-00 • 0x08 = CYBLE-214015-01 • 0x09 = CYBLE-222005-00 • 0x0A = CYBLE-222014-01 • 0x0B = CYBLE-224110-00 • 0x0C = CYBLE-224116-01 uint8 cause C Cause of boot event: • 0x01 = Hardware power-on/reset • 0x02 = Wake from hibernation mode • 0
PAGE 186
API Protocol Reference Binary Header: Type Length Group ID 80 00 02 03 Notes None. Text Info: Text Name Event Length RFAC 0x0005 Notes None. Event Parameters: None. Related Commands: • system_factory_reset (/RFAC, ID=2/5) 7.3.2.4 system_factory_test_entered (TFAC, ID=2/4) Manufacturing test mode active. This event occurs if you assert (LOW) the FACTORY_TR pin at boot time. The module will remain in this state until you reset or power-cycle it.
PAGE 187
API Protocol Reference 7.3.3 DFU Group (ID=3) DFU methods relate to the firmware update process, using either wired UART or over-the-air GATT-based firmware transfer. NOTE: DFU features within EZ-Serial are only available on devices with 256k of flash memory. The API methods described in this section will not function on devices with only 128k of flash. Events within this group are listed below: • dfu_boot (BDFU, ID=3/1) Commands within this group are documented in Section 7.2.3, DFU Group (ID=3). 7.3.
PAGE 188
API Protocol Reference Data Type Name uint8 Text hardware Description Hardware identifier (added in v1.
PAGE 189
API Protocol Reference • gap_query_whitelist (/QWL, ID=4/14) 7.3.4.2 gap_adv_state_changed (ASC, ID=4/2) Indicates that the module has started or stopped advertising, due to a scheduled timeout, automated process, or intentional action. Binary Header: Type Length Group ID 80 02 04 02 Notes None. Text Info: Text Name Event Length ASC 0x000E Notes None.
PAGE 190
API Protocol Reference Related Commands: • • • • gap_start_scan (/S, ID=4/10) gap_stop_scan (/SX, ID=4/11) p_cyspp_start (.CYSPPSTART, ID=10/2) p_cyspp_get_parameters (.CYSPPGP, ID=10/4) 7.3.4.4 gap_scan_result (S, ID=4/4) Details about an advertisement or scan response packet. This event occurs while scanning for remote devices. If you have enable active scanning, most peripherals will provide two separate packets delivered via this API: one advertisement packet and one scan response packet.
PAGE 191
API Protocol Reference Text Info: Text Name Event Length C 0x0035 Notes None.
PAGE 192
API Protocol Reference Example Usage: • Section 3.5.5 (How to Disconnect from a Peripheral Device) 7.3.4.7 gap_connection_update_requested (UCR, ID=4/7) Remote peer has requested a connection parameter update. To accept or reject the new request, use the gap_send_connupdate_response (/CUR, ID=4/4) API command. An argument of “0” for that command will accept, and non-zero will reject.
PAGE 193
API Protocol Reference Event Parameters: Data Type Name Text Description uint8 conn_handle C Connection handle uint16 interval I Connection interval uint16 slave_latency L Slave latency uint16 supervision_timeout O Supervision timeout Related Commands: • • gap_update_conn_parameters (/UCP, ID=4/3) gap_send_connupdate_response (/CUR, ID=4/4) Related Events: • gap_connection_update_requested (UCR, ID=4/7) 7.3.
PAGE 194
API Protocol Reference Data Type Name uint16 Text type uint8 properties Description T Attribute type: • 0x2800 = Primary Service Declaration • 0x2801 = Secondary Service Declaration • 0x2802 = Include Declaration • 0x2803 = Characteristic Declaration • 0x2900 = Characteristic Extended Properties descriptor • 0x2901 = Characteristic User Description descriptor • 0x2902 = Client Characteristic Configuration descriptor • 0x2903 = Server Characteristic Configuration descriptor • 0x2904 = Characteristi
PAGE 195
API Protocol Reference Event Parameters: Data Type Name Text uint8 conn_handle C Handle of connection from which write came uint16 attr_handle H Attribute handle Write type: • 0x00 = Simple write – acknowledged • 0x01 = Write without response – unacknowledged • 0x80 = Simple write requiring manual response via API command uint8 type T longuint8a data D Description Written data NOTE: longuint8a data type requires two prefixed “length” bytes before binary parameter payload Related Commands
PAGE 196
API Protocol Reference Text Info: Text Name Event Length DGATT 0x0037-0x0057 Notes Variable-length event payload, minimum of 55 (0x37), maximum of 87 (0x57) Event Parameters: Data Type Name Text uint16 handle H Attribute handle (0x0001 – 0xFFFF) T* Attribute type: • 0x2800 = Primary Service Declaration • 0x2801 = Secondary Service Declaration • 0x2802 = Include Declaration • 0x2803 = Characteristic Declaration • 0x2900 = Characteristic Extended Properties descriptor • 0x2901 = Characteristic U
PAGE 197
API Protocol Reference 7.3.6 GATT Client Group (ID=6) GATT client methods relate to the client role of the Generic Attribute Protocol layer of the Bluetooth stack. These methods are used for working with the GATT structures on remote devices, and can only be used while a device is connected.
PAGE 198
API Protocol Reference Related Commands: • • • gattc_discover_services (/DRS, ID=6/1) gattc_discover_characteristics (/DRC, ID=6/2) gattc_discover_descriptors (/DRD, ID=6/3) Related Events: • gattc_remote_procedure_complete (RPC, ID=6/2) Example Usage: • Section 3.7.1 (How to Discover a Remote Server’s GATT Structure) 7.3.6.2 gattc_remote_procedure_complete (RPC, ID=6/2) Remote GATT client operation has completed.
PAGE 199
API Protocol Reference Binary Header: Type Length Group ID 80 05-19 06 03 Notes Variable-length event payload, minimum of 5 (0x05), maximum of 25 (0x19) Text Info: Text Name Event Length Notes D 0x0016-0x003E Variable-length event payload, minimum of 22 (0x16), maximum of 62 (0x3E) Event Parameters: Data Type Name Text uint8 conn_handle C Connection handle uint16 handle H Attribute handle Transfer source: • 0x00 = GATT client read request • 0x01 = GATT server notification • 0x02 =
PAGE 200
API Protocol Reference 7.3.7 SMP Group (ID=7) SMP methods relate to the Security Manager Protocol layer of the Bluetooth stack. These methods are used for working with encryption, pairing, and bonding between two peers.
PAGE 201
API Protocol Reference Event Parameters: Data Type Name Text Description uint8 conn_handle C Connection handle uint8 mode M Security level setting reported to peer: • 0x10 = Mode 1, Level 1 – No security • 0x11 = Mode 1, Level 2 – Unauthenticated pairing with encryption (no MITM) • 0x12 = Mode 1, Level 3 – Authenticated pairing with encryption (with MITM) • 0x21 = Mode 2, Level 2 – Unauthenticated pairing with data signing (no MITM) • 0x22 = Mode 2, Level 3 – Authenticated pairing with data sign
PAGE 202
API Protocol Reference 7.3.7.4 smp_encryption_status (ENC, ID=7/4) Encryption status has changed. This event confirms that a link has transitioned between plaintext and encrypted status during the pairing process. Binary Header: Type Length Group ID 80 02 07 04 Notes None. Text Info: Text Name Event Length ENC 0x000E Notes None.
PAGE 203
API Protocol Reference 7.3.7.6 smp_passkey_entry_requested (PKE, ID=7/6) Remote peer requested passkey entry during pairing. This event indicates that a remote device has generated and displayed a passkey which must be entered locally and sent back for comparison. If this occurs, you must reply with the smp_send_passkeyreq_response (/PE, ID=7/6) API command. If the pairing process completes successfully, EZ-Serial will generate the smp_pairing_result (PR, ID=7/3) API event with a success result code (0).
PAGE 204
API Protocol Reference Text Info: Text Name Event Length LCR 0x002C Notes None.
PAGE 205
API Protocol Reference 7.3.8.3 l2cap_data_received (LD, ID=8/3) Received a data block from remote peer over an open L2CAP channel. NOTE: L2CAP communication features within EZ-Serial are only available on devices with 256K of flash memory. The behavior described in this section will not function on devices with only 128K of flash.
PAGE 206
API Protocol Reference • l2cap_register_psm (/LRP, ID=8/3) Related Events: • • l2cap_connection_requested (LCR, ID=8/1) l2cap_connection_response (LC, ID=8/2) 7.3.8.5 l2cap_rx_credits_low (LRCL, ID=8/5) Open L2CAP channel connection has crossed the defined threshold for low remaining credits. NOTE: L2CAP communication features within EZ-Serial are only available on devices with 256K of flash memory. The behavior described in this section will not function on devices with only 128K of flash.
PAGE 207
API Protocol Reference Data Type Name Text Description uint16 channel N Channel ID uint16 credits Z Credits received Related Commands: • l2cap_send_data (/LD, ID=8/6) 7.3.8.7 l2cap_command_rejected (LREJ, ID=8/7) L2CAP command has been rejected by the remote peer. NOTE: L2CAP communication features within EZ-Serial are only available on devices with 256K of flash memory. The behavior described in this section will not function on devices with only 128K of flash.
PAGE 208
API Protocol Reference 7.3.9 GPIO Group (ID=9) GPIO methods relate to the physical pins on the module. Events within this group are listed below: • gpio_interrupt (INT, ID=9/1) Commands within this group are documented in Section 7.2.9, GPIO Group (ID=9). 7.3.9.1 gpio_interrupt (INT, ID=9/1) Configured GPIO interrupt has occurred. This event is generated for GPIO edge changes that have enabled interrupts via the gpio_set_interrupt_mode (SIOI, ID=9/9) API command.
PAGE 209
API Protocol Reference 7.3.10 CYSPP Group (ID=10) CYSPP methods relate to the Cypress Serial Port Profile. Events within this group are listed below: • p_cyspp_status (.CYSPP, ID=10/1) Commands within this group are documented in Section 7.2.10, CYSPP Group (ID=10). 7.3.10.1 p_cyspp_status (.CYSPP, ID=10/1) CYSPP operational status has changed.
PAGE 210
API Protocol Reference 7.3.11 CYCommand Group (ID=11) CYCommand methods relate to CYCommand remote configuration channel behavior. Events within this group are listed below: • p_cycommand_status (.CYCOM, ID=11/1) Commands within this group are documented in Section 7.2.11 CYCommand Group (ID=11). 7.3.11.1 p_cycommand_status (.CYCOM, ID=11/1) CYCommand operational status has changed.
PAGE 211
API Protocol Reference 7.4 Error Codes 7.4.1 EZ-Serial System Error Codes The complete list of all result/error codes generated by EZ-Serial is contained in the table below. Refer to the command and event reference material in Section 7.2 (API Commands and Responses) and Section 7.3 (API Events) for specific details about each result within the context of the responses and events where they are triggered. Table 7-5.
PAGE 212
API Protocol Reference Code (Hex) Name Description 0400 EZS_ERR_LL Link layer error category 0401 EZS_ERR_LL_CONTROLLER_BUSY Link layer controller busy 0402 EZS_ERR_LL_NO_DEVICE_ENTITY Device entity not available 0403 EZS_ERR_LL_NOT_IN_BOND_LIST Device not found in bond list 0404 EZS_ERR_LL_DEVICE_ALREADY_EXISTS Device already exists 0500 EZS_ERR_GAP GAP error category 0501 EZS_ERR_GAP_INVALID_CONNECTION_HANDLE Invalid connection handle specified 0502 EZS_ERR_GAP_CONNECTION_REQUIRE
PAGE 213
API Protocol Reference Code (Hex) Name Description 0906 EZS_ERR_SPEC_PIN_OR_KEY_MISSING PIN or Key Missing 0907 EZS_ERR_SPEC_MEMORY_CAPACITY_EXCEEDED Memory Capacity Exceeded 0908 EZS_ERR_SPEC_CONNECTION_TIMEOUT Connection Timeout 0909 EZS_ERR_SPEC_CONNECTION_LIMIT_EXCEEDED Connection Limit Exceeded 090A EZS_ERR_SPEC_SYNCHRONOUS_CONN_LIMIT _DEVICE_EXCEEDED Synchronous Connection Limit to a Device Exceeded 090B EZS_ERR_SPEC_ACL_CONNECTION_ALREADY_EXISTS ACL Connection Already Exists 090
PAGE 214
API Protocol Reference Code (Hex) Name Description 092D EZS_ERR_SPEC_QOS_REJECTED QoS Rejected 092E EZS_ERR_SPEC_CHANNEL_CLASSIFICATION _NOT_SUPPORTED Channel Classification Not Supported 092F EZS_ERR_SPEC_INSUFFICIENT_SECURITY Insufficient Security 0930 EZS_ERR_SPEC_PARAMETER_OUT_OF _MANDATORY_RANGE Parameter Out Of Mandatory Range 0931 /* 0x31 reserved */ Reserved 0932 EZS_ERR_SPEC_ROLE_SWITCH_PENDING = 0x0932 Role Switch Pending 0933 /* 0x33 reserved */ Reserved 0934 EZS_ERR_SPE
PAGE 215
API Protocol Reference 7.5 Macro Definitions Macros in EZ-Serial are simple codes which result in text substitution within the parser. Macros may be used in either text mode or binary mode. Macros always begin with the ‘%’ character and are followed by one or more alphanumeric characters (A-Z, 0-9). Macros are not case sensitive.
PAGE 216
8. GPIO Reference This section describes the various GPIO connections provided by the EZ-Serial firmware on supported modules. It also provides details on the default boot state and what behavior to expect in different operational modes. 8.1 GPIO Pin Map for Supported Modules The EZ-Serial firmware can be run on multiple Cypress BLE modules, some of which have unique pin configurations. The assignment of special functions for supported modules is described in Table 8-1.
PAGE 217
GPIO Reference 8.2 GPIO Pin Functionality EZ-Serial provides 12 special-function digital GPIO pins, four optional PWM output pins for generating flexible PWM signals, and one optional analog input pin for ADC reads. 8.2.1 Digital Special-Function Pins Table 8-2 below details the functionality of each digital function GPIO pin.
PAGE 218
GPIO Reference Pin Name Direction Details Optional CP_ROLE Input Description: Central or peripheral GAP role selection for CSYPP operation. The external host can use this pin to select which role the module should use for CYSPP behavior. This pin is also internally pulled high or low based on software-triggered GAP behavioral state. If connected to a high-impedance input pin (weaker than 5.6k pull), this pin may be used as a status indicator for software-based GAP role changes.
PAGE 219
GPIO Reference Pin Name Direction Details Optional FACTORY_TR Input Description: Factory test or reset control. The external host can use this pin to boot into a manufacturing test mode (CYSPP pin high), or to trigger a complete reset of all settings back to their factory default values (CYSPP pin low), similar to what happens when the “system_factory_reset” API command is used (“/SFAC” in text mode).
PAGE 220
GPIO Reference 8.2.3 Analog Input Pins (ADC) EZ-Serial provides a single dedicated ADC input pin (ADC0) for reading analog voltages. The ADC supports an input voltage range of 0 V minimum to 1.024 V maximum. To perform a single ADC conversion, use the gpio_query_adc (/QADC, ID=9/2) API command. Once the conversion completes, the module will transmit the result in the response to this command.
PAGE 221
9. Cypress GATT Profile Reference The EZ-Serial platform makes use of a few custom GATT profiles defined by Cypress Semiconductor. The service UUIDs, characteristic UUIDs, special permissions, and overall structure are outlined here for quick reference. Much more detailed reference material can be found on the Cypress website here: http://www.cypress.com/documentation/software-and-drivers/cypresss-custom-ble-profiles-and-services 9.
PAGE 222
Cypress GATT Profile Reference The EZ-Serial firmware is able to fully track every transfer in both directions. This characteristic has a variable length, supporting transfers in each direction of up to 20 bytes per packet.  o Configuration Descriptor: Unacknowledged Data Characteristic: (Write without response, Notify) UUID 0x2902 UUID 65333333-A115-11E2-9E9A-0800200CA102 The Unacknowledged Data Characteristic is used to send and receive data in an unacknowledged fashion.
PAGE 223
10. Configuration Example Reference The configuration examples provided in this section are each designed to work independently, assuming in each case that the platform is initially configured using factory default settings. Applying all of the commands in one example and then immediately following this with the commands from another example may result in changes to the first set of behavior that are no longer in line with the expected results.
PAGE 224
Configuration Example Reference 10.2 Adopted Bluetooth SIG GATT Profile Structure Snippets The snippets below demonstrate how to add various GATT service and characteristic structural elements in order to support official profiles defined by the Bluetooth SIG, and some other common services. NOTE: These database structures concern only the GATT server side of the profiles in question. GATT client operations depend on the client device.
PAGE 225
Configuration Example Reference 10.2.1 Generic Access Service (0x1800) Official documentation for this service can be found on the Bluetooth SIG Developer website. NOTE: This service is include in the EZ-Serial application. It is always present in the fixed, nonremovable part of the GATT structure. Do not add another instance of this service to the EZ-Serial application.
PAGE 226
Configuration Example Reference /CAC,T=2803,R=01,W=00,C=02,L=0000,D=142A /CAC,T=0000,R=01,W=00,C=02,L=0004,D= 10.2.7 Reference Time Update Service (0x1806) Official documentation for this service can be found on the Bluetooth SIG Developer website. /CAC,T=2800,R=01,W=00,C=00,L=0000,D=0618 /CAC,T=2803,R=01,W=00,C=04,L=0000,D=162A /CAC,T=0000,R=02,W=02,C=04,L=0001,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=172A /CAC,T=0000,R=01,W=00,C=02,L=0002,D= 10.2.
PAGE 227
Configuration Example Reference /CAC,T=2803,R=01,W=00,C=02,L=0000,D=252A /CAC,T=0000,R=01,W=00,C=02,L=0010,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=272A /CAC,T=0000,R=01,W=00,C=02,L=0010,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=262A /CAC,T=0000,R=01,W=00,C=02,L=0010,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=282A /CAC,T=0000,R=01,W=00,C=02,L=0010,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=232A /CAC,T=0000,R=01,W=00,C=02,L=0008,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=2A2A /CAC,T=0000,R=01,W=00,C=02,L=0001,D= /CAC,T=2803
PAGE 228
Configuration Example Reference 10.2.16 Alert Notification Service (0x1811) Official documentation for this service can be found on the Bluetooth SIG Developer website.
PAGE 229
Configuration Example Reference /CAC,T=2803,R=01,W=00,C=02,L=0000,D=5D2A /CAC,T=0000,R=01,W=00,C=02,L=0001,D= /CAC,T=2803,R=01,W=00,C=28,L=0000,D=552A /CAC,T=0000,R=02,W=02,C=28,L=0006,D= /CAC,T=2902,R=01,W=01,C=0A,L=0002,D= 10.2.20 Cycling Speed and Cadence Service (0x1816) Official documentation for this service can be found on the Bluetooth SIG Developer website.
PAGE 230
Configuration Example Reference 10.2.23 Body Composition Service (0x181B) Official documentation for this service can be found on the Bluetooth SIG Developer website. /CAC,T=2800,R=01,W=00,C=00,L=0000,D=1B18 /CAC,T=2803,R=01,W=00,C=02,L=0000,D=9B2A /CAC,T=0000,R=01,W=00,C=02,L=0004,D= /CAC,T=2803,R=01,W=00,C=20,L=0000,D=9C2A /CAC,T=0000,R=00,W=00,C=20,L=002A,D= /CAC,T=2902,R=01,W=01,C=0A,L=0002,D= 10.2.
PAGE 231
Configuration Example Reference /CAC,T=0000,R=01,W=01,C=0A,L=0001,D= /CAC,T=2803,R=01,W=00,C=0A,L=0000,D=822A /CAC,T=0000,R=01,W=01,C=0A,L=0001,D= /CAC,T=2803,R=01,W=00,C=0A,L=0000,D=8B2A /CAC,T=0000,R=01,W=01,C=0A,L=0004,D= /CAC,T=2803,R=01,W=00,C=0A,L=0000,D=942A /CAC,T=0000,R=01,W=01,C=0A,L=0002,D= /CAC,T=2803,R=01,W=00,C=0A,L=0000,D=952A /CAC,T=0000,R=01,W=01,C=0A,L=0001,D= /CAC,T=2803,R=01,W=00,C=0A,L=0000,D=992A /CAC,T=0000,R=01,W=01,C=0A,L=0004,D= /CAC,T=2902,R=01,W=01,C=0A,L=0002,D= /CAC,T=2803,R=0
PAGE 232
Configuration Example Reference 10.2.28 Environmental Sensing Service (0x181A) The complete implementation of every supported sensor data characteristic within this service will not fit within EZ-Serial’s dynamic GATT implementation due to flash limits. The reference code lists 124 attribute definitions, but only 102 can fit (38 on devices with 128K of flash memory) as described in Section 3.6.1 (How to Define Custom Local GATT Services and Characteristics).
PAGE 233
Configuration Example Reference /CAC,T=290C,R=01,W=00,C=02,L=000B,D= /CAC,T=290D,R=01,W=00,C=02,L=0002,D= /CAC,T=2901,R=01,W=00,C=02,L=0000,D= /CAC,T=2906,R=01,W=00,C=02,L=0006,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=782A /CAC,T=0000,R=01,W=00,C=02,L=0002,D= /CAC,T=290C,R=01,W=00,C=02,L=000B,D= /CAC,T=290D,R=01,W=00,C=02,L=0002,D= /CAC,T=2901,R=01,W=00,C=02,L=0000,D= /CAC,T=2906,R=01,W=00,C=02,L=0004,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=6D2A /CAC,T=0000,R=01,W=00,C=02,L=0004,D= /CAC,T=290C,R=01,W=00,C=02,
PAGE 234
Configuration Example Reference /CAC,T=2906,R=01,W=00,C=02,L=0004,D= /CAC,T=2803,R=01,W=00,C=02,L=0000,D=A12A /CAC,T=0000,R=01,W=00,C=02,L=0006,D= /CAC,T=290C,R=01,W=00,C=02,L=000B,D= /CAC,T=290D,R=01,W=00,C=02,L=0002,D= /CAC,T=2901,R=01,W=00,C=02,L=0000,D= /CAC,T=2906,R=01,W=00,C=02,L=0004,D= 10.2.29 HTTP Proxy Service (0x1823) Official documentation for this service can be found on the Bluetooth SIG Developer website.
PAGE 235
Revision History , Document Title: EZ-Serial BLE Firmware Platform User Guide Document Number: 002-11259 Revision Issue Date Origin of Change Description of Change ** 4/29/2016 JROW New user guide draft. *A 6/29/2016 JROW Applied technical review edits. *B 9/27/2016 JROW Updated for new EZ-Serial patch release v1.0.1 build 14, adding support for eight additional modules. • Minor typo, grammar, and formatting fixes • 1, 1.3, 3.10.3, 3.11.2, 7.2.3, 7.2.3.1, 7.2.8, 7.2.8.1, 7.2.8.2, 7.2.8.
PAGE 236
Revision History in command list, fix duplicate gap_set_adv_parameters in command list • 7.2.5.1, 7.2.5.2, 10.2 – Add details about flash write side effects • 7.2.9 – Note GPIO example applies to one specific module • 7.2.9.2 – Clarify new behavior with gpio_query_adc command • 7.2.10.3, 7.2.10.4 – Add “flags” details to CYSPP get/set commands • 7.2.11.2 – Fix incorrect subheadings for command/response arguments • 7.4.
PAGE 237
Revision History • Modify "l2cap_register_psm" command: add "watermark" parameter • Modify "l2cap_send_connreq_response" command: add "mps" parameter • Modify "l2cap_send_data" command: rename "conn_handle" parameter to "C" in text mode • Modify "l2cap_rx_credits_zero" event: rename to "l2cap_rx_credits_low", add "credits" parameter • Modify "gpio_query_adc" command: rename "channel" parameter to "N" in text mode, add "reference" parameter, add "value" and "uvolts" as immediate response parameters
PAGE 238
Revision History *D 07/10/2017 JROW Updated for new EZ-Serial minor release v1.1.0 build 25, adding bugfixes and support for CYSPP packetization and fixed passkey features. • 1.3.3: Add section about development limitations • 1.4, 2.2, 2.4.1.3, 2.4.2.2, 3.1.1.1, 3.1.1.2, 3.1.6.2, 3.2.1.1, 3.2.1.2: Update version details to v1.1.0.25, BLE v3.3.0.53, protocol v1.3 • 2.4.3: Clarify default/preset values in text mode • 2.4.5.2: Fix "CSYPP" typo • 2.4.5.4: Add CYSPP packetization summary • 3.1.5.
PAGE 239
Revision History • *E 9/14/2017 JROW 7.4.1, 7.4.2: Update table reference numbers • 8.1: Add CYBLE-212020-01 and CYBLE-214015-01 modules to table • 10.1: Add .CYSPPSK setting to factory default list Updated for new EZ-Serial patch release v1.1.1 build 26 • 1.4, 2.2, 2.4.1.3, 2.4.2.2, 3.1.1.1, 3.1.1.2, 3.1.6.2, 3.2.1.1, 3.2.1.2: Update version details to v1.1.1.26 • 7.3.3.1: Update app-related bootloader version details EZ-Serial BLE Firmware Platform User Guide, Doc. No. 002-11259 Rev.
PAGE 240
FCC Statement FCC standards: FCC CFR Title 47 Part 15 Subpart C Section 15.247 Integral antenna with antenna gain 3.3dBi This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation.
PAGE 241
IC STATEMENT This device contains licence-exempt transmitter(s)/receiver(s) that comply with Innovation, Science and Economic Development Canada’s licence-exempt RSS(s). Operation is subject to the following two conditions: (1) This device may not cause interference.