feedback: confusing limitation in sd_ble_gap_adv_data_set

[pabigot]

The S110 v7.1.0 documentation for sd_ble_gap_adv_data_set says:

The format of the advertisement data will be checked by this call to ensure interoperability. Limitations imposed by this API call to the data provided include having a flags data type in the scan response data and duplicating the local name in the advertisement data and scan response data.

To me, this says that the Flags data type must be in the scan response data, and that the advertisement and scan response data must have the same local name content.

Apparently not. In order to avoid NRF_ERROR_INVALID_PARAM (which is not documented as an expected error return), the Flags data type must not be in the scan response data, and the local name content must not be in the advertisement data.

Please keep in mind that some of us are using the low-level soft-device API, not the helper libraries in the nrf51-sdk (though having the source to that did help me figure out what was going wrong). Perhaps change:

Limitations imposed by this API call to the data provided include....

to something starting with

Data parameters that will be rejected include...

[Ulrich Myhre]

"Limitations imposed (...) include having flags data type in the scan response". The wording is correct, but I can see that it can be a bit long-winded and confusing. The BLE_GAP_AD_TYPE_FLAGS is a meant as a filtering option for scanners, so they can broadly filter devices based upon discoverability flags. It does not make sense to put this in the scan response.

I could not find a very good reason to disallow duplication of the local name field, but the intended usage is for a device to connect and read the Device Name characteristic if it is interested. I could see this being useful for having a short name in the advertising data and a longer name in the scan response, but not the other way around (since the short name shall be equal to a substring of the full name, starting from the first character). We might loosen up this restriction in the future.

And I can see that invalid params can be indeed returned from this function, but that should only be the case when both pointers are NULL. Do you get this return code reliably in any other scenario as well? I have reported the case I found internally.

[pabigot]

It's just the phrasing: "Limitations include eating toast" when the intent is to disallow eating toast is unusual in English in my experience. A negative requirement would normally be used: "Limitations include no eating of toast".

Later I found in the CSS (v5): "The Flags AD type shall not be included in the scan response data." so rejecting that is correct.

The CSS has no requirements on the appearance of either Local Name data element except that only one instance shall appear [edit: in any packet]. Personally I don't think you should be preventing it, and it seems you're implementing the "no duplicates" not by checking for duplication but disallowing it in advertizing, which is inconvenient for a passive-scan use case.

I was getting INVALID_PARAM a lot while figuring things out; if I encounter it again I'll report the circumstances.

[Ulrich Myhre]

The Local Name should work in advertisement. I have personally been using it a lot there. The "no duplicates" check is both checking for a duplicate within the same data type (returns INVALID_DATA if so) and if the fields are present in adv/scan resp. simultaneously (returns INVALID_FLAGS in that case).

[pabigot]

OK. I can't get it to work, but I'm getting an invalid length error (when adv_data contains only Flags and a one-character complete local name, and sr_data is empty). Not important enough to spend more time on, though.

[Ulrich Myhre]

If you post the code you are having problems with, either by messaging me directly or by editing the original question, I can hopefully help you.