Bluetooth LE Profile API document
Bluetooth LE Profile API document Rev.1.00 [May 22, 2020]

Detailed Description

Functions

ble_status_t R_BLE_VS_Init (ble_vs_app_cb_t vs_cb)
 This function initializes Vendor Specific API and registers a callback function for Vendor Specific Event. More...
 
ble_status_t R_BLE_VS_StartTxTest (st_ble_vs_tx_test_param_t *p_tx_test_param)
 This function starts extended Transmitter Test. More...
 
ble_status_t R_BLE_VS_StartRxTest (st_ble_vs_rx_test_param_t *p_rx_test_param)
 This function starts extended Receiver Test. More...
 
ble_status_t R_BLE_VS_EndTest (void)
 This function terminates the extended transmitter or receiver test. More...
 
ble_status_t R_BLE_VS_SetTxPower (uint16_t conn_hdl, uint8_t tx_power)
 This function configures transmit power. More...
 
ble_status_t R_BLE_VS_GetTxPower (uint16_t conn_hdl)
 This function gets transmit power. More...
 
ble_status_t R_BLE_VS_SetCodingScheme (uint8_t coding_scheme)
 This function configure default Coding scheme(S=8 or S=2) that is used in the case of selecting Coded PHY in Primary advertising PHY or Secondary advertising PHY advertising or request for link establishment. More...
 
ble_status_t R_BLE_VS_SetRfControl (st_ble_vs_set_rf_ctrl_param_t *p_rf_ctrl)
 This function performs power control on RF. More...
 
ble_status_t R_BLE_VS_SetBdAddr (uint8_t area, st_ble_dev_addr_t *p_addr)
 This function sets public/random address of local device to the area specified by the parameter. More...
 
ble_status_t R_BLE_VS_GetBdAddr (uint8_t area, uint8_t addr_type)
 This function gets currently configured public/random address. More...
 
ble_status_t R_BLE_VS_GetRand (uint8_t rand_size)
 This function generates 4-16 bytes of random number used in creating keys. More...
 
ble_status_t R_BLE_VS_StartTxFlowEvtNtf (void)
 This function starts the notification(BLE_VS_EVENT_TX_FLOW_STATE_CHG event) of the state transition of TxFlow. More...
 
ble_status_t R_BLE_VS_StopTxFlowEvtNtf (void)
 This function stops the notification(BLE_VS_EVENT_TX_FLOW_STATE_CHG event) of the state transition of TxFlow. More...
 
ble_status_t R_BLE_VS_GetTxBufferNum (uint32_t *p_buffer_num)
 This function gets the number of the available transmission packet buffers. More...
 
ble_status_t R_BLE_VS_SetTxLimit (uint32_t tx_queue_lwm, uint32_t tx_queue_hwm)
 This function sets the threshold for notifying the application layer of the TxFlow state. More...
 

Function Documentation

◆ R_BLE_VS_Init()

ble_status_t R_BLE_VS_Init ( ble_vs_app_cb_t  vs_cb)

This function initializes Vendor Specific API and registers a callback function for Vendor Specific Event.

The result of this API call is returned by a return value.

Parameters
[in]vs_cbCallback function to be registered.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The vs_cb parameter is specified as NULL.
BLE_ERR_CONTEXT_FULL(0x000B)Callback function has already been registered.

Events
none

◆ R_BLE_VS_StartTxTest()

ble_status_t R_BLE_VS_StartTxTest ( st_ble_vs_tx_test_param_t p_tx_test_param)

This function starts extended Transmitter Test.

The following extended transmitter test functions of DTM Tx are supported by this function.

  • Tx Power
  • Tx Modulation Enable/Modulation Disable
  • Tx packet transmission/continuous transmission
  • Tx packets count

The result of this API call is notified in BLE_VS_EVENT_TX_TEST_START event.

If the num_of_packet field in the p_tx_test_param parameter is other than 0x0000, BLE_VS_EVENT_TX_TEST_TERM event notifies the application layer that the number of packet has been sent.

If R_BLE_VS_EndTest() is called before the specified number of packets completions, BLE_VS_EVENT_TX_TEST_TERM event is not notified to the application layer.

The condition that phy field in the p_tx_test_param parameter is BLE_VS_EH_TEST_PHY_CODED_S_8(0x03) and option field is modulation(bit0:0) & continuous transmission(bit1:1) is not supported.
In this case, BLE_VS_EVENT_TX_TEST_START event returns BLE_ERR_INVALID_ARG(0x0003) .

Parameters
[in]p_tx_test_paramTx Test parameters.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_tx_test_param parameter is specified as NULL.
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

Message Sequence Chart

◆ R_BLE_VS_StartRxTest()

ble_status_t R_BLE_VS_StartRxTest ( st_ble_vs_rx_test_param_t p_rx_test_param)

This function starts extended Receiver Test.

The result of this API call is notified in BLE_VS_EVENT_RX_TEST_START event.

The following extended receiver test functions of DTM Rx are supported by this function.

  • Calculating the maximum, the minimum and the average of RSSI in the receiver test.
  • The number of CRC error packets in the receiver test.

