S130 HVX error codes

[tlongeri]

Hi,

I am using S130 on an nRF51822 with SDK v12.3. I want to handle the different error codes that could result from calling sd_ble_gatts_hvx and retry later.

Firstly, there's a couple of error codes that I'm not understanding. ble_gatts.h describes BLE_ERROR_INVALID_CONN_HANDLE and NRF_ERROR_INVALID_STATE as follows:

* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or notifications and/or indications not enabled in the CCCD.

What does 'Invalid Connection State' mean in this case? Which one of these would I receive if I have disconnected? I would expect to obtain BLE_ERROR_INVALID_CONN_HANDLE if I am disconnected. I was thinking maybe I get NRF_ERROR_INVALID_STATE if I have initiated a disconnection but it hasn't finished yet, and BLE_ERROR_INVALID_CONN_HANDLE if I am disconnected.

Another pair of error codes I can't quite differentiate is NRF_ERROR_BUSY and BLE_ERROR_NO_TX_PACKETS, which are are described in ble_gatts.h as follows:

* @retval ::NRF_ERROR_BUSY Procedure already in progress.
* @retval ::BLE_ERROR_NO_TX_PACKETS  No available application packets for this connection, applies only to notifications.

I found this S120 question which states that BLE layers are allowed to only queue one TX packet per connection, so NRF_ERROR_BUSY signals that another packet can't be queued. I don't know whether this applies to S130, and furthermore I don't see when BLE_ERROR_NO_TX_PACKETS would be returned if this is the case. My question is: under what situations would each of these error codes be returned?

Lastly, when I get these I would prefer to retry in response to a TX_COMPLETE event instead of a timer: I think this is possible, so that if I get NRF_ERROR_BUSY or BLE_ERROR_NO_TX_PACKETS I can expect a TX_COMPLETE event 100% of the time (except possibly when I disconnect or notifications are disabled instead), is that correct?

Edit: I found this diagram for S130 that shows a different behavior that what is described in the S120 question I linked. Still that leaves me with the question of under what circumstances is NRF_ERROR_BUSY returned.

[Øyvind]

Hello,

 

What does 'Invalid Connection State' mean in this case? Which one of these would I receive if I have disconnected? I would expect to obtain BLE_ERROR_INVALID_CONN_HANDLE if I am disconnected. I was thinking maybe I get NRF_ERROR_INVALID_STATE if I have initiated a disconnection but it hasn't finished yet, and BLE_ERROR_INVALID_CONN_HANDLE if I am disconnected.

NRF_ERROR_INVALID_STATE may mean that in this current state, the requested operation is not allowed. The device may have been disconnected during an operation, and when finalizing this operation to are not in a valid state to finish. See this thread for more information.

BLE_ERROR_INVALID_CONN_HANDLE is returned if your connection handle is not valid anymore.
Say that you are in the middle a function and about to send data, then an interrupt fires and disconnects the device. When continuing in the function the device will try to send data, in a disconnected state, you can get this error message. Some functions can also return _INVALID_STATE if called during such a race-condition.

I found this S120 question which states that BLE layers are allowed to only queue one TX packet per connection, so NRF_ERROR_BUSY signals that another packet can't be queued. I don't know whether this applies to S130, and furthermore I don't see when BLE_ERROR_NO_TX_PACKETS would be returned if this is the case. My question is: under what situations would each of these error codes be returned?

Edit: I found this diagram for S130 that shows a different behavior that what is described in the S120 question I linked. Still that leaves me with the question of under what circumstances is NRF_ERROR_BUSY returned.

Yes, the diagram for S130 is correct and shows that different SoftDevices handle this differently.  NRF_ERROR_BUSY is sometimes a symptom on a function that is not used as intended, see this thread. 

Lastly, when I get these I would prefer to retry in response to a TX_COMPLETE event instead of a timer: I think this is possible, so that if I get NRF_ERROR_BUSY or BLE_ERROR_NO_TX_PACKETS I can expect a TX_COMPLETE event 100% of the time (except possibly when I disconnect or notifications are disabled instead), is that correct?

This thread discusses somewhat how to handle the BLE_ERROR_NO_TX_PACKETS.

Note that this behavior may differ slightly if you use another softdevice. Here's the message sequence chart for S132 v6-series: GATTS Handle Value Notification

Kind regards,

Øyvind

[tlongeri]

Thank you, your second linked thread is very clear in saying that NRF_ERROR_BUSY is returned in the specific case of sending multiple indications through sd_ble_gatts_hvx without waiting for an acknowledge. Although it does not state this is the only situation that would result in this error code, I am going to go ahead and assume that is the case (I have some code that sends notifications which I modified to assert on NRF_ERROR_BUSY and I haven't had trouble yet).

The third thread you linked is about what I expected, just wait for the TX_COMPLETE event and send again. I was wondering if there were any circumstances where I wouldn't get the TX_COMPLETE event after getting BLE_ERROR_NO_TX_PACKETS, leaving me waiting forever. I would expect if I disconnected or if notifications were disabled, which is something I can handle, but I was worried if there were other cases.

Regarding INVALID_STATE and INVALID_CONN_HANDLE, I still find 'not being in a valid state' a bit vague. Granted, the the other possibilities for INVALID_STATE, notifications disabled and ongoing MTU exchange (the latter I only found out thanks to the thread you linked, by the way) are not vague. I guess I am probably right in thinking that after disconnecting there may be a window of time where INVALID_STATE will be returned, after which INVALID_CONN_HANDLE would be returned.

Although this is not terribly critical for my application, except for possibly the case of waiting forever for TX_COMPLETE, it would help make my code cleaner (with an added bonus of ever so slightly less power consumption by not requiring the RTC for a retry timer).

One of the relevant questions is 'do I have to retry sending after receiving an INVALID_STATE? If so, can I do it in response to any event instead of using a timer?'. Notifications being disabled, for my particular application, would mean 'stop sending and forget about any pending messages', as would a disconnection. Since I don't know exactly what INVALID_STATE means, or if I should wait for some particular event(s) after getting it, I have to be conservative with my assumptions and retry on a timer until I succeed or get a disconnection or disabled notifications event.

[Øyvind]

Hello,

tlongeri said:

The third thread you linked is about what I expected, just wait for the TX_COMPLETE event and send again. I was wondering if there were any circumstances where I wouldn't get the TX_COMPLETE event after getting BLE_ERROR_NO_TX_PACKETS, leaving me waiting forever. I would expect if I disconnected or if notifications were disabled, which is something I can handle, but I was worried if there were other cases.

 Usually, you should receive TX_COMPLETE after a BLE_ERROR_NO_TX_PACKETS, but sometimes you may miss/not receive TX_COMPLETE due to other circumstances. If so, you'll get an e.g. DISCONNECTED event. 

tlongeri said:

Regarding INVALID_STATE and INVALID_CONN_HANDLE, I still find 'not being in a valid state' a bit vague. Granted, the the other possibilities for INVALID_STATE, notifications disabled and ongoing MTU exchange (the latter I only found out thanks to the thread you linked, by the way) are not vague. I guess I am probably right in thinking that after disconnecting there may be a window of time where INVALID_STATE will be returned, after which INVALID_CONN_HANDLE would be returned.

 Yes, this is correct but depends on each individual call. Searching for NRF_ERROR_INVALID_STATE or BLE_ERROR_INVALID_CONN_HANDLE in ble_gatts.h yields several results. Each return value is found described in the function brief which might help to indicate what state returned the error:

line 507 /**@brief Notify or Indicate an attribute value.

@note The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution.
* When receiveing the error codes @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and
* @ref BLE_ERROR_NO_TX_PACKETS the Attribute Table has been updated.
* The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len).

@note It is important to note that a notification will <b>consume an application buffer</b>, and will therefore
* generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. An indication on the other hand will use the
* standard server internal buffer and thus will only generate a @ref BLE_GATTS_EVT_HVC event as soon as the confirmation
* has been received from the peer. Please see the documentation of @ref sd_ble_tx_packet_count_get for more details.

tlongeri said:

One of the relevant questions is 'do I have to retry sending after receiving an INVALID_STATE? If so, can I do it in response to any event instead of using a timer?'. Notifications being disabled, for my particular application, would mean 'stop sending and forget about any pending messages', as would a disconnection. Since I don't know exactly what INVALID_STATE means, or if I should wait for some particular event(s) after getting it, I have to be conservative with my assumptions and retry on a timer until I succeed or get a disconnection or disabled notifications event.

 I would suggest reading through the API documentation of S130 header files, they include a very good description of each API call with a description of NRF_ERROR_INVALID_STATE and BLE_ERROR_INVALID_CONN_HANDLE.

Best regards,
Oeyvind

[tlongeri]

Hi,

Øyvind said:

 Yes, this is correct but depends on each individual call. Searching for NRF_ERROR_INVALID_STATE or BLE_ERROR_INVALID_CONN_HANDLE in ble_gatts.h yields several results. Each return value is found described in the function brief which might help to indicate what state returned the error:

I was asking specifically about sd_ble_gatts_hvx.

Øyvind said:

 I would suggest reading through the API documentation of S130 header files, they include a very good description of each API call with a description of NRF_ERROR_INVALID_STATE and BLE_ERROR_INVALID_CONN_HANDLE.

This is what I initially did and what I quoted in my original question, because I found it to not be thorough enough that I would know what to expect without doing tests.

Maybe I am asking for too many details. Regardless of that, thank you for the answers, there were some helpful links. I have got something working (timer-less) and it has yet to fail.

Regards,

Tomás