Skip to content

GoFIT SDK Android Application Programming Interface Specifications

Robbinsisbatman edited this page Jun 10, 2021 · 7 revisions

GoFIT SDK Android Application Programming Interface Specifications

Scope

The present document specifies the base version of GoFIT SDK - Android Application Programming Interfaces (API's).

Terms and Definitions

  • 裝置 (Device)
    • 本 SDK 之目標物、連接對象;為手錶、手環。
  • API's
    • Application Programming Interfaces.
    • Particularly, in the present document, API's (Application Programming Interfaces) 特指 function / method 等可呼叫之類型的介面
  • Data Object
    • 在 API's 之外,還有其所關聯到的資料物件,或資料結構。In the present document, they are called Data Object (s). 為 data model.
  • 健康資料 (Fitness Data)
  • SDK vs. Client
    • SDK 指的即為本文件所描述的程式套件
    • Client 特指使用本文件所描述的程式套件之客戶端 (i.e., 本 SDK 的 user / caller)

API's

  • 本 SDK 以 Singleton Pattern 形式呈現並提供所需服務 / 功能. 各 method 若有 callback 者, 則在 callback 完成前, 都不允許再次呼叫 (本 SDK 非 reentrant, 非 multi-threaded 使用).
  • Unless otherwise specified, all the (Java) Interfaces defined below are all of scope GoFITSdk (i.e., these Interfaces are defined nested inside GoFITSdk).

SDK Instance

  • GoFITSDK GoFITSdk.getInstance(
        android.content.Context context, 
        String certificate, 
        String license, 
        GoFITSDK.ReceivedLicenseCallback receivedLicenseCallback
    );
    • 功能
      • 取得 GoFIT SDK singleton instance
    • Parameters
      • context
        • Client application's context (e.g., Activity or Service)
      • certificate
        • GOLiFE offered certificate (sequence of bytes); mandatory.
      • license
        • License (sequence of bytes). Will download license from GOLiFE server (i.e., AAA procedure will be executed, and authorized license, if passed, will be returned via GoFITSDK.ReceivedLicenseCallback.success() callback) in case this parameter is null. Client shall store received license -- otherwise this license download operation will occur each time this singleton is initiated (and thus network is required every time).
      • receivedLicenseCallback
        public interface ReceivedLicenseCallback {
            public void onSuccess(String receivedLicense);
            public void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 傳回取得的 license 給 Client (若 AAA 成功 pass 的話)
        • (callback) onSuccess() : 成功
          • String retrievedLicense : 取得的 license
        • (callback) onFailure() : 程序失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • GoFIT SDK singleton instance, of type GoFITSDK, if success. null otherwise.
    • Example :
      import com.goyourlife.gofitsdk.GoFITSdk;
      ...
      public class SdkUser extends AppCompatActivity {
          private static GoFITSdk _goFITSdk;
          private static String _certificate;
          ...
          public void init() {
              ...
              _goFITSdk = GoFITSdk.getInstance(
                  this, 
                  _certificate, 
                  null,   // In case this is the very first time the SDK is activated
                  new GoFITSDK.ReceivedLicenseCallback {
                      public void onSuccess(String receivedLicense) {
                          // Store received license
                      }
                      public void onFailure(int errorCode, String errorMsg) {
                          // Do error handling
                      }
              });
              ...
          }
          ...
      }

Scan Device

  • public void doScanDevice(
        final DeviceScanCallback scanCallback
    );
    • 功能
      • 掃瞄裝置
    • 參數
      • scanCallback
        public interface GenericCallback {
            void onSuccess();
            void onFailure(int errorCode, String errorMsg);
        }
        
        public interface DeviceScanCallback {
            public void onSuccess(ScanBluetoothDevice device, String productID);
            public void onCompletion(HashMap<ScanBluetoothDevice, String> devices);
            public void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 回傳掃瞄結果
        • (callback) onSuccess() : 會不斷更新,每掃描到一個新的 device 即 callback
        • (callback) onCompletion() : 掃描完成
          • devices : 所有掃描到的 devices
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
      • Timeout : 10 秒 (10 秒後回傳 scan 結果)
    • Return
      • void
    • Example :
      ...
      _goFITSdk.doScanDevice(new GoFITSdk.DeviceScanCallback() {
          @Override
          public void onSuccess(ScanBluetoothDevice device, String productID);
              Log.i(tag, 
                     "DeviceScanCallback.onSuccess() : device (" + productID 
                          + ") = " + device.toString()
              );
          }
      
          @Override
          public void onCompletion(HashMap<ScanBluetoothDevice, String> devices) {
              for (Map.Entry<ScanBluetoothDevice, String> deviceEntry : devices.entrySet()) {
                  ScanBluetoothDevice device = deviceEntry.getKey();
                  String productID = deviceEntry.getValue();
                  Log.i(tag, 
                      "DeviceScanCallback.onCompletion() : device (" + productID 
                          + ") = " + device.getDevice().getName() + ", " 
                          + device.getDevice().getAddress() + ", " 
                          + device.getRSSI()
                  );
              }
          }
      
          @Override
          public void onFailure(int errorCode, String errorMsg) {
              Log.i(tag, 
                  "DeviceScanCallback.onFailure() : errorCode = " + errorCode 
                      + ", errorMsg = " + errorMsg
              );
          }
      });
      ...

New Pairing Device

  • public void doNewPairing(
        ScanBluetoothDevice device, 
        String productID, 
        final NewPairingCallback newPairingCallback
    );
    • 功能
      • 新配對裝置,不帶有配對碼的連線機制
    • 參數
      • device

        • The device to pair. Shall be one of the devices returned via DeviceScanCallback of Scan Device
      • productID

        • 上述 device 之 product ID (與上述 device 一同在 Scan Device 時期所傳回)
      • newPairingCallback

        public interface NewPairingCallback extends GenericCallback {
            void onSuccess(String pairingCode, String pairingTime);
        }
        • 功能
          • 回傳配對碼
        • (callback) onSuccess() : 成功連線並取回配對碼
          • pairingCode : 帶著裝置螢幕顯示之四位字元 (ASCI value 0x30 ~ 0x39。字串的字元依序為裝置上顯示之順序)。
          • pairingTime : 配對碼於裝置上生成的時間 (裝置螢幕不顯示)
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message

Confirm Pairing Code

  • public void doConfirmPairingCode(
        String pairingCode, 
        String pairingTime, 
        String productID, 
        final GenericCallback confirmPairingCallback
    );
    • 功能
      • 確認輸入的配對碼,完成裝置配對機制
    • 參數
      • context
        • Client application's context (e.g., Activity or Service)
      • pairingCode : 輸入裝置螢幕顯示之四字元配對碼
      • pairingTime : 於上述 New Pairing DeviceNewPairingCallback 取得之 pairingTime
      • productID
        • 欲連線裝置之 Product ID。必須為之前透過 Scan Device 所回傳者,且與當時回傳之 device 成對。此參數之值應亦等同於呼叫 New Pairing Device 時所傳入者。
      • confirmPairingCallback
        • 功能
          • 回傳配對結果
        • (callback) onSuccess() : 配對成功
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Connect Device

  • public void doConnectDevice(
        String macAddress, 
        String pairingCode, 
        String pairingTime, 
        String productID, 
        final GenericCallback connectDeviceCallback
    );
    • 功能
      • 帶有配對碼的連線機制,適合已配對過的裝置
      • 傳入裝置之 macAddresspairingCodepairingTime 以連接裝置
      • 此 API 會連帶執行手環時間校正功能
    • 參數
      • macAddress : 裝置之 MAC address. 可為 null, 但將較為耗時, 請於為了無痛跨手機系統平台時使用 (手機; e.g., iOS ⇒ Android). 但即使是此種 case, 您也應該盡量透過 Get Device MAC Address 預先取得 MAC address 並儲存下來,以利日後跨手機系統平台時的速度。
      • pairingCode : 裝置配對碼
      • pairingTime : 裝置配對時間戳記
      • productID
        • 欲連線裝置之 Product ID。必須為之前透過 Scan Device 所回傳者,且與當時回傳之 device 成對。此參數之值應亦等同於呼叫 New Pairing Device 時所傳入者。
      • connectDeviceCallback
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void
    • Timeout : 5 秒 (若 5 秒內連不上目標裝置,則 callback fail)

Get Fitness Data

  • public void doSyncFitnessData(
        final SyncCallback syncCallback
    );
    • 功能
      • 同步手環上所有健康資料
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • (callback) syncCallback :

        public interface SyncCallback {
            public void onProgress(String message, int totalProgress, int progressNow);
            public void onGetFitnessData(
                ArrayList<TableStepRecord> stepRecords, 
                ArrayList<TableSleepRecord> sleepRecords, 
                ArrayList<TablePulseRecord> hrRecords
            );
            public void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 回傳同步結果
        • (callback) onProgress() :
          • message : 文字訊息;表示正在同步中的項目
          • progress : 表示目前 sync 進度 (單純為一累進數值; 無)
        • (callback) onGetFitnessData() :
          • stepRecords : 請參考 TableStepRecord (每 20 分鐘為一筆)
          • sleepRecords : 請參考 TableSleepRecord
          • hrRecords : 請參考 TablePulseRecord
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Device Settings

  • public void doSetSettings(
        SetCareSetting settings, 
        final SettingsCallback settingsCallback
    );
    • 功能

      • 設定手環功能
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數

      • settings : 請參考 SetCareSetting Data Object

      • (callback) settingsCallback :

        public interface SettingsCallback {
            public void onCompletion();
            public void onProgress(String message);
            public void onFailure(int errorCode, String cause);
        }
        • 功能
          • 回傳設定結果
        • (callback) onCompletion() : 表示完成
        • (callback) onProgress() :
          • message : 文字訊息;表示正在設定中的項目
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return

      • void
    • GoFITSdk provides a helper method GoFITSdk.getDefaultCareSettings() that returns a object of type SetCareSettings populated with default settings, for example :

      GoFITSdk _goFITSdk = GoFITSdk.getInstance(...);
      
      ...
      
      // Demo - new Setting object
      SetCareSetting mCareSettings = _goFITSdk.getDefaultCareSettings();
      
      // Demo - generate system unit setting
      String systemUnit = mCareSettings.getSystemUnit();
      systemUnit = "imperial";
      mCareSettings.setSystemUnit(systemUnit);
      
      // Demo - generate time format setting
      String timeFormat = mCareSettings.getTimeFormat();
      timeFormat = "12";
      mCareSettings.setTimeFormat(timeFormat);
      
      // Demo - generate disconnect alert setting
      SetCareSetting.Switch disconnectAlert = mCareSettings.getEnableDisconnectAlert();
      disconnectAlert = SetCareSetting.Switch.True;
      mCareSettings.setEnableDisconnectAlert(disconnectAlert);
      
      _goFITSdk.doSetSettings(mCareSettings, new GoFITSdk.SettingsCallback() {
          ...
      });

Clear Data

  • public void doClearDeviceData(
        final GenericCallback clearDataCallback
    );
    • 功能
    • 參數
      • (callback) clearDataCallBack :

        public interface GenericCallback {
            void onSuccess();
            void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Timeout : 15 秒 (若裝置無回應,15秒後會 callback fail)

Device Data Initialization

  • public void doInitialDevice(
        final GenericCallback initialDeviceCallBack
    );
    • 功能
      • 初始化裝置內之資料
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • (callback) initialDeviceCallBack :

        public interface GenericCallback {
            void onSuccess();
            void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Timeout : 15 秒 (若裝置無回應,15 秒後會 callback fail)

Device Firmware Update

  • public void doDFU(
        final DFUCallback dfuCallback
    );
    • 功能
      • 升級手環韌體
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • dfuCallback

        public interface DFUCallback {
            public void onSuccess();
            public void onProgress(int progress);
            public void onFailure(int errorCode, String errorMsg);
        }
        • 功能
          • 回傳同步結果
        • (callback) onProgress() : 目前 DFU 的進度 (百分比)
        • (callback) onSuccess() : 表示成功
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message; could be null.
    • Return
      • void
    • Timeout : 30 秒 (若裝置無回應,30秒後會 callback fail)

Send Incoming Message

  • public void doSendIncomingMessage(
        AppContract.emIncomingMessageType type,
        String message,
        String packageName
    );
    public enum emIncomingMessageType {
        GMail,
        Hangout,
        calendar,
        calendar2,
        Facebook,
        Line,
        WhatsApp,
        QQ,
        WeChat,
        phoneOn,
        phoneOff,
        SMS,
        Default
    }
    • 功能
      • 傳送手機通知給裝置
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
      • Client 需自行於 App 內定義實做 Notification Listener,以利用本 API 轉送訊息通知到手環
    • 參數
      • type : GoFIT SDK 預設定義的通知 type (裝置韌體有為預設 type 設計特定圖示)
      • message : 手機端接收到的通知內容
      • packageName : 通知內容所屬的 app package name
    • Return
      • void

Set Remote Camera Handler

  • public void setRemoteCameraHandler(
        AppContract.RemoteCameraHandler handler
    );
    public interface RemoteCameraHandler {
        public void triggerCamera();
    }
    
    • 功能
      • 定義接收遙控拍照指令的 callback
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
      • Client 需自行於 App 內設計/實做啟動相機功能之畫面
      • 僅適用於裝置 Care-XcCare-Xe
    • 參數
      • handler : 接收遙控拍照指令的 callback,可於此 callback 自行定義接收遙控拍照指令的後續行為
    • Return
      • void

Find My Care

  • public void doFindMyCare(
        int vibrationCount
    ) ;
    • 功能
      • 尋找我的手環功能
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
      • 僅適用於裝置 Care-XcCare-Xe
    • 參數
      • vibrationCount : 手環震動次數
    • Return
      • void

Check Device Connection Status

  • public boolean isBLEConnect();
    • 功能
      • 確認裝置目前的連線狀態
    • Return
      • true if connected; false otherwise

Get Device Battery Level

  • public void getDeviceBatteryValue(
        final GetDeviceInfoCallback getDeviceInfoCallback
    );
    • 功能
      • 取得裝置電量
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • getDeviceInfoCallback

        public interface GetDeviceInfoCallback {
            public void onSuccess(String info);
            public void onFailure(int errorCode, String reason);
        }
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
          • info : 電量 (為百分比)
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Get Device Serial Number

  • public void getDeviceSN(
        final GetDeviceInfoCallback getDeviceInfoCallback
    );
    • 功能
      • 取得裝置之序號
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • getDeviceInfoCallback (其 type 之定義同上述)
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
          • info : 裝置之序號
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Get Device MAC Address

  • public void getDeviceMAC(
        final GetDeviceInfoCallback getDeviceInfoCallback
    );
    • 功能
      • 取得裝置之 MAC Address
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • getDeviceInfoCallback (其 type 之定義同上述)
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
          • info : 裝置之 MAC address
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Get Device Firmware Version

  • public void getDeviceFWVersion(
        final GetDeviceInfoCallback getDeviceInfoCallback
    ); 
    • 功能
      • 取得裝置之韌體版本
      • 需要先呼叫 Connect Device API,連接成功後才能執行此 API
    • 參數
      • getDeviceInfoCallback (其 type 之定義同上述)
        • 功能
          • 回傳結果
        • (callback) onSuccess() : 表示成功
          • info : 裝置之韌體版本
        • (callback) onFailure() : 表示失敗
          • errorCode : Error code
          • errorMsg : Error message
    • Return
      • void

Disconnect Device

  • public void doDisconnectDevice();
    • 功能
      • 將目前連線之裝置斷線

Re-Initialize Instance

  • public void reInitInstance();
    • 功能
      • 為避免一些例外情況造成 SDK instance 錯亂 (e.g., 防止 reentrant 的 lock 在異常狀態下沒有解開,造成下一個裝置無法進行連線同步),透過此方法可手動 re-inititalize SDK singleton instance

Set Context

  • public void setContext(Context context);
    • 功能
      • 變更當前的 Application's context

Set Connect Device Timeout

  • public void setConnectTimeout(String productID, int timeout);
    • 功能



Data Models and Objects

Response Code

  • public class ResponseCode {
        public static final int HTTP_REQUEST_FAIL = 0;
    
        // BLE
        public static final int BLE_CMD_OK = 10;
        public static final int BLE_NOT_ENABLE = BLE_CMD_OK + 1;
        public static final int BLE_CONNECT_FAIL = BLE_CMD_OK + 2;
        public static final int DEVICE_DISCONNECT = BLE_CMD_OK + 3;
        public static final int DEVICE_PAIRING_FAIL = BLE_CMD_OK + 4;
        public static final int DEVICE_PAIRING_CODE_NOT_FOUND = BLE_CMD_OK + 5;
        public static final int DEVICE_ALREADY_PAIRED = BLE_CMD_OK + 6;
        public static final int DEVICE_RELEASE_PAIR_FAIL = BLE_CMD_OK + 7;
        public static final int BLE_SETTING_FORMAT_ERROR = BLE_CMD_OK + 8;
        public static final int DEVICE_NOT_SUPPORT_JUMP_BOOTLOADER = BLE_CMD_OK + 9;
        public static final int DFU_APP_MODE_ERROR = BLE_CMD_OK + 10;
        public static final int MESSAGE_TYPE_NON_EXISTENT_OR_NOT_IMPLEMENTED = BLE_CMD_OK + 11;
        public static final int PAIRING_NEEDED = BLE_CMD_OK + 12;
        public static final int AUTHORIZATION_NEEDED = BLE_CMD_OK + 13;
        public static final int ANCS_BONDING_FAIL = BLE_CMD_OK + 14;
        public static final int START_TRANSMISSION_FAIL = BLE_CMD_OK + 15;
        public static final int GET_ACTIVITY_SUMMARY_FAIL = BLE_CMD_OK + 16;
        public static final int GET_NMEA_FAIL = BLE_CMD_OK + 17;
        public static final int DEVICE_NOT_FOUND = BLE_CMD_OK + 18;
        public static final int WRITE_COMMAND_TO_DEVICE_TIMEOUT = BLE_CMD_OK + 19;
        public static final int PAIRING_CODE_MISMATCH = BLE_CMD_OK + 20;
        public static final int DEVICE_FIRMWARE_UPDATE_FAILED = BLE_CMD_OK + 21;
        public static final int DEVICE_FIRMWARE_UPDATE_PROGRESSING = BLE_CMD_OK + 22;
        public static final int SYNC_PROGRESSING = BLE_CMD_OK + 23;
        public static final int UPLOAD_ACTIVITY_SUCCESS = BLE_CMD_OK + 24;
        public static final int UPLOAD_ACTIVITY_FAILED = BLE_CMD_OK + 25;
    }

Fitness Data Objects

  • Step Fitness Data Object
    public class TableStepRecord {
        public Date getTimestamp()    // Unix Time, i.e., number of `milliseconds` that have elapsed since 00:00:00 UTC time, 1 January 1970
        public int getSteps()
        public int getCalories()
        public int getDistance()
    }
  • Sleep Fitness Data Object
    public class TableSleepRecord {
        public Date getTimestamp()    // Unix Time, i.e., number of `milliseconds` that have elapsed since 00:00:00 UTC time, 1 January 1970
        public int getScore()
    }
  • Heart Rate Fitness Data Object
    public class TablePulseRecord {
        public Date getTimestamp()    // Unix Time, i.e., number of `milliseconds` that have elapsed since 00:00:00 UTC time, 1 January 1970
        public int getPulse()
    }
  • SpO2 Fitness Data Object
    public class TableSpO2Record {
        public Date getTimestamp()    // Unix Time, i.e., number of `milliseconds` that have elapsed since 00:00:00 UTC time, 1 January 1970
        public int getSpO2()
    }

SetCareSetting Data Object

  • package com.golife.customizeclass;
    
    class SetCareSetting {
        public enum Switch {
            None, True, False
        }
    
        public int getStepGoal();
        public void setStepGoal(int stepGoal);
    
        public String getSystemUnit();
        public void setSystemUnit(String systemUnit);    // "metric" | "imperial"
    
        public String getTimeFormat();
        public void setTimeFormat(String timeFormat);    // "12" | "24"
    
        public String getHandedness();
        public void setHandedness(String handedness);    // left" | "right"
    
        public Switch getEnableAutoLightUp();
        public void setEnableAutoLightUp(Switch enableAutoLightUp);
    
        public Switch getEnableDisconnectAlert();
        public void setEnableDisconnectAlert(Switch enableDisconnectAlert);
    
        public Switch getEnableANTPlus();
        public void setEnableANTPlus(Switch enableANTPlus);
    
        public SystemLanguage getSystemLanguage();
        public void setSystemLanguage(SystemLanguage language);
    
        public CareMeasureHR getMeasureHR();
        public void setMeasureHR(CareMeasureHR measureHR);
    
        public CareHRWarning getHRWarning();
        public void setHRWarning(CareHRWarning HRWarning);
    
        public CareDoNotDisturb getDoNotDisturb();
        public void setDoNotDisturb(CareDoNotDisturb doNotDisturb);
    
        public CareIdleAlert getIdleAlert();
        public void setIdleAlert(CareIdleAlert idleAlert);
    
        public CareAlarm getAlarms();
        public void setAlarms(CareAlarm alarms);
    
        public Switch getEnableHorizontalUnlock();
        public void setEnableHorizontalUnlock(Switch enableHorizontalUnlock);
    }