The transmitter is configured to one of the following, the receiver can't receive the packets by this function.

Parameters
[in]p_rx_test_paramThe extended receiver test parameters.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_rx_test_param parameter is specified as NULL.
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

Message Sequence Chart

◆ R_BLE_VS_EndTest()

ble_status_t R_BLE_VS_EndTest ( void  )

This function terminates the extended transmitter or receiver test.

The result of this API call is notified in BLE_VS_EVENT_TEST_END event. In case of extended receiver test, this event notifies the application layer of the result of the extended receiver test.

Parameters
void
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

Message Sequence Chart

◆ R_BLE_VS_SetTxPower()

ble_status_t R_BLE_VS_SetTxPower ( uint16_t  conn_hdl,
uint8_t  tx_power 
)

This function configures transmit power.

This function configures the transmit power as follows.

  • The transmit power used in sending advertising PDU, scan request PDU, connection request PDU (in not connected state).
    Set the conn_hdl parameter to BLE_GAP_INIT_CONN_HDL(0xFFFF).
  • The transmit power used in sending PDU in connected state.
    Set the conn_hdl parameter to the connection handle of the link.

Select the following transmit power level.

  • High
  • Middle
  • Low

Max transmit power of "High" is dependent on the configuration of the firmware.
The result of this API call is notified in BLE_VS_EVENT_SET_TX_POWER event.

Parameters
[in]conn_hdlConnection handle identifying the link whose transmit power to be configured. If non connected state, set BLE_GAP_INIT_CONN_HDL(0xFFFF).

[in]tx_powerTransmission power. Select one of the following.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

◆ R_BLE_VS_GetTxPower()

ble_status_t R_BLE_VS_GetTxPower ( uint16_t  conn_hdl)

This function gets transmit power.

This function gets the transmit power as follows.

  • The transmit power used in sending advertising PDU, scan request PDU, connection request PDU (in not connected state).
    Set the conn_hdl parameter to BLE_GAP_INIT_CONN_HDL(0xFFFF).
  • The transmit power used in sending PDU in connected state.
    Set the conn_hdl parameter to the connection handle of the link.

    The result of this API call is notified in BLE_VS_EVENT_GET_TX_POWER event.

Parameters
[in]conn_hdlConnection handle identifying the link whose transmit power to be retrieved. If non connected state, set BLE_GAP_INIT_CONN_HDL(0xFFFF).
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

◆ R_BLE_VS_SetCodingScheme()

ble_status_t R_BLE_VS_SetCodingScheme ( uint8_t  coding_scheme)

This function configure default Coding scheme(S=8 or S=2) that is used in the case of selecting Coded PHY in Primary advertising PHY or Secondary advertising PHY advertising or request for link establishment.

After setting the default Coding scheme by this function, configure the advertising parameters by R_BLE_GAP_SetAdvParam() or send a request for link establishment.

The result of this API call is notified in BLE_VS_EVENT_SET_CODING_SCHEME_COMP event.

Parameters
[in]coding_schemeCoding scheme for Primary advertising PHY, Secondary advertising PHY, request for link establishment.The coding_scheme field is set to a bitwise OR of the following values.
bit description
bit0 Coding scheme for Primary Advertising PHY(0:S=8/1:S=2).
bit1 Coding scheme for Secondary Advertising PHY(0:S=8/1:S=2).
bit2 Coding scheme for request for link establishment(0:S=8/1:S=2).
All other bits Reserved for future use.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

◆ R_BLE_VS_SetRfControl()

ble_status_t R_BLE_VS_SetRfControl ( st_ble_vs_set_rf_ctrl_param_t p_rf_ctrl)

This function performs power control on RF.

If BLE communication is not used for a long time, RF reduces the power consumption by moving to the RF PowerDown state.
When RF power on, RF initialization processing is executed.
After RF power off by this function, API functions other than this are not available until RF power on again.

The result of this API call is notified in BLE_VS_EVENT_RF_CONTROL_COMP event.
After RF power on again with this function, call R_BLE_GAP_Terminate(), R_BLE_GAP_Init() in order to restart the host stack.

Parameters
[in]p_rf_ctrlRF parameters.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_rf_ctrl parameter is specified as NULL.
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

◆ R_BLE_VS_SetBdAddr()

ble_status_t R_BLE_VS_SetBdAddr ( uint8_t  area,
st_ble_dev_addr_t p_addr 
)

This function sets public/random address of local device to the area specified by the parameter.

If the address is written in non-volatile area, the address is used as default address on the next MCU reset.
For more information on the random address, refer to Core Specification Vol 6, PartB, "1.3.2 Random Device Address".
The result of this API call is notified in BLE_VS_EVENT_SET_ADDR_COMP event.

Parameters
[in]areaThe area that the address is to be written in.
Select one of the following.
macro description
BLE_VS_ADDR_AREA_REG(0x00) Address writing to non-volatile area is not performed.
Only the address in register is written.
BLE_VS_ADDR_AREA_DATA_FLASH(0x01) Address wiring to DataFlash area is performed.


[in]p_addrThe address to be set to the area. Set BLE_GAP_ADDR_PUBLIC(0x00) or BLE_GAP_ADDR_RAND(0x01) to the type field in the p_addr parameter.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_addr parameter is specified as NULL.
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

◆ R_BLE_VS_GetBdAddr()

ble_status_t R_BLE_VS_GetBdAddr ( uint8_t  area,
uint8_t  addr_type 
)

This function gets currently configured public/random address.

The area parameter specifies the place where this function gets public/random address.
The result of this API call is notified in BLE_VS_EVENT_GET_ADDR_COMP event.

Parameters
[in]areaThe area that the address is to be acquired.
Select one of the following.
macro description
BLE_VS_ADDR_AREA_REG(0x00) Acquire the address in register.
BLE_VS_ADDR_AREA_DATA_FLASH(0x01) Acquire the address in DataFlash area.


[in]addr_typeThe address type that is type of the address to be acquired.
macro description
BLE_GAP_ADDR_PUBLIC(0x00) Public address.
BLE_GAP_ADDR_RAND(0x01) Random address.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

◆ R_BLE_VS_GetRand()

ble_status_t R_BLE_VS_GetRand ( uint8_t  rand_size)

This function generates 4-16 bytes of random number used in creating keys.

The result of this API call is notified in BLE_VS_EVENT_GET_RAND event.

Parameters
[in]rand_sizeLength of the random number (byte).
The valid range is 4<=rand_size<=16.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_STATE(0x0008)The task for host stack is not running.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)There are no memories for Vendor Specific Command.

Events

◆ R_BLE_VS_StartTxFlowEvtNtf()

ble_status_t R_BLE_VS_StartTxFlowEvtNtf ( void  )

This function starts the notification(BLE_VS_EVENT_TX_FLOW_STATE_CHG event) of the state transition of TxFlow.

If the number of the available transmission packet buffers is the following, BLE_VS_EVENT_TX_FLOW_STATE_CHG event notifies the application layer of the state of the TxFlow.

  • The number of the available transmission packet buffers is less than Low Water Mark.
  • The number of the available transmission packet buffers is more than High Water Mark.

The result of this API call is returned by a return value.

Parameters
void
Return values
BLE_SUCCESS(0x0000)Success

Events

Message Sequence Chart

◆ R_BLE_VS_StopTxFlowEvtNtf()

ble_status_t R_BLE_VS_StopTxFlowEvtNtf ( void  )

This function stops the notification(BLE_VS_EVENT_TX_FLOW_STATE_CHG event) of the state transition of TxFlow.

The result of this API call is returned by a return value.

Parameters
void
Return values
BLE_SUCCESS(0x0000)Success

Events
none

◆ R_BLE_VS_GetTxBufferNum()

ble_status_t R_BLE_VS_GetTxBufferNum ( uint32_t *  p_buffer_num)

This function gets the number of the available transmission packet buffers.

The maximum number of the available buffers is 10.
The result of this API call is returned by a return value.

Parameters
[out]p_buffer_numThe number of the available transmission packet buffers.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_buffer_num parameter is specified as NULL.

Events
none

◆ R_BLE_VS_SetTxLimit()

ble_status_t R_BLE_VS_SetTxLimit ( uint32_t  tx_queue_lwm,
uint32_t  tx_queue_hwm 
)

This function sets the threshold for notifying the application layer of the TxFlow state.

Call this function before the notification(BLE_VS_EVENT_TX_FLOW_STATE_CHG event) has been started by R_BLE_VS_StartTxFlowEvtNtf().
The result is returned from this API.

Vendor Specific API supports the flow control function(TxFlow) for the transmission on L2CAP fixed channel in Basic Mode such as GATT.

Host stack has 10 transmission packet buffers for the transmission.

When the number of the available transmission packet buffers has been less than Low Water Mark, the state of TxFlow transmits into the TxFlow OFF state from the TxFlow ON state that is the initial state and host stack notifies the application layer of timing to stop packet transmission.

When host stack has sent the transmission packets to Controller and the number of the available transmission packet buffers has been more than High Water Mark, the state of TxFlow transmits into the TxFlow ON state from the TxFlow OFF state and host stack notifies the application layer of timing to restart packet transmission.

It is possible to perform flow control on a fixed channel by using the event notification.

Figure 1.1 shows the state transition of TxFlow.

flow_state_en.svg
Figure 1.1 The state transition of TxFlow
Parameters
[in]tx_queue_lwmLow Water Mark.
Set 0-9 less than tx_queue_hwm to the parameter.
When the number of the available transmission packet buffers has been less than the value specified by the tx_queue_lwm parameter, host stack notifies the application layer of the timing to stop packet transmission.

[in]tx_queue_hwmHigh Water Mark.
Set 1-10 more than tx_queue_lwm to the parameter.
When the number of the available transmission packet buffers has been more than the value specified by the tx_queue_hwm parameter, host stack notifies the application layer of the timing to restart packet transmission.

Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_ARG(0x0003)The tx_queue_lwm parameter or the tx_queue_hwm parameter is out of range.

Events

Message Sequence Chart