PE Controller

Class PEController:

The class is used to interact with the peripheral controller which communicates with BLE:Bit.

Constructing a PEripheral Controller object

import cybervelia.sdk.controller.pe.PEController;
import cybervelia.sdk.controller.pe.PEBLEDeviceCallbackHandler;

static void main(){
    PEController pe = new PEController("COM1", new PEBLEDeviceCallbackHandler());
}

Available Member Methods

Read LTK Own Key

public int readLTKPeerKey(byte[] data) throws IOException

Read our own key from BLE:Bit and store the key in parameter data

Parameters:

byte[] data - The buffer to store the LTK key

Returns int:

The length of key in bytes

Read LTK Peer Key

public int readLTKPeerKey(byte[] data) throws IOException

Read the peer key from BLE:Bit and store the key in parameter data

Parameters:

byte[] data - The buffer to store the peer's LTK key

Returns int:

The length of key in bytes

Check Initialization

Then a PEController object is created, the device is initialized.

Example: When the port used for a CEController is instead a BLE:Bit PE device, and the port used for a PEController is instead a BLE:Bit CE device, then this method will return false in both object's invocation of method isInitializedCorrectly(). In that case, a call to switchIO() in both objects must follow in order to switch I/O and continue the session. The reason for switching and not re-creating the objects it's because the BLE:Bit devices are already initialized and have already changed state. Recreating the objects is unnecessary.

public boolean isInitializedCorrectly()

Parameters: None

Returns: boolean

True when the device is initialized correctly, False when the device failed to be initialized as the expected controller.

Switching IO

public InputStream getInputStream()

public OutputStream getOutputStream()

public BLESerialPort getSerialPort()

public short getFirmwareVersion()

public void switchIO(InputStream in, OutputStream out, BLESerialPort port, short firmwarev) throws IOException

When two BLE:Bit devices with different controllers are used, one cannot determine which devices has which controller only be reviewing the USB bridge SoC driver's name. Therefore, when a wrong port is selected, the method isInitializedCorrectly() can be used to detect that error. In this case, the above methods can be used to correct that behavior. Then, the methods can be used as shown below:

    /* Identify the correct device (ce or pe ) and switch IO if that is deemed necessary */
    private static void switchIO(String[] found_ports, CEController ce, PEController pe) throws IOException {
        if (!ce.isInitializedCorrectly() && !pe.isInitializedCorrectly())
        {
            // Get SerialPort InputStream and OutputStream
            InputStream ce_in = ce.getInputStream();
            OutputStream ce_out = ce.getOutputStream();
            // Get Firmware version retrieved from BLE:Bit during initialization stage
            short ce_fw = ce.getFirmwareVersion();
            // get Serial Port
            BLESerialPort ce_port = ce.getSerialPort();
            // Exchange Ports
            String serial_ce = found_ports[0];
            found_ports[0] = found_ports[1];
            found_ports[1] = serial_ce;
            // Switch Input/Output streams, Serial Ports and Firmware Version
            ce.switchIO(pe.getInputStream(), pe.getOutputStream(), pe.getSerialPort(), pe.getFirmwareVersion());
            pe.switchIO(ce_in, ce_out, ce_port, ce_fw);

        }
        else if ((ce.isInitializedCorrectly() ^ pe.isInitializedCorrectly()))
        {
            System.exit(1);
        }
    }

Sending Connection Parameters

Note: Must be used before invoking the method finishSetup()

public void sendConnectionParameters(PEConnectionParameters pe_connection_parameters) throws IOException

Parameters:

pe_connection_parameters - An object of class PEConnectionParameters that holds the connection parameters

Returns: void

Set Device Bluetooth Device Address

Note: Must be used before invoking the method finishSetup()

public void sendBluetoothDeviceAddress(String address, ConnectionTypesCommon.BITAddressType address_type) throws IOException

Parameters:

address - The hexadecimal format address of peripheral, semi-colon separated ie. aa:bb:cc:aa:bb:cc
address_type - The type of address specified as a ConnectionTypesCommon.BITAddressType

Returns: void

Disable Repairing after bonding

Note: Must be used before invoking the method finishSetup()

public void deviceDisableRepairingAfterBonding() throws IOException

When there is an LTK key for the target device, do not attempt to repair with the device.

Parameters: None

Returns: void

Delete all Long Term Keys

Note: Must be used before invoking the method finishSetup()

public void eraseBonds() throws IOException

Parameters: None

Returns: void

Delete Long Term Key per device

Note: You may delete peer's keys only when you are disconnected and no advertising/scan is in place - otherwise the call will fail

public boolean deletePeerBond(short peer_id)

When the device has successfully paired with a target, then target is associated with a peer-id.

