feat!: add ble state 'initiating'

[gabrielsantosphilips]

This PR adds the missing GAP state "initiate" as mentioned in the BLUETOOTH CORE SPECIFICATION Version 5.3 (Vol 6, Part B, 1.1 LINK LAYER STATES). This state specifically impacts BLE Central and is unrelated to other roles.

The "initiate" state allows for detection of connection failures when no events are returned from the stack, which can block further stack operations.

Two potential scenarios for this state are:

Attempting to connect to a device that does not exist (e.g., due to a wrong MAC address).
The peripheral crashing or entering an undefined state between scanning and connecting, regardless of the cause.

The BLUETOOTH CORE SPECIFICATION Version 5.3 | Vol 6, Part B, 4.5 CONNECTION STATE explains in detail how a connection works:

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details

Scanned Files

[github-actions]

🦙 MegaLinter status: ⚠️ WARNING

Descriptor	Linter	Files	Fixed	Errors	Elapsed time
✅ ACTION	actionlint	12		0	0.03s
✅ CPP	clang-format	994	3	0	6.94s
✅ DOCKERFILE	hadolint	2		0	0.09s
✅ JSON	jsonlint	9		0	0.12s
✅ JSON	prettier	9	0	0	0.7s
⚠️ MARKDOWN	markdownlint	6	0	4	1.61s
⚠️ MARKDOWN	markdown-link-check	6		1	78.16s
✅ MARKDOWN	markdown-table-formatter	6	0	0	0.37s
✅ REPOSITORY	checkov	yes		no	19.69s
✅ REPOSITORY	git_diff	yes		no	0.05s
✅ REPOSITORY	grype	yes		no	16.71s
✅ REPOSITORY	ls-lint	yes		no	0.07s
✅ REPOSITORY	secretlint	yes		no	7.36s
✅ REPOSITORY	trivy	yes		no	21.66s
✅ REPOSITORY	trivy-sbom	yes		no	0.09s
✅ REPOSITORY	trufflehog	yes		no	2.09s
⚠️ SPELL	lychee	140		2	2.74s
⚠️ YAML	prettier	23	1	1	1.1s
✅ YAML	v8r	23		0	11.21s
✅ YAML	yamllint	23		0	0.35s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

[oguzcanoguz]

I am not 100% aligned on the problems PR is trying to solve.

1. Attempting to connect to a device that does not exist (e.g., due to a wrong MAC address).
2. The peripheral crashing or entering an undefined state between scanning and connecting, regardless of the cause.

In both cases, stack should not be able so send CONNECT_IND to the peer and we should not receive connection complete event.
So we are in the initiating state and cannot switch to connected state.
What happens when this is the case? Don't we get any event at all?

So these cases do not reflect the figure:

The case described in the above figure seems different.
There we are able to go to the connected state but not able to exhange any data packets.
In this case, ble stack should eventually emit a disconnected event.
Is the timing of this event too long? Is it related to supervision timeout?

[gabrielsantosphilips]

@oguzcanoguz I updated the picture on philips-software/amp-hal-st#420 to reflect the problem correctly as we just discussed.

[oguzcanoguz]

@oguzcanoguz I updated the picture on philips-software/amp-hal-st#420 to reflect the problem correctly as we just discussed.

[oguzcanoguz]

@gabrielsantosphilips Thanks.
Now I better understand the issue.
I also can see why ST ble stack cannot determine a time-out itself: The stack does not know about the advertising interval of the peripheral. It can be from 20ms to 10.24 seconds. And it can also be a noisy environment where not all the advertising packets reach the central. It cannot know when to stop listening.

Just for this reason, I recommend also not having a fixed time-out inside our GapCentral implementation; we cannot possibly know when to expect the next advertising packet.
I'd suggest adding an optional time-out argument to GapCentral::Connect.
After all, the user would likely to know better about what to expect, e.g. a noisy environment.

I'd also add a comment for the Connect method to briefly expain that calling connect will first trigger a state update with Initiating and then either another update to Connected or to Standby if there is time-out.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud