Updated for beta, new tutorial doc Added a tutorial doc for BLE Peripheral, complete with pictures.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/31d56312 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/31d56312 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/31d56312 Branch: refs/heads/develop Commit: 31d56312a83944fb50c7195f9aedb69dd64938b0 Parents: cc3415e Author: David G. Simmons <[email protected]> Authored: Thu Oct 27 12:48:05 2016 -0400 Committer: David G. Simmons <[email protected]> Committed: Thu Oct 27 12:48:05 2016 -0400 ---------------------------------------------------------------------- docs/os/tutorials/bleprph/bleprph-app.md | 110 ++++++++++++++++++++++++++ docs/os/tutorials/bletiny_project.md | 83 +++++++++++-------- docs/os/tutorials/pics/LightBlue-1.jpg | Bin 0 -> 90014 bytes docs/os/tutorials/pics/LightBlue-2.jpg | Bin 0 -> 121238 bytes docs/os/tutorials/pics/LightBlue-3.jpg | Bin 0 -> 122447 bytes docs/os/tutorials/pics/LightBlue-4.jpg | Bin 0 -> 94431 bytes docs/os/tutorials/pics/LightBlue-5.jpg | Bin 0 -> 53663 bytes docs/os/tutorials/pics/LightBlue-6.jpg | Bin 0 -> 97461 bytes mkdocs.yml | 3 +- 9 files changed, 160 insertions(+), 36 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/bleprph/bleprph-app.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/bleprph/bleprph-app.md b/docs/os/tutorials/bleprph/bleprph-app.md new file mode 100644 index 0000000..a0a51c1 --- /dev/null +++ b/docs/os/tutorials/bleprph/bleprph-app.md @@ -0,0 +1,110 @@ +## BLE Peripheral Project + +###Overview + +<br> + +Now that we've gone through how BLE Apps are contructed, how they function, and how all the parts fit together +let's try out a BLE Peripheral App to see how it all works. + +<br> + +###Prerequisites + +<br> + +* You should already have completed the previous [BLE Tiny Project](../bletiny_project.md), though it's not required. +* You should have a BLE Central App of some sort to connect with. On Mac OS or iOS, you can use [LightBlue](https://itunes.apple.com/us/app/lightblue-explorer-bluetooth/id557428110?mt=8) +which is a free app to browse and connect to BLE Peripheral devices. + +<br> + +###Create a New Target + +You can create a new project instead, but this tutorial will simply use the previously created bletiny project and add a new target for the BLE Peripheral + +``` +$ newt target create myperiph +Target targets/myperiph successfully created +$ newt target set myperiph bsp=@apache-mynewt-core/hw/bsp/nrf52dk +Target targets/myperiph successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk +$ newt target set myperiph app=@apache-mynewt-core/apps/bleprph +Target targets/myperiph successfully set target.app to @apache-mynewt-core/apps/bleprph +$ newt target set myperiph build_profile=optimized +Target targets/myperiph successfully set target.build_profile to optimized +$ newt target set myperiph cflags=-DSTATS_NAME_ENABLE +Target targets/myperiph successfully set pkg.cflags to -DSTATS_NAME_ENABLE +$ newt build blerph +Building target targets/myperiph +... +Linking /Users/dsimmons/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.elf +Target successfully built: targets/myperiph +$ newt create-image myperiph 1.0.0 +App image succesfully generated: /Users/dsimmons/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.img +$ newt load myperiph +Loading app image into slot 1 +``` + +Now if you reset the board, and fire up your BLE Central App, you should see a new peripheral device called 'nimble-bleprph'. + +<br> + + + +<br> + +Now that you can see the device, you can begin to interact with the advertised service. + +Click on the device and you'll establish a connection. + +<br> + + + +<br> + +Now that you're connected, you can see the Services that are being advertised. + +Scroll to the bottom and you will see a Read Characteristic, and a Read/Write Characteristic. + + + +<br> + +Just click on the Read Write Characteristic and you will see the existing value. + + + +<br> + +Type in a new value. + + + +<br> + +And you will see the new value reflected. + + + +<br> + +If you still have your console connected, you will be able to see the connection requests, and pairing, +happen on the device as well. + +<br> + +```hl_lines="1" +258894:[ts=2022609336ssb, mod=64 level=1] connection established; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=0 authenticated=0 bonded=0 +258904:[ts=2022687456ssb, mod=64 level=1] +258917:[ts=2022789012ssb, mod=64 level=1] mtu update event; conn_handle=1 cid=4 mtu=185 +258925:[ts=2022851508ssb, mod=64 level=1] subscribe event; conn_handle=1 attr_handle=14 reason=1 prevn=0 curn=0 previ=0 curi=1 +261486:[ts=2042859320ssb, mod=64 level=1] encryption change event; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=1 authenticated=0 bonded=1 +261496:[ts=2042937440ssb, mod=64 level=1] +``` + +<br> + +Congratulations! You've just built and connected your first BLE Peripheral device! + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/bletiny_project.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/bletiny_project.md b/docs/os/tutorials/bletiny_project.md index 495a8b3..51f4594 100644 --- a/docs/os/tutorials/bletiny_project.md +++ b/docs/os/tutorials/bletiny_project.md @@ -59,11 +59,15 @@ targets/nrf52_boot <br> -Define the targets further. Note that you are using the example app `bletiny` for the application target. Set the bsp correctly (nrf52pdk or nrf52dk depending on whether the board is the preview kit or the dev kit, respectively. Look on the top of your board, if you see PCA100040, use the nrf52dk version, otherwide use the nrf52pdk version). +Define the targets further. Note that you are using the example app `bletiny` for the application target. Set the bsp + +**NOTE:** The preview version, nrf52pdk, is no longer supported. If you do not see PCA100040 on the top of your board, you have a preview version of the board and will need to upgrade your developer board before continuing. + +<br> ``` -$ newt target set myble bsp=@apache-mynewt-core/hw/bsp/nrf52pdk -Target targets/myble successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52pdk +$ newt target set myble bsp=@apache-mynewt-core/hw/bsp/nrf52dk +Target targets/myble successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk $ newt target set myble app=@apache-mynewt-core/apps/bletiny Target targets/myble successfully set target.app to @apache-mynewt-core/apps/bletiny $ newt target set myble build_profile=optimized @@ -77,7 +81,7 @@ Use the same `newt target set` command to set the following definition for the b ``` targets/nrf52_boot app=@apache-mynewt-core/apps/boot - bsp=@apache-mynewt-core/hw/bsp/nrf52pdk + bsp=@apache-mynewt-core/hw/bsp/nrf52dk build_profile=optimized ``` @@ -91,12 +95,12 @@ targets/my_blinky_sim build_profile=debug targets/myble app=@apache-mynewt-core/apps/bletiny - bsp=@apache-mynewt-core/hw/bsp/nrf52pdk + bsp=@apache-mynewt-core/hw/bsp/nrf52dk build_profile=optimized cflags=-DSTATS_NAME_ENABLE targets/nrf52_boot app=@apache-mynewt-core/apps/boot - bsp=@apache-mynewt-core/hw/bsp/nrf52pdk + bsp=@apache-mynewt-core/hw/bsp/nrf52dk build_profile=optimized ``` @@ -170,26 +174,38 @@ Port /dev/tty.usbserial-AJ03HAQQ, 09:57:17 Press Meta-Z for help on special keys ? -4828455:log echo ? tasks mempools date -4828457:stat b +4754:Commands: +4754: echo ? prompt tasks mempools date +4756: b ``` <br> -Try the `stat` command. +If you'd like a shell prompt, try the `prompt` command. +```hl_lines="1" +prompt +14025:Usage: prompt [set|show] [prompt_char] +prompt set > +15086:Prompt set to: > +15086:Usage: prompt [set|show] [prompt_char] +15087: > +``` + +You'll notice that there is an ever-increasing counter before the prompt (and before any output to the terminal). +This is just a counter kept by the MCU. + +<br> + +Try the `tasks` command. ```hl_lines="1" -stat -4973017:Must specify a statistic name to dump, possible names are: -4973021: stat -4973022: ble_l2cap -4973024: ble_att -4973026: ble_gap -4973027: ble_gattc -4973029: ble_gatts -4973031: ble_hs -4973032: ble_ll_conn -4973034: ble_ll +27365: > tasks +Tasks: +28330: idle (prio: 255, tid: 0, lcheck: 0, ncheck: 0, flags: 0x0, ssize: 64, susage: 34, cswcnt: 233, tot_run_time: 28330ms) +28333: ble_ll (prio: 0, tid: 1, lcheck: 0, ncheck: 0, flags: 0x0, ssize: 80, susage: 60, cswcnt: 11, tot_run_time: 0ms) +28336: shell (prio: 1, tid: 2, lcheck: 0, ncheck: 0, flags: 0x0, ssize: 512, susage: 115, cswcnt: 18, tot_run_time: 0ms) +28339: bletiny (prio: 1, tid: 3, lcheck: 0, ncheck: 0, flags: 0x0, ssize: 512, susage: 138, cswcnt: 456, tot_run_time: 0ms) +28342: > ``` <br> @@ -218,21 +234,18 @@ stat ble_ll For a more exciting output, try scanning your surroundings for BLE adverstisements. The HCI command shown below specifies a scan duration in ms, sets discovery mode to general (as opposed to limited), the filter to no-whitelist, and type of scan to passive. You should see some scan data flying by! ```hl_lines="1" -b scan dur=10000 disc=gen filt=no_wl type=passive - -5301227:[ts=5301227ssb, mod=4 level=1] host_hci_cmd_send: ogf=0x08 ocf=0x0b len=7 -5301233:[ts=5301233ssb, mod=4 level=1] Command Complete: cmd_pkts=1 ogf=0x8 ocf=0xb status=0 -5301241:[ts=5301241ssb, mod=4 level=1] host_hci_cmd_send: ogf=0x08 ocf=0x0c len=2 -5301248:[ts=5301248ssb, mod=4 level=1] Command Complete: cmd_pkts=1 ogf=0x8 ocf=0xc status=0 -GAP procedure initiated: discovery; disc_mode=2 filter_policyLE advertising report. len=38 num=1 evtype=3 addr9 -5301270:[ts=5301270ssb, mod=4 level=1] 02 01 06 03 03 aa fe 12 -5301276:[ts=5301276ssb, mod=4 level=1] 16 aa fe 10 f6 02 67 2e -5301281:[ts=5301281ssb, mod=4 level=1] 63 6f 2f 62 65 61 63 6f -5301287:[ts=5301287ssb, mod=4 level=1] 6e 73 -5301291:[ts=5301291ssb, mod=64 level=2] received advertisement; event_type=3 addr_type=1 addr=0xa0:0x0d:0xec:0: -5301316:[ts=5301316ssb, mod=64 level=2] flags=0x06 -5301321:[ts=5301321ssb, mod=64 level=2] uuids16(complete)=0xfeaa -5301327:[ts=5301327ssb, mod=64 level=2] svc_data_uuid16= +139088: > b scan dur=10000 disc=gen filt=no_wl type=passive +... +146055:received advertisement; event_type=0 addr_type=1 addr=6b:aa:49:b7:46:e6 length_data=24 rssi=-42 data=0x02:0x01:0x1a:0x14:0xff:0x4c:0x00:0x01:0x00:0x00:0x00:0x00:0x04:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00 fields: +146061: flags=0x1a +146062: mfg_data=0x4c:0x00:0x01:0x00:0x00:0x00:0x00:0x04:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00 +146065: +146065:received advertisement; event_type=0 addr_type=0 addr=ac:bc:32:ac:4f:e4 length_data=11 rssi=-36 data=0x02:0x01:0x06:0x07:0xff:0x4c:0x00:0x10:0x02:0x0b:0x00 fields: +146069: flags=0x06 +146070: mfg_data=0x4c:0x00:0x10:0x02:0x0b:0x00 +146071: +146072:scanning finished +... <snip> ``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-1.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-1.jpg b/docs/os/tutorials/pics/LightBlue-1.jpg new file mode 100644 index 0000000..87a305e Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-1.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-2.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-2.jpg b/docs/os/tutorials/pics/LightBlue-2.jpg new file mode 100644 index 0000000..715deff Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-2.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-3.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-3.jpg b/docs/os/tutorials/pics/LightBlue-3.jpg new file mode 100644 index 0000000..5ceb627 Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-3.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-4.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-4.jpg b/docs/os/tutorials/pics/LightBlue-4.jpg new file mode 100644 index 0000000..a8e35c3 Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-4.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-5.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-5.jpg b/docs/os/tutorials/pics/LightBlue-5.jpg new file mode 100644 index 0000000..4a3cbbd Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-5.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/docs/os/tutorials/pics/LightBlue-6.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/LightBlue-6.jpg b/docs/os/tutorials/pics/LightBlue-6.jpg new file mode 100644 index 0000000..eb4ca4d Binary files /dev/null and b/docs/os/tutorials/pics/LightBlue-6.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/31d56312/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index a7dd702..f39ac4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ pages: - 'Characteristic Access': 'os/tutorials/bleprph/bleprph-chr-access.md' - 'Advertising': 'os/tutorials/bleprph/bleprph-adv.md' - 'GAP Event Callbacks': 'os/tutorials/bleprph/bleprph-gap-event.md' + - 'BLE Peripheral App' : 'os/tutorials/bleprph/bleprph-app.md' - 'BLE iBeacon': 'os/tutorials/ibeacon.md' - 'BLE HCI interface': 'os/tutorials/blehci_project.md' - OS User Guide: @@ -497,7 +498,7 @@ markdown_extensions: pygments_style: xcode extra: - version: 'none' + version: 'v0_9_0' versions: - label: 'develop' branch: 'develop'
