Cordio Documentation: Explain how to tests and what tools are available. #7417

pan- · 2018-07-04T11:17:20Z

Description

Improve the cordio porting documentation by explaining how tests can be run and describe the tooling available.

Pull request type

[ ] Fix
[ ] Refactor
[ ] New target
[X] Feature
[ ] Breaking change

0xc0170 · 2018-07-04T11:25:57Z

@ARMmbed/mbed-docs As @AnotherButler is OoO this week, can anyone else review this please

iriark01 · 2018-07-04T11:27:29Z

@MelindaWeed wanna meet something that isn't Mbed Cloud?

melwee01 · 2018-07-04T11:41:51Z

So long as it doesn't bite. Anything I should know before review, or is this standard procedure?

iriark01 · 2018-07-04T11:44:19Z

Take no prisoners?

melwee01 · 2018-07-04T12:27:40Z

I don't have push access. Could I be granted it temporarily, or should I fork?

donatieng · 2018-07-04T13:15:52Z

What do you need push access for @MelindaWeed ? Do you have reviewing rights?

pan- · 2018-07-04T13:21:40Z

@MelindaWeed I made sure you can push on my fork this pr branch.

melwee01 · 2018-07-04T13:22:16Z

Please do not merge until docs gives the thumbs-up. Working on it now.

@donatieng, I'm standing in for Amanda for docs review since she's OoO.

melwee01

I'd like to take a look at the whole file, if I may.

melwee01 · 2018-07-04T12:58:35Z

features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md

@@ -489,6 +489,26 @@ ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() {
 }
 ```

+### Tests
+
+Greentea tests are bundled with the cordio port of BLE API to ensure that the transport driver works as expected as well as validate the cordio stack initialization. You can run them with the following command:


Greentea tests are bundled with the Cordio port of the BLE API to make sure the transport driver works as expected, as well as to validate Cordio stack initialization. You can run them with the following command:

We don't typically use language that implies things might not work (as per the style guide). I'm not crazy about "works as expected."

Also, if the bundling is something Arm does, Arm should be the active subject of the sentence. Or "we."

Cordio capitalized throughout.

melwee01 · 2018-07-04T13:20:41Z

features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md

+mbed test -t <toolchain> -m <target> -n mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-driver,mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport
+```
+
+* mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport: Ensure that the transport is able to send an HCI reset command and receive the corresponding HCI status event.


Rather than ensure, I'd suggest check. Or make sure.

Rather than is able to, can. Reduces wordiness.

Query: Why don't you like "ensure"? I usually prefer it to "make sure" because it's shorter.

melwee01 · 2018-07-04T13:26:49Z

features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md

+
+The application [mbed-os-cordio-hci-passthrough](https://github.com/ARMmbed/mbed-os-cordio-hci-passthrough) can be used to _proxify_ a Bluetooth controller connected to an mbed board.
+
+Bytes sent by the host over the board serial are forwarded to the controller with the help of the `HCITransportDriver` while bytes sent by the controller are sent back to the host through the board serial.


Subject-verb disagreement in Runs the whole initialization process then ensure the cordio stack has been properly initialized by the HCI driver.

Is this a statement about what the driver does, or a command that the user must follow?

Passive -> active. Every sentence here could be streamlined by changing from passive to active.

0xc0170 · 2018-07-04T13:28:24Z

Please do not merge until docs gives the thumbs-up. Working on it now.

We always do 👍

melwee01 · 2018-07-04T13:29:28Z

I was about to thumbs-up your thumbs-up, but was afraid that might be misinterpreted. :)

melwee01 · 2018-07-04T14:21:00Z

So I'll need to do some pretty heavy restructuring/rewording to the rest of the file so it's compliant with our stylistic guidelines. What's the timeframe on this?

cmonr · 2018-07-05T22:09:21Z

@pan- Ping. ^^^

0xc0170 · 2018-07-25T12:34:07Z

@MelindaWeed Please update this pull request. Is it ready or still to be done?

melwee01 · 2018-07-25T12:39:23Z

Partially done. Update has jumped to the top of my list this sprint, sorry.

cmonr · 2018-08-09T01:41:16Z

@MelindaWeed Your timeframe question was never answered.
The sooner the better, but by the end of the month/by the 5.10 code freeze would be prefereable.

melwee01 · 2018-08-17T11:49:59Z

@pan- How do you feel about the signature line now?

0xc0170 · 2018-08-20T15:19:33Z

@pan- Please review (add those tags back in) and we should be good to go ?

pan- · 2018-08-23T09:42:55Z

@0xc0170 That's my PR so I github forbid me to approve it. I do approve @MelindaWeed changes.

0xc0170 · 2018-08-23T15:10:19Z

/morph build

mbed-ci · 2018-08-23T16:16:42Z

Build : SUCCESS

Build number : 2883
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/7417/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build
/morph mbed2-build

cmonr · 2018-08-23T17:15:40Z

Pausing Test CI until 5.9.6 PR is merged.
Will restart CI shortly after.

mbed-ci · 2018-08-23T18:00:39Z

Exporter Build : SUCCESS

