sample project:DeviceManager.kt,DeviceConnectDialogFragment.kt

Use FcConnector to connect/control the device, which is also the most important class in the SDK.

Use the FcSDK to obtain the FcConnector, and then use connect/close to control the connection.

val connector = fcSDK.connector
...
connector.connect(..)
...
connector.close()

connect and close

connect

connect and close are the most important connection methods.

FcConnector will hold the devices passed in by the connect method. If the device disconnects, it will reconnect at the appropriate time. Such as at a certain interval of time, when the Bluetooth Adapter is available, the app enters the foreground and the phone screen on, etc.

So, you don't need to perform your own reconnect code outside of the SDK, and it is highly discouraged.

fun connect(
    address: String,
    userId: String,
    bindOrLogin: Boolean,
    sex: Boolean,
    age: Int,
    height: Float,
    weight: Float
)

The parameters of the connect method are very important. If incorrect parameters are passed in, it may be unable to connect or clear the device's data.

• device/address

  The device/address will be held for reconnection until the close method is called or FcAuthException is thrown.

• auth info

  After the device is connected, the userId and bindOrLogin are used to authenticate the device.

  If bindOrLogin is true(BIND mode), it is considered that this user connects to the device for the first time, and the device will clear the old data(steps,sleep,heart rate,etc...) on the device.

  If bindOrLogin is false(LOGIN mode), the device will check whether the last authenticated userId is the same as this userId. If not, observerConnectorError will emit FcAuthException and terminate the connection.

• user info

  Some calculations on the device will use the user info. Every time the user info changes, you can use the connect method to setting the changed data.

Authorization info userId and bindOrLogin need to be maintained by the developers themselves.

For a new user, when you connect the device for the first time, you need to select the BIND mode. After the bind is successful, the next time you connect, you need to select the LOGIN mode.

If your application does not have an account system or needs to bind the device before the user can log in, you can always use a fixed userId, or use the unique serial number of the mobile phone as userId

close

close method will immediately disconnect the device, and clear the device hold by the FcConnector.

Usually, you only use the close method when you don't need this device anymore, and in this case, you usually need to consider using it in conjunction with Unbind.

observer connection state and error

Use observerConnectorState to observer FcConnectorState.

enum class FcConnectorState {

    /**
     * No connection or no connection being attempted. Usually it will be in this state in the following situations:
     * 1. Initial state
     * 2. [FcBaseConnector.close] method called
     * 3. [BluetoothAdapter] turned off
     * 4. [FcAuthException] occurs
     */
    DISCONNECTED,

    /**
     * Although the device is not connected at this time, it will make the next connection after waiting for a certain period of time.
     */
    PRE_CONNECTING,

    /**
     * Actually trying to connect(contains scan the device before connect).
     */
    CONNECTING,

    /**
     * Device connected but not prepared. After the connection is established, some basic settings are required. At this time, external operation of this device is not allowed.
     */
    PRE_CONNECTED,

    /**
     * Device connected and prepared. Now, you can interact with the device.
     */
    CONNECTED;
}

There are some methods that can help you better understand the details of the connection.

getConnectorState: Immediately get current connection state.

getDevice: Get the device(may be null) held by this connector if exist.

getDisconnectedReason:When FcConnectorState.DISCONNECTED is emit, get the disconnected reason.

getNextRetryTime:When FcConnectorState.PRE_CONNECTING is emit, get the next retry connect time.

isBindOrLogin:When FcConnectorState.CONNECTED is emit, get the current connect is BIND or LOGIN mode.

Use observerConnectorError to observer FcConnectorError. When a FcConnectorError is emit, don't necessarily mean that the current state is FcConnectorState.DISCONNECTED, because the connector may continue to be reconnect. You can determine whether reconnect use FcConnectorError.retryContinue.

disconnect and reconnect

The disconnect and reconnect are not commonly used.

Different from the close method. The disconnect method does not clear device hold by FcConnector. Similarly, the reconnect method only triggers the connection of the device held.

When you need to temporarily disconnect, you can use the disconnect method. Afterwards, the reconnect method can be used to connect.

It should be noted that even if you do not call reconnect, the connection may still trigger, such as when the app enters the foreground, because FcConnector held the device in the internal.

Unbind

The close method will disconnect the device, but the userId you passed in through the connect method is still saved on the device. Your can use FcSettingsFeature.unbindUser to clear the userId. This can immediately clear the data of this user on the device.

In addition, some devices will have dual mode Bluetooth, and the close method only closes the BLE Bluetooth connection. You can use FcSettingsFeature. unbindAudioDevice to remove the Classic Bluetooth connection.

There are usually two different strategies for unbinding：

1. Unbind and clear user data

connector.settingsFeature().unbindUser().ignoreElement().onErrorComplete()
    .andThen(connector.settingsFeature().unbindAudioDevice().onErrorComplete())
    .andThen(Completable.fromAction { 
        connector.close()
    })
    .subscribe()

2. Unbind and keep user data

connector.settingsFeature().unbindAudioDevice().onErrorComplete()
    .andThen(Completable.fromAction {
        connector.close()
    })
    .subscribe()

It should be noted that keeping data does not mean that data will always exist. If the userId of the next connect does not match the previous one, the data will still be cleared.

Reconnect strategy

FcConnector will try to maintain a connection with the device as much as possible.

When the device disconnects or fails to connect, it will delay for 5 seconds in attempting to reconnect.

But when the app is in the background, the attempt time will increase with the number of failures, in order to save power.

You can enable high-frequency reconnection in the background through FcSDK.setReConnectFrequent.

In addition, after the connection is disconnected, the following scenarios will also trigger a reconnection:

• The Bluetooth Adapter is available
• The app enters the foreground
• The phone screen on