![]() |
Bluetooth LE Profile API document
Bluetooth LE Profile API document Rev.1.00 [May 22, 2020]
|
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... | |
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.
[in] | vs_cb | Callback function to be registered. |
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
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.
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) .
[in] | p_tx_test_param | Tx Test parameters. |
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
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.
The transmitter is configured to one of the following, the receiver can't receive the packets by this function.
[in] | p_rx_test_param | The extended receiver test parameters. |
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
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.
void |
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
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.
Select the following transmit power level.
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.
[in] | conn_hdl | Connection handle identifying the link whose transmit power to be configured. If non connected state, set BLE_GAP_INIT_CONN_HDL(0xFFFF). |
[in] | tx_power | Transmission power. Select one of the following. |
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. |
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 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.
[in] | conn_hdl | Connection handle identifying the link whose transmit power to be retrieved. If non connected state, set BLE_GAP_INIT_CONN_HDL(0xFFFF). |
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. |
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.
[in] | coding_scheme | Coding 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.
|
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
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.
[in] | p_rf_ctrl | RF parameters. |
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
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.
[in] | area | The area that the address is to be written in. Select one of the following.
| ||||||
[in] | p_addr | The 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. |
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
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.
[in] | area | The area that the address is to be acquired. Select one of the following.
| ||||||
[in] | addr_type | The address type that is type of the address to be acquired.
|
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
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.
[in] | rand_size | Length of the random number (byte). The valid range is 4<=rand_size<=16. |
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
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 result of this API call is returned by a return value.
void |
BLE_SUCCESS(0x0000) | Success |
Events
Message Sequence Chart
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.
void |
BLE_SUCCESS(0x0000) | Success |
Events
none
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.
[out] | p_buffer_num | The number of the available transmission packet buffers. |
BLE_SUCCESS(0x0000) | Success |
BLE_ERR_INVALID_PTR(0x0001) | The p_buffer_num parameter is specified as NULL. |
Events
none
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.
[in] | tx_queue_lwm | Low 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_hwm | High 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. |
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