Build number : 2505
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/7417/

cmonr · 2018-08-24T03:59:26Z

@MelindaWeed For reference, since I didn't see anyone clarify what happened with your picture.

You tried to directly push changes to an Mbed OS branch, in which most people don't have access to do (by design, and to the irritation of some).

You then pushed your changes to @pan-'s branch, which you did have access to, and because that branch has an active PR (this PR), your changes magically appeared!

cmonr · 2018-08-24T04:59:26Z

/morph test

melwee01 · 2018-08-24T05:24:36Z

Ahhhh, got it. Thanks! Still learning the ins and outs of git, and it finds constant ways to be surprising/frustrating.

cmonr · 2018-08-24T05:29:55Z

Still learning the ins and outs of git, and it finds constant ways to be surprising/frustrating.

Don't worry. I don't think that ever goes away.

mbed-ci · 2018-08-24T06:55:28Z

Test : SUCCESS

Build number : 2634
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/7417/2634

pan- requested a review from donatieng July 4, 2018 11:17

0xc0170 requested a review from a team July 4, 2018 11:25

Cordio Documentation: Explain how to tests and what tools are available.

7a8cc02

pan- force-pushed the improve-cordio-hci-doc branch from a02b666 to 7a8cc02 Compare July 4, 2018 11:47

0xc0170 added the needs: review label Jul 4, 2018

donatieng approved these changes Jul 4, 2018

View reviewed changes

melwee01 suggested changes Jul 4, 2018

View reviewed changes

Remove shall, whole lotta other changes. Not done yet.

bae4c89

cmonr added needs: work and removed needs: review labels Jul 25, 2018

Melinda Weed added 4 commits August 10, 2018 09:56

Further stylistic changes. Passive -> active

f2c6d59

grammatical and stylistic fixes, more passive -> active

739bd66

Fixing colons and formatting

db8f369

formatting changes

1082724

cmonr added the needs: review label Aug 13, 2018

removing \

c1e154b

adbridge added needs: work and removed needs: review labels Aug 15, 2018

function signature line

4a9570b

cmonr added needs: review and removed needs: work labels Aug 18, 2018

0xc0170 approved these changes Aug 23, 2018

View reviewed changes

0xc0170 added needs: CI and removed needs: review labels Aug 23, 2018

0xc0170 mentioned this pull request Aug 23, 2018

BLE: Cordio going open source #7869

Merged

cmonr added risk: G release-version: 5.10.0-rc1 labels Aug 23, 2018

0xc0170 added ready for merge and removed risk: G needs: CI labels Aug 24, 2018

0xc0170 merged commit 70814d6 into ARMmbed:master Aug 24, 2018

0xc0170 removed the ready for merge label Aug 24, 2018


		The application [mbed-os-cordio-hci-passthrough](https://github.com/ARMmbed/mbed-os-cordio-hci-passthrough) can be used to _proxify_ a Bluetooth controller connected to an mbed board.

		Bytes sent by the host over the board serial are forwarded to the controller with the help of the `HCITransportDriver` while bytes sent by the controller are sent back to the host through the board serial.

Cordio Documentation: Explain how to tests and what tools are available. #7417

Cordio Documentation: Explain how to tests and what tools are available. #7417

Uh oh!

Conversation

pan- commented Jul 4, 2018

Description

Pull request type

Uh oh!

0xc0170 commented Jul 4, 2018

Uh oh!

iriark01 commented Jul 4, 2018

Uh oh!

melwee01 commented Jul 4, 2018

Uh oh!

iriark01 commented Jul 4, 2018

Uh oh!

melwee01 commented Jul 4, 2018

Uh oh!

donatieng commented Jul 4, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pan- commented Jul 4, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

melwee01 commented Jul 4, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

melwee01 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 commented Jul 4, 2018

Uh oh!

melwee01 commented Jul 4, 2018

Uh oh!

melwee01 commented Jul 4, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cmonr commented Jul 5, 2018

Uh oh!

0xc0170 commented Jul 25, 2018

Uh oh!

melwee01 commented Jul 25, 2018

Uh oh!

cmonr commented Aug 9, 2018

Uh oh!

melwee01 commented Aug 17, 2018

Uh oh!

0xc0170 commented Aug 20, 2018

Uh oh!

pan- commented Aug 23, 2018

Uh oh!

0xc0170 commented Aug 23, 2018

Uh oh!

mbed-ci commented Aug 23, 2018

Triggering tests

Uh oh!

cmonr commented Aug 23, 2018

Uh oh!

mbed-ci commented Aug 23, 2018

Uh oh!

cmonr commented Aug 24, 2018

Uh oh!

cmonr commented Aug 24, 2018

Uh oh!

melwee01 commented Aug 24, 2018

Uh oh!

donatieng commented Jul 4, 2018 •

edited

Loading

pan- commented Jul 4, 2018 •

edited

Loading

melwee01 commented Jul 4, 2018 •

edited

Loading

melwee01 commented Jul 4, 2018 •

edited

Loading

cmonr commented Aug 24, 2018 •

edited

Loading