# LBLEClient 此類別允許使用者連線到其他的低功耗藍牙周邊裝置。 若欲存取其他低功耗藍牙周邊裝置，首先請建構一個 **LBLEClient** 物件，然後呼叫 **LBLEClient::connect(address)** 來連接到該裝置所對應的裝置地址，如下： ``` // assume LBLECentral::scan has already performed. // connect to the 1st device scanned. LBLEClient client; LBLEAddress serverAddress = LBLECentral.getBLEAddress(0); client.connect(serverAddress); while(!client.connected()){ delay(100); } // now we are connnected. ``` 如果連線成功的話，**client.connected()** 將會回傳 true。 接著，搜尋該裝置是否支援開發者所需要的服務，可以透過這幾個 API 來使用： * **getServiceCount()** * **getServiceUuid(index)** * **hasService(uuid).** 當確認該裝置上面有所需的服務之後，可以利用不同的 API 來讀寫該服務所提供的資料特性。此時有兩個選擇： * 根據資料特性的 UUID 來讀寫：如果本來就知道要讀寫的資料特性的 UUID 的話，此方法相當簡便。然而，有些情況，同一個裝置的不同服務，是有可能會提供相同 UUID 的資料特性的。用這個方法的話，最終可能會存取到意料之外的資料特性。 * 根據資料特性的流水號來讀寫：開發者要先取得每一個服務的流水號，再取得每一個服務當中的每一個資料特性的流水號，並搜尋自己所需要的資料特性的 UUID。最後，可以根據服務與特性的流水號來進行讀寫。利用這個方法，需要呼叫比較多的 API，但好處是可以處理有相同的 UUID 的資料特性的情形。 要注意的是，在讀寫資料特性時，LBLE 程式庫不會進行任何的型別檢查。所以，必須自行確保讀寫的資料特性的資料型別，在周邊裝置跟主控裝置上面都是一致的。 ### Constructors LBLEClient {% tabs %} {% tab title="First Tab" %} 建構一個可以連線到周邊裝置的 LBLEClient 物件。 **Syntax** **Parameters** none **Returns** LBLEClient 物件 {% endtab %} {% endtabs %} ### Connection Methods connect() connected() disconnect() {% tabs %} {% tab title="connect()" %} 根據裝置地址，開始連接至一個低功耗藍牙周邊裝置。 你可以利用 **LBLECentral** 單件來掃描鄰近的周邊裝置以及其對應的裝置地址。 呼叫此函式之後，可透過不斷呼叫 **connected()** 方法來確認是否已經成功完成連線。請注意，連線過程當中，程式庫會列舉遠端裝置的服務以及資料特性，所以會需要一些時間才能完成連線。 **Syntax** **Parameters** none **Returns** 回傳 true：開始連線。請注意，這並不代表連線已經完成。 回傳 false：無法開始連線。 {% endtab %} {% tab title="connected()" %} 檢查連線是否已經完成。 **Syntax** **Parameters** none **Returns** 回傳 true：已經連線成功。 回傳 false：尚未連線成功。 {% endtab %} {% tab title="disconnect()" %} 從遠端裝置斷線。 **Syntax** *client*.disconnect(); **Parameters** none **Returns** none {% endtab %} {% endtabs %} ### Service Methods hasService() getServiceCount() getServiceName() getServiceUuid() getCharacteristicCount() {% tabs %} {% tab title=" hasService()" %} 查詢遠端的周邊裝置是否有此 UUID 對應的服務。 **Syntax** bool serviceAvailable = *client*.hasService(serviceUUID); **Parameters** serviceUUID 128-bit or 16-bit UUID to identify the service. **Returns** 回傳 true：遠端的周邊裝置有支援此服務，反之則回傳 false。 {% endtab %} {% tab title=" getServiceCount()" %} 查詢遠端的周邊裝置所支援的服務數量 **Syntax** int serviceCount *= client*.getServiceCount(); **Parameters** none **Returns** 遠端裝置所支持的服務的數量。 {% endtab %} {% tab title="getServiceName()" %} 這個幫手 API 可以協助查詢某個 service 是否有已知的名字。 **Syntax** String serviceName = *client*.getServiceName(serviceIndex); **Parameters** serviceIndex 介於 0 到 (getServiceCount() - 1) 之間的流水號 **Returns** 該 Service 的名字。 {% endtab %} {% tab title=" getServiceUuid()" %} 根據服務的流水號，取得其 UUID。 **Syntax** LBLEUuid uuid = *clinet*.getServiceUuid(serviceIndex); **Parameters** | | | | ------------ | ------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | **Returns** 該服務的 UUID。 {% endtab %} {% tab title=" getCharacteristicCount()" %} 取得服務當中的資料特性的數目。 **Syntax** LBLEUuid uuid = *clinet*.getCharacteristicCount(serviceIndex); **Parameters** | | | | ------------ | ------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | **Returns** 服務當中的資料特性的數目。 {% endtab %} {% endtabs %} ### Characteristic Methods getCharacteristicUuid() readCharacteristicString() readCharacteristicInt() writeCharacteristicFloat() writeCharacteristicString() writeCharacteristicInt() writeCharacteristicFloat() {% tabs %} {% tab title="getCharacteristicUuid()" %} 根據流水號取得資料特性的 UUID **Syntax** LBLEUuid uuid = *clinet*.getCharacteristicUuid(serviceIndex, characteristicIndex); **Parameters** | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** 該流水號所對應的資料特性的UUID {% endtab %} {% tab title="readCharacteristicString()" %} 從遠端的周邊裝置讀取一個資料特性的值，並以字串形式呈現。 **Syntax** String value = *client.*readCharacteristicString(uuid) String value = *client.*readCharacteristicString(serviceIndex, characteristicIndex) **Parameters** | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** 該資料特性的數值，以字串型別表示。如果讀取失敗，則回傳空字串。 {% endtab %} {% tab title="readCharacteristicInt()" %} 從遠端的周邊裝置讀取一個資料特性的值，並以整數形式呈現。 **Syntax** int value = *client.*readCharacteristicInt(uuid) int value = *client.*readCharacteristicInt(serviceIndex, characteristicIndex) **Parameters** | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** 該資料特性的數值，以整數型別表示。如果讀取失敗，則回傳 0。 {% endtab %} {% tab title="writeCharacteristicFloat()" %} 從遠端的周邊裝置讀取一個資料特性的值，並以浮點數形式呈現。 **Syntax** float value = *client.*readCharacteristicFloat(uuid) float value = *client.*readCharacteristicFloat(serviceIndex, characteristicIndex) **Parameters** | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** 該資料特性的數值，以浮點數型別表示。如果讀取失敗，則回傳 0.0f。 {% endtab %} {% endtabs %} {% tabs %} {% tab title="writeCharacteristicString()" %} 將字串資料寫入遠端周邊裝置的特性。 **Syntax** *client*.writeCharacteristicString(uuid, string\_to\_write) *client*.writeCharacteristicString(serviceIndex, characteristicIndex, string\_to\_write) **Parameters** | uuid | 要存取的資料特性的 UUID | | ----------------- | -------------- | | string\_to\_write | 要寫入的字串值 | | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** \>0 ：表示寫入成功。 0 ： 表示寫入失敗。 {% endtab %} {% tab title="writeCharacteristicInt()" %} 將一個整數資料寫入遠端周邊裝置的特性。 **Syntax** *client*.writeCharacteristicString(uuid, int\_value) *client*.writeCharacteristicString(serviceIndex, characteristicIndex, int\_value) **Parameters** | uuid | 要存取的資料特性的 UUID | | ---------- | -------------- | | int\_value | 要寫入的數值 | | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** \>0 ：表示寫入成功。 0 ： 表示寫入失敗。 {% endtab %} {% tab title=" writeCharacteristicFloat()" %} 將一個浮點數資料寫入遠端周邊裝置的特性。 **Syntax** *client*.writeCharacteristicString(uuid, float\_value) *client*.writeCharacteristicString(serviceIndex, characteristicIndex, float\_value) **Parameters** | uuid | 要存取的資料特性的 UUID | | ------------ | -------------- | | float\_value | 要寫入的數值 | | | | | ------------------- | -------------------------------------------------------- | | serviceIndex | 介於 0 到 (getServiceCount() - 1) 之間的流水號 | | characteristicIndex | 介於 0 到 (getCharacteristicCount(serviceIndex) - 1) 之間的流水號 | **Returns** \>0 ：表示寫入成功。 0 ： 表示寫入失敗。 {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cavedu.gitbook.io/linkit-7697/linkit-7697-arduinoide/kai-fa-zhi-nan/shi-yong-ble-di-gong-hao-lan-ya/lble-api-zhi-nan/lbleclient.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.