Parameters:

peer_id - The peer-id of the target

Returns: boolean

Returns true when the keys has been erased or false when the call has failed to complete.

Get ready for action - Finish Setup

When the device has been configured properly, then the method finishSetup() must be invoked in order to force the device to change state which can accept connections, advertise etc.

public void finishSetup() throws IOException

Parameters: None

Returns: void

Check if the communication is encrypted

public boolean isBonded()

Parameters: None

Returns: boolean

Returns true only if the device has established a secure communication with the target.

Configure Pairing Method

Note: Must be used before invoking the method finishSetup()

public void configurePairing(ConnectionTypesCommon.PairingMethods p_method, String static_pin) throws IOException

Parameters:

p_method - Pairing method, a type of ConnectionTypesCommon.PairingMethods
pin (optional) - A static PIN

Returns: void

Get connected device status

public boolean isDeviceConnected()

Parameters: None

Returns: boolean

Returns true if there is a connection has been established with a target or false when there is no connection established

Get disconnected reason

public int getDisconnectionReason()

Parameters: None

Returns: int

Returns the reason as a numerical form, which defines the disconnection reason. The encoded reasons are taken from the actual LE-frame, and are defined by the Bluetooth Sig Spec. and can be found below:

Authentication Failure - 0x05
Remote User Terminated Connection - 0x13
Connection Terminated by Local Host - 0x16
Remote device terminated connection due to low resources - 0x14
Remote device terminated connection due to Power Off - 0x15
Unsupported Remote Feature - 0x15
Pairing with Unit Key Not Supported error code - 0x29
Unacceptable Connection Parameters - 0x3B

Disconnect

public void disconnect(int reason)

Parameters:

reason - Disconnect from the target by specifying a reason

The encoded reasons are defined by the Bluetooth Sig Spec. and can be found below:

Authentication Failure - 0x05
Remote User Terminated Connection - 0x13
Connection Terminated by Local Host - 0x16
Remote device terminated connection due to low resources - 0x14
Remote device terminated connection due to Power Off - 0x15
Unsupported Remote Feature - 0x15
Pairing with Unit Key Not Supported error code - 0x29
Unacceptable Connection Parameters - 0x3B

Returns: void

Send Notifications

Sending a notification to a central:

public boolean sendNotification(short cccd_handle, final byte[] data, int size) throws IOException

Parameters:

cccd_handle - Handle of the characteristic CCCD
data - Buffer that holds the data to be transmitted
size - Size of data

Returns: boolean

Returns true when the notification/indication has been sent successfully, or returns false when the operation has failed

Bond Now

public boolean bondNow(boolean force_repairing)

Parameters:

force_repairing - Force the device to repair

Returns: boolean

Returns true of the device has bonded successfully.

Terminate BLE:Bit's Session

The following method forces the BLE:Bit to perform a soft-reset.

public void terminate()

Setting Manufacturer's Name

Note: Must be used before invoking the method finishSetup()

public void setManufacturerName(String value) throws IOException

Parameters:

value - Name of the manufacturer

Returns: void

Setting model's name

Note: Must be used before invoking the method finishSetup()

public void setModelName(String value) throws IOException

Parameters:

value - Model's name

Returns: void

Setting Hardware Revision String

Note: Must be used before invoking the method finishSetup()

public void setHardwareRevision(String value) throws IOException

Parameters:

value - Hardware Revision String

Returns: void

Setting Software Revision String

Note: Must be used before invoking the method finishSetup()

public void setSoftwareRevision(String value) throws IOException

Parameters:

value - Software Revision String

Returns: void

Setting Firmware Revision String

Note: Must be used before invoking the method finishSetup()

public void setFirmwareRevision(String value) throws IOException

Parameters:

value - Firmware Revision String

Returns: void

Setting device's name

Note: Must be used before invoking the method finishSetup()

public void sendDeviceName(String devname) throws IOException

Parameters:

devname - Device name

Returns: void

Setting appearance

Note: Must be used before invoking the method finishSetup()

public void setAppearanceValue(short value) throws IOException

Parameters:

value - Appearance encoded value, based on BLE specification standard encoded values

Returns: void

Appearance Values:

BLE_APPEARANCE_UNKNOWN = 0
BLE_APPEARANCE_GENERIC_PHONE = 64
BLE_APPEARANCE_GENERIC_COMPUTER = 128
BLE_APPEARANCE_GENERIC_WATCH = 192
BLE_APPEARANCE_WATCH_SPORTS_WATCH = 193
BLE_APPEARANCE_GENERIC_CLOCK = 256
BLE_APPEARANCE_GENERIC_DISPLAY = 320
BLE_APPEARANCE_GENERIC_REMOTE_CONTROL = 384
BLE_APPEARANCE_GENERIC_EYE_GLASSES = 448
BLE_APPEARANCE_GENERIC_TAG = 512
BLE_APPEARANCE_GENERIC_KEYRING = 576
BLE_APPEARANCE_GENERIC_MEDIA_PLAYER = 640
BLE_APPEARANCE_GENERIC_BARCODE_SCANNER = 704
BLE_APPEARANCE_GENERIC_THERMOMETER = 768
BLE_APPEARANCE_THERMOMETER_EAR = 769
BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR = 832
BLE_APPEARANCE_HEART_RATE_SENSOR_HEART_RATE_BELT = 833
BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE = 896
BLE_APPEARANCE_BLOOD_PRESSURE_ARM = 897
BLE_APPEARANCE_BLOOD_PRESSURE_WRIST = 898
BLE_APPEARANCE_GENERIC_HID = 960
BLE_APPEARANCE_HID_KEYBOARD = 961
BLE_APPEARANCE_HID_MOUSE = 962
BLE_APPEARANCE_HID_JOYSTICK = 963
BLE_APPEARANCE_HID_GAMEPAD = 964
BLE_APPEARANCE_HID_DIGITIZERSUBTYPE = 965
BLE_APPEARANCE_HID_CARD_READER = 966
BLE_APPEARANCE_HID_DIGITAL_PEN = 967
BLE_APPEARANCE_HID_BARCODE = 968
BLE_APPEARANCE_GENERIC_GLUCOSE_METER = 1024
BLE_APPEARANCE_GENERIC_RUNNING_WALKING_SENSOR = 1088
BLE_APPEARANCE_RUNNING_WALKING_SENSOR_IN_SHOE = 1089
BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_SHOE = 1090
BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_HIP = 1091
BLE_APPEARANCE_GENERIC_CYCLING = 1152
BLE_APPEARANCE_CYCLING_CYCLING_COMPUTER = 1153
BLE_APPEARANCE_CYCLING_SPEED_SENSOR = 1154
BLE_APPEARANCE_CYCLING_CADENCE_SENSOR = 1155
BLE_APPEARANCE_CYCLING_POWER_SENSOR = 1156
BLE_APPEARANCE_CYCLING_SPEED_CADENCE_SENSOR = 1157

Disable advertising channels

Note: Must be used before invoking the method finishSetup()

public void disableAdvertisingChannels(int channels) throws IOException

Parameters:

channels - Channels to disable advertisement.

Channels:

    // Advertising Channel Type
    public static final byte ADV_CH_37                      = 0x01;
    public static final byte ADV_CH_38                      = 0x02;
    public static final byte ADV_CH_39                      = 0x04;

Example (disabling channel 37 and channel 38:

disableAdvertisingChannels(ConnectionTypesPE.ADV_CH_37 | ConnectionTypesPE.ADV_CH_38)

Setting advertisement interval

Note: Must be used before invoking the method finishSetup()

public void sendAdvIntervalTU(int value) throws IOException

Parameters:

value - Time Units (1 TU = 0.625 ms)

Value Limitations: value >= 0x20 and value <= 0x4000

Update Characteristic's value

public boolean updateValue(short handle, final byte[] data, int size) throws IOException

Parameters

handle - Characteristic's handle
data - Buffer containing the updated data
size - Size of characteristic's data

Returns: boolean

Returns true when update has been successful and fails if update has failed.

Start or Stop Advertisement

The advertisement starts automatically when finishSetup is invoked.

public void stopAdvertising() throws IOException
public void startAdvertising() throws IOException

Setting a BLE service

Note: Must be used before invoking the method finishSetup()

Each service cannot be set twice.

public boolean sendBLEService(BLEService ble_service) throws IOException

Parameters:

ble_service - BLEService object that contains service metadata and its corresponding characteristics

Returns: boolean

Returns true of the service has been set successfully

Setting Advertisement Data

Note: Must be used before invoking the method finishSetup()

public void sendScanData(AdvertisementData data) throws IOException

Parameters:

data - Scan Data

Returns: void

public void sendAdvertisementData(AdvertisementData data) throws IOException

Parameters:

data - Advertisement Data

Returns: void

Setting direct address

Note: Must be used before invoking the method finishSetup()

public void setDirectAddress(String address, ConnectionTypesCommon.BITAddressType type) throws IOException

Parameters:

address - Direct address
type - Type of direct address

Returns: void

Available Static Methods

Reset

public static boolean reset(String device_port)

Parameters:

String device_port - The COM/tty/ACM/USB port of the device

Returns: boolean

Returns true if the device has been reset successfully, or false when the reset has failed