You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/01/16 22:21:23 UTC
[GitHub] aditihilbert closed pull request #737: Removes BLE tutorial sections from /docs and moves them to mynewt-documentation repo
aditihilbert closed pull request #737: Removes BLE tutorial sections from /docs and moves them to mynewt-documentation repo
URL: https://github.com/apache/mynewt-core/pull/737
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/tutorials/ble/ble_bare_bones.rst b/docs/os/tutorials/ble/ble_bare_bones.rst
deleted file mode 100644
index 1d7c09505..000000000
--- a/docs/os/tutorials/ble/ble_bare_bones.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-Set up a bare bones NimBLE application
-=======================================
-
-.. toctree::
- :hidden:
-
- ibeacon
- eddystone
- bleprph/bleprph
- blehci_project/
-
-This tutorial explains how to set up a minimal application using the
-NimBLE stack. This tutorial assumes that you have already installed the
-newt tool and are familiar with its concepts.
-
-Create a Mynewt project
-~~~~~~~~~~~~~~~~~~~~~~~
-
-We start by creating a project space for your own application work using
-the Newt tool. We will call our project ``my_proj``.
-
-::
-
- ~/dev$ newt new my_proj1
- Downloading project skeleton from apache/mynewt-blinky...
- Installing skeleton in my_proj1...
- Project my_proj1 successfully created.
-
-The above command created the following directory tree:
-
-::
-
- ~/dev$ tree my_proj1
- my_proj1
- ??? DISCLAIMER
- ??? LICENSE
- ??? NOTICE
- ??? README.md
- ??? apps
- ??? ??? blinky
- ??? ??? pkg.yml
- ??? ??? src
- ??? ??? main.c
- ??? project.yml
- ??? targets
- ??? my_blinky_sim
- ??? ??? pkg.yml
- ??? ??? target.yml
- ??? unittest
- ??? pkg.yml
- ??? target.yml
-
- 6 directories, 11 files
-
-Next, we need to retrieve the Mynewt repositories that our app will
-depend on. When you retrieve a repository, your project gains access to
-the libraries and applications that the repo contains.
-
-A new project automatically depends on the Apache Mynewt core repo
-(``apache-mynewt-core``). The core repo contains the Apache Mynewt
-operating system, NimBLE stack, and other system libraries. Later, our
-app may need packages from additional repos, but for now the core repo
-suits our needs.
-
-We download the dependent repos using the ``newt install`` command:
-
-::
-
- ~/dev$ cd my_proj1
- ~/dev/my_proj1$ newt install
- apache-mynewt-core
-
-Now it's time to create your own app.
-
-Create an application package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: console
-
- ~/dev/my_proj1$ newt pkg new apps/ble_app -t app
- Download package template for package type app.
- Package successfully installed into /home/me/dev/my_proj1/apps/ble_app.
-
-You now have an application called ``apps/ble_app``. It isn't terribly
-interesting as far as applications go, but it does all the configuration
-and set up required of a Mynewt app. It will be a useful starting point
-for our BLE application.
-
-Create the target
-~~~~~~~~~~~~~~~~~
-
-Now you have to create the target that ties your application to a BSP.
-We will call this target "ble\_tgt".
-
-.. code-block:: console
-
- ~/dev/my_proj1$ newt target create ble_tgt
- Target targets/ble_tgt successfully created
-
-We now have a new target:
-
-::
-
- ~/dev/my_proj1]$ tree targets/ble_tgt
- targets/ble_tgt
- ??? pkg.yml
- ??? target.yml
-
-We need to fill out a few details in our target before it is usable. At
-a minimum, a target must specify three bits of information:
-
-- Application pacakge
-- BSP package
-- Build profile
-
-The application package is straightforward; this is the ble\_app package
-that we created in the previous step.
-
-For the BSP package, this tutorial chooses to target the nRF52dk BSP. If
-you would like to use a different platform, substitute the name of the
-appropriate BSP package in the command below.
-
-Finally, the build profile specifies the set of compiler and linker
-options to use during the build. Apache Mynewt supports two build
-profiles: ``debug`` and ``optimized``.
-
-.. code-block:: console
-
- ~/dev/my_proj1$ newt target set ble_tgt \
- app=apps/ble_app \
- bsp=@apache-mynewt-core/hw/bsp/nrf52dk \
- build_profile=optimized
- Target targets/ble_tgt successfully set target.app to apps/ble_app
- Target targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk
- Target targets/ble_tgt successfully set target.build_profile to optimized
-
-Enter BLE
-~~~~~~~~~
-
-Since our application will support BLE functionality, we need to give it
-access to a BLE stack. We do this by adding the necessary NimBLE
-packages to the app's dependency list. To enable a combined
-host-controller in the app, add dependencies for the NimBLE controller,
-host, and in-RAM transport to ``apps/ble_app/pkg.yml``:
-
-``hl_lines="6 7 8" pkg.deps: - "@apache-mynewt-core/kernel/os" - "@apache-mynewt-core/sys/console/full" - "@apache-mynewt-core/sys/log/full" - "@apache-mynewt-core/sys/stats/full" - "@apache-mynewt-core/net/nimble/controller" - "@apache-mynewt-core/net/nimble/host" - "@apache-mynewt-core/net/nimble/transport/ram"``
-
-**Important note:** The controller package affects system configuration,
-see `this page <../../../network/ble/ble_setup/ble_lp_clock/>`__ for
-details.
-
-Build the target
-~~~~~~~~~~~~~~~~
-
-Now would be a good time for a basic sanity check. Let's make sure the
-target builds.
-
-::
-
- ~/dev/my_proj1$ newt build ble_tgt
- Building target targets/ble_tgt
- Compiling repos/apache-mynewt-core/hw/hal/src/hal_common.c
- Compiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c
- <...snip...>
- Linking /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.elf
- Target successfully built: targets/ble_tgt
-
-Now let's try running our minimal application on actual hardware. Attach
-the target device to your computer and run the application with
-``newt run``:
-
-::
-
- ~/dev/my_proj1$ newt run ble_tgt 0
- App image succesfully generated: /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.img
- <...snip...>
- Resetting target
- [Switching to Thread 57005]
- 0x000000dc in ?? ()
- (gdb)
-
-You can start the application by pressing ``c <enter>`` at the gdb
-prompt. When the excitement of watching the idle loop run wears off,
-quit gdb with ``<ctrl-c> q <enter>``.
-
-If your target fails to build or run, you might want to revisit the
-`project blinky tutorial <../../../os/tutorials/blinky/>`__ to see if
-there is a setup step you missed. You may also find help by posting a
-question to the `mailing list <../../community.html>`__ or searching the
-archives.
-
-Conclusion
-~~~~~~~~~~
-
-You now have a fully functional BLE app (never mind that it doesn't
-actually do anything yet!). With all the necessary infrastructure in
-place, you can now start turning this into a real application. A good
-next step would be to turn your app into a beaconing device. The `BLE
-iBeacon tutorial <../../../os/tutorials/ibeacon/>`__ builds on this one
-and ends with a functioning iBeacon. For something a little more
-ambitious, the `BLE peripheral project
-tutorial <../../../os/tutorials/bleprph/bleprph-intro/>`__ describes a
-NimBLE peripheral application in detail.
diff --git a/docs/os/tutorials/ble/blehci_project.rst b/docs/os/tutorials/ble/blehci_project.rst
deleted file mode 100644
index c03483a53..000000000
--- a/docs/os/tutorials/ble/blehci_project.rst
+++ /dev/null
@@ -1,233 +0,0 @@
-Use HCI access to NimBLE controller
------------------------------------
-
-This tutorial explains how to use the example application ``blehci``
-included in the NimBLE stack to talk to the Mynewt NimBLE controller via
-the Host Controller Interface. You may build the Mynewt image using a
-laptop running any OS of your choice - Mac, Linux, or Windows.
-
-The host used in this specific example is the BlueZ Bluetooth stack.
-Since BlueZ is a Bluetooth stack for Linux kernel-based family of
-operating system, the tutorial expects a computer running Linux OS and
-with BlueZ installed to talk to the board with the Mynewt image.
-
-Prerequisites
-~~~~~~~~~~~~~
-
-Ensure that you meet the following prerequisites before continuing with
-one of the tutorials.
-
-- Have Internet connectivity to fetch remote Mynewt components.
-- Have a board with BLE radio that is supported by Mynewt. We will use
- an nRF52 Dev board in this tutorial.
-- Have a USB TTL Serial Cable that supports hardware flow control such
- as ones found at
- http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm to establish
- a serial USB connection between the board and the laptop.
-- Install the newt tool and toolchains (See `Basic
- Setup </os/get_started/get_started.html>`__).
-- Install a BLE host such as BlueZ on a Linux machine to talk to the
- nrf52 board running Mynewt. Use ``sudo apt-get install bluez`` to
- install it on your Linux machine.
-
-Create a project
-~~~~~~~~~~~~~~~~
-
-Use the newt tool to create a new project directory containing a
-skeletal Mynewt framework. Change into the newly created directory.
-
-::
-
- $ newt new blehciproj
- Downloading project skeleton from apache/mynewt-blinky...
- Installing skeleton in blehciproj ...
- Project blehciproj successfully created.
- $ cd mblehciproj
-
- $ newt install
- apache-mynewt-core
-
-Create targets
-~~~~~~~~~~~~~~
-
-You will create two targets - one for the bootloader, the other for the
-application. Then you will add the definitions for them. Note that you
-are using the example app ``blehci`` for the application target. Set the
-bsp to nrf52dk.
-
-**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.
-
-::
-
- $ newt target create nrf52_boot
- $ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot
- $ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk
- $ newt target set nrf52_boot build_profile=optimized
-
-::
-
- $ newt target create myble2
- $ newt target set myble2 bsp=@apache-mynewt-core/hw/bsp/nrf52dk
- $ newt target set myble2 app=@apache-mynewt-core/apps/blehci
- $ newt target set myble2 build_profile=optimized
-
-Check that the targets are defined correctly.
-
-::
-
- $ newt target show
- targets/my_blinky_sim
- app=apps/blinky
- bsp=@apache-mynewt-core/hw/bsp/native
- build_profile=debug
- targets/myble2
- app=@apache-mynewt-core/apps/blehci
- bsp=@apache-mynewt-core/hw/bsp/nrf52dk
- build_profile=optimized
- targets/nrf52_boot
- app=@apache-mynewt-core/apps/boot
- bsp=@apache-mynewt-core/hw/bsp/nrf52dk
- build_profile=optimized
-
-Build targets
-~~~~~~~~~~~~~
-
-Then build the two targets.
-
-.. code-block:: console
-
- $ newt build nrf52_boot
- <snip>
- Linking ~/dev/blehciproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf
- Target successfully built: targets/nrf52_boot
-
- $ newt build myble2
- <snip>
- Linking ~/dev/blehciproj/bin/targets/myble2/app/apps/blehci/blehci.elf
- Target successfully built: targets/myble2
- $
-
-Create the app image
-~~~~~~~~~~~~~~~~~~~~
-
-Generate a signed application image for the ``myble2`` target. The
-version number is arbitrary.
-
-.. code-block:: console
-
- $ newt create-image myble2 1.0.0
- App image succesfully generated: ~/dev/blehciproj/bin/targets/myble2/app/apps/bletiny/bletiny.img
-
-Load the bootloader and the application image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Make sure the USB connector is in place and the power LED on the board
-is lit. Use the Power ON/OFF switch to reset the board after loading the
-image.
-
-Load the bootloader:
-
-.. code-block:: console
-
- $ newt load nrf52_boot
- Loading bootloader
- $
-
-Load the application image:
-
-.. code-block:: console
-
- $ newt load myble2
- Loading app image into slot 1
- $
-
-Establish serial connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Attach a serial port to your board by connecting the USB TTL Serial
-Cable. This should create /dev/ttyUSB0 (or similar) on your machine.
-
-**Note** Certain Linux OS versions have been observed to detect the
-nrf52 board as a mass storage device and the console access doesn?t work
-properly. In that case try powering the nrf52 board from your monitor or
-something other than your Linux computer/laptop when you set up the
-serial port for HCI communication.
-
-Open Bluetooth monitor btmon
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``btmon`` is a BlueZ test tool to display all HCI commands and events in
-a human readable format. Start the btmon tool in a terminal window.
-
-::
-
- $ sudo btmon
- [sudo] password for admin:
- Bluetooth monitor ver 5.37
-
-Attach the blehci device to BlueZ
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In a different terminal, attach the blehci device to the BlueZ daemon
-(substitute the correct /dev filename for ttyUSB0).
-
-::
-
- $ sudo btattach -B /dev/ttyUSB0 -S 1000000
- Attaching BR/EDR controller to /dev/ttyUSB0
- Switched line discipline from 0 to 15
- Device index 1 attached
-
-The baud rate used to connect to the controller may be changed by
-overriding the default value of 1000000 in the
-``net/nimble/transport/uart/syscfg.yml``. Settings in the serial
-transport ``syscfg.yml`` file can be overridden by a higher priority
-package such as the application. So, for example, you may set the
-``BLE_HCI_UART_BAUD`` to a different value in
-``apps/blehci/syscfg.yml``.
-
-If there is no CTS/RTS lines present in the test environment, flow
-control should be turned off. This can be done with -N option for
-btattach. **Note:** -N option came with BlueZ ver 5.44.
-
-Start btmgmt to send commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In a third terminal, start btmgmt. This tool allows you to send commands
-to the blehci controller. Use the index number that shows up when you
-``btattach`` in the previous step.
-
-::
-
- $ sudo btmgmt --index 1
- [sudo] password for admin:
-
-Set your device address (you can substitute any static random address
-here).
-
-::
-
- [hci1]# static-addr cc:11:11:11:11:11
- Static address successfully set
-
-Initialize the controller.
-
-::
-
- [hci1]# power on
- hci1 Set Powered complete, settings: powered le static-addr
-
-Begin scanning.
-
-::
-
- [hci1]# find -l
- Discovery started
- hci1 type 6 discovering on
- hci1 dev_found: 58:EF:77:C8:8D:17 type LE Random rssi -78 flags 0x0000
- AD flags 0x06
- eir_len 23
- <snip>
diff --git a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-adv.rst b/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-adv.rst
deleted file mode 100644
index 9bb0bd85f..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-adv.rst
+++ /dev/null
@@ -1,145 +0,0 @@
-Advertising
-===========
-
-Overview
-^^^^^^^^
-
-A peripheral announces its presence to the world by broadcasting
-advertisements. An advertisement typically contains additional
-information about the peripheral sending it, such as the device name and
-an abbreviated list of supported services. The presence of this
-information helps a listening central to determine whether it is
-interested in connecting to the peripheral. Advertisements are quite
-limited in the amount of information they can contain, so only the most
-important information should be included.
-
-When a listening device receives an advertisement, it can choose to
-connect to the peripheral, or query the sender for more information.
-This second action is known as an *active scan*. A peripheral responds
-to an active scan with some extra information that it couldn't fit in
-its advertisement. This additional information is known as *scan
-response data*. *bleprph* does not configure any scan response data, so
-this feature is not discussed in the remainder of this tutorial.
-
-*bleprph* constantly broadcasts advertisements until a central connects
-to it. When a connection is terminated, *bleprph* resumes advertising.
-
-Let's take a look at *bleprph*'s advertisement code (*main.c*):
-
-.. code:: c
-
- /**
- * Enables advertising with the following parameters:
- * o General discoverable mode.
- * o Undirected connectable mode.
- */
- static void
- bleprph_advertise(void)
- {
- struct ble_hs_adv_fields fields;
- int rc;
-
- /* Set the advertisement data included in our advertisements. */
- memset(&fields, 0, sizeof fields);
- fields.name = (uint8_t *)bleprph_device_name;
- fields.name_len = strlen(bleprph_device_name);
- fields.name_is_complete = 1;
- rc = ble_gap_adv_set_fields(&fields);
- if (rc != 0) {
- BLEPRPH_LOG(ERROR, "error setting advertisement data; rc=%d\n", rc);
- return;
- }
-
- /* Begin advertising. */
- rc = ble_gap_adv_start(BLE_GAP_DISC_MODE_GEN, BLE_GAP_CONN_MODE_UND,
- NULL, 0, NULL, bleprph_on_connect, NULL);
- if (rc != 0) {
- BLEPRPH_LOG(ERROR, "error enabling advertisement; rc=%d\n", rc);
- return;
- }
- }
-
-Now let's examine this code in detail.
-
-Setting advertisement data
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A NimBLE peripheral specifies what information to include in its
-advertisements with the following function:
-
-.. code:: c
-
- int
- ble_gap_adv_set_fields(struct ble_hs_adv_fields *adv_fields)
-
-The *adv\_fields* argument specifies the fields and their contents to
-include in subsequent advertisements. The Bluetooth `Core Specification
-Supplement <https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=302735>`__
-defines a set of standard fields that can be included in an
-advertisement; the member variables of the *struct ble\_hs\_adv\_fields*
-type correspond to these standard fields. Information that doesn't fit
-neatly into a standard field should be put in the *manufacturing
-specific data* field.
-
-As you can see in the above code listing, the
-``struct ble_hs_adv_fields`` instance is allocated on the stack. It is
-OK to use the stack for this struct and the data it references, as the
-``ble_gap_adv_set_fields()`` function makes a copy of all the
-advertisement data before it returns. *bleprph* doesn't take full
-advantange of this; it stores its device name in a static array.
-
-The code sets three members of the *struct ble\_hs\_adv\_fields*
-instance:
-
-- name
-- name\_len
-- name\_is\_complete
-
-The first two fields are used to communicate the device's name and are
-quite straight-forward. The third field requires some explanation.
-Bluetooth specifies two name-related advertisement fields: *Shortened
-Local Name* and *Complete Local Name*. Setting the ``name_is_complete``
-variable to 1 or 0 tells NimBLE which of these two fields to include in
-advertisements. Some other advertisement fields also correspond to
-multiple variables in the field struct, so it is a good idea to review
-the *ble\_hs\_adv\_fields* reference to make sure you get the details
-right in your app.
-
-Begin advertising
-^^^^^^^^^^^^^^^^^
-
-An app starts advertising with the following function:
-
-.. code:: c
-
- int
- ble_gap_adv_start(uint8_t discoverable_mode, uint8_t connectable_mode,
- uint8_t *peer_addr, uint8_t peer_addr_type,
- struct hci_adv_params *adv_params,
- ble_gap_conn_fn *cb, void *cb_arg)
-
-This function allows a lot of flexibility, and it might seem daunting at
-first glance. *bleprph* specifies a simple set of arguments that is
-appropriate for most peripherals. When getting started on a typical
-peripheral, we recommend you use the same arguments as *bleprph*, with
-the exception of the last two (*cb* and *cb\_arg*). These last two
-arguments will be specific to your app, so let's talk about them.
-
-*cb* is a callback function. It gets executed when a central connects to
-your peripheral after receiving an advertisement. The *cb\_arg* argument
-gets passed to the *cb* callback. If your callback doesn't need the
-*cb\_arg* parameter, you can do what *bleprph* does and pass *NULL*.
-Once a connection is established, the *cb* callback becomes permanently
-associated with the connection. All subsequent events related to the
-connection are communicated to your app via calls to this callback
-function. Connection callbacks are an important part of building a BLE
-app, and we examine *bleprph*'s connection callback in detail in the
-next section of this tutorial.
-
-**One final note:** Your peripheral automatically stops advertising when
-a central connects to it. You can immediately resume advertising if you
-want to allow another central to connect, but you will need to do so
-explicitly by calling ``ble_gap_adv_start()`` again. Also, be aware
-NimBLE's default configuration only allows a single connection at a
-time. NimBLE supports multiple concurrent connections, but you must
-configure it to do so first.
diff --git a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-app.rst b/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-app.rst
deleted file mode 100644
index ec888e0a5..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-app.rst
+++ /dev/null
@@ -1,100 +0,0 @@
-BLE Peripheral App
-==================
-
-Overview
-~~~~~~~~
-
-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.
-
-Prerequisites
-~~~~~~~~~~~~~
-
-- 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.
-
-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
-
-.. code-block:: console
-
- $ 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 build myperiph
- Building target targets/myperiph
- ...
- Linking ~/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: ~/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'.
-
-.. figure:: /os/tutorials/pics/LightBlue-1.jpg
- :alt: LightBlue iOS App with nimble-bleprph device
-
-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.
-
-.. figure:: /os/tutorials/pics/LightBlue-2.jpg
- :alt: LightBlue iOS App connected to the nimble-bleprph device
-
-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.
-
-.. figure:: /os/tutorials/pics/LightBlue-3.jpg
- :alt: LightBlue iOS App connected to the nimble-bleprph device
-
-Just click on the Read Write Characteristic and you will see the
-existing value.
-
-.. figure:: /os/tutorials/pics/LightBlue-4.jpg
- :alt: LightBlue iOS App with nimble-bleprph device Characteristic
-
-Type in a new value.
-
-.. figure:: /os/tutorials/pics/LightBlue-5.jpg
- :alt: LightBlue iOS App Value Change
-
- LightBlue
-
-And you will see the new value reflected.
-
-.. figure:: /os/tutorials/pics/LightBlue-6.jpg
- :alt: LightBlue iOS App with nimble-bleprph new value
-
-If you still have your console connected, you will be able to see the
-connection requests, and pairing, happen on the device as well.
-
-.. code:: console
-
- 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]
-
-Congratulations! You've just built and connected your first BLE
-Peripheral device!
diff --git a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-chr-access.rst b/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-chr-access.rst
deleted file mode 100644
index 0d6d4ec4f..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-chr-access.rst
+++ /dev/null
@@ -1,282 +0,0 @@
-Characteristic Access
-=====================
-
-Review
-^^^^^^
-
-A characteristic's access callback implements its behavior. Recall that
-services and characteristics are registered with NimBLE via attribute
-tables. Each characteristic definition in an attribute table contains an
-*access\_cb* field. The *access\_cb* field is an application callback
-that gets executed whenever a peer device attempts to read or write the
-characteristic.
-
-Earlier in this tutorial, we looked at how *bleprph* implements the GAP
-service. Let's take another look at how *bleprph* specifies the first
-few characteristics in this service.
-
-.. code:: c
-
- static const struct ble_gatt_svc_def gatt_svr_svcs[] = {
- {
- /*** Service: GAP. */
- .type = BLE_GATT_SVC_TYPE_PRIMARY,
- .uuid128 = BLE_UUID16(BLE_GAP_SVC_UUID16),
- .characteristics = (struct ble_gatt_chr_def[]) { {
- /*** Characteristic: Device Name. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_DEVICE_NAME),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
- }, {
- /*** Characteristic: Appearance. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_APPEARANCE),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
- }, {
- // [...]
-
-As you can see, *bleprph* uses the same *access\_cb* function for all
-the GAP service characteristics, but the developer could have
-implemented separate functions for each characteristic if they
-preferred. Here is the *access\_cb* function that the GAP service
-characteristics use:
-
-.. code:: c
-
- static int
- gatt_svr_chr_access_gap(uint16_t conn_handle, uint16_t attr_handle, uint8_t op,
- union ble_gatt_access_ctxt *ctxt, void *arg)
- {
- uint16_t uuid16;
-
- uuid16 = ble_uuid_128_to_16(ctxt->chr_access.chr->uuid128);
- assert(uuid16 != 0);
-
- switch (uuid16) {
- case BLE_GAP_CHR_UUID16_DEVICE_NAME:
- assert(op == BLE_GATT_ACCESS_OP_READ_CHR);
- ctxt->chr_access.data = (void *)bleprph_device_name;
- ctxt->chr_access.len = strlen(bleprph_device_name);
- break;
-
- case BLE_GAP_CHR_UUID16_APPEARANCE:
- assert(op == BLE_GATT_ACCESS_OP_READ_CHR);
- ctxt->chr_access.data = (void *)&bleprph_appearance;
- ctxt->chr_access.len = sizeof bleprph_appearance;
- break;
-
- case BLE_GAP_CHR_UUID16_PERIPH_PRIV_FLAG:
- assert(op == BLE_GATT_ACCESS_OP_READ_CHR);
- ctxt->chr_access.data = (void *)&bleprph_privacy_flag;
- ctxt->chr_access.len = sizeof bleprph_privacy_flag;
- break;
-
- case BLE_GAP_CHR_UUID16_RECONNECT_ADDR:
- assert(op == BLE_GATT_ACCESS_OP_WRITE_CHR);
- if (ctxt->chr_access.len != sizeof bleprph_reconnect_addr) {
- return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN;
- }
- memcpy(bleprph_reconnect_addr, ctxt->chr_access.data,
- sizeof bleprph_reconnect_addr);
- break;
-
- case BLE_GAP_CHR_UUID16_PERIPH_PREF_CONN_PARAMS:
- assert(op == BLE_GATT_ACCESS_OP_READ_CHR);
- ctxt->chr_access.data = (void *)&bleprph_pref_conn_params;
- ctxt->chr_access.len = sizeof bleprph_pref_conn_params;
- break;
-
- default:
- assert(0);
- break;
- }
-
- return 0;
- }
-
-After you've taken a moment to examine the structure of this function,
-let's explore some details.
-
-Function signature
-^^^^^^^^^^^^^^^^^^
-
-.. code:: c
-
- static int
- gatt_svr_chr_access_gap(uint16_t conn_handle, uint16_t attr_handle, uint8_t op,
- union ble_gatt_access_ctxt *ctxt, void *arg)
-
-A characteristic access function always takes this same set of
-parameters and always returns an int. The parameters to this function
-type are documented below.
-
-+----------------+--------------+------------+
-| **Parameter** | **Purpose** | **Notes** |
-+================+==============+============+
-| conn\_handle | Indicates | Use this |
-| | which | value to |
-| | connection | determine |
-| | the | which peer |
-| | characterist | is |
-| | ic | accessing |
-| | access was | the |
-| | sent over. | characteri |
-| | | stic. |
-+----------------+--------------+------------+
-| attr\_handle | The | Can be |
-| | low-level | used to |
-| | ATT handle | determine |
-| | of the | which |
-| | characterist | characteri |
-| | ic | stic |
-| | value | is being |
-| | attribute. | accessed |
-| | | if you |
-| | | don't want |
-| | | to perform |
-| | | a UUID |
-| | | lookup. |
-+----------------+--------------+------------+
-| op | Indicates | Valid |
-| | whether this | values |
-| | is a read or | are:\ *BLE |
-| | write | \_GATT\_AC |
-| | operation | CESS\_OP\_ |
-| | | READ\_CHR* |
-| | | \ \ *BLE\_ |
-| | | GATT\_ACCE |
-| | | SS\_OP\_WR |
-| | | ITE\_CHR* |
-+----------------+--------------+------------+
-| ctxt | Contains the | For |
-| | characterist | characteri |
-| | ic | stic |
-| | value | accesses, |
-| | pointer that | use the |
-| | the | *ctxt->chr |
-| | application | \_access* |
-| | needs to | member; |
-| | access. | for |
-| | | descriptor |
-| | | accesses, |
-| | | use the |
-| | | *ctxt->dsc |
-| | | \_access* |
-| | | member. |
-+----------------+--------------+------------+
-
-The return value of the access function tells the NimBLE stack how to
-respond to the peer performing the operation. A value of 0 indicates
-success. For failures, the function returns the specific ATT error code
-that the NimBLE stack should respond with. The ATT error codes are
-defined in
-`net/nimble/host/include/host/ble\_att.h <https://github.com/apache/incubator-mynewt-core/blob/master/net/nimble/host/include/host/ble_att.h>`__.
-
-Determine characteristic being accessed
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: c
-
- {
- uint16_t uuid16;
-
- uuid16 = ble_uuid_128_to_16(ctxt->chr_access.chr->uuid128);
- assert(uuid16 != 0);
-
- switch (uuid16) {
- // [...]
-
-This function uses the UUID to determine which characteristic is being
-accessed. There are two alternative methods *bleprph* could have used to
-accomplish this task:
-
-- Map characteristics to ATT handles during service registration; use
- the *attr\_handle* parameter as a key into this table during
- characteristic access.
-- Implement a dedicated function for each characteristic; each function
- inherently knows which characteristic it corresponds to.
-
-All the GAP service characteristics have 16-bit UUIDs, so this function
-uses the *ble\_uuid\_128\_to\_16()* function to convert the 128-bit UUID
-to its corresponding 16-bit UUID. This conversion function returns the
-corresponding 16-bit UUID on success, or 0 on failure. Success is
-asserted here to ensure the NimBLE stack is doing its job properly; the
-stack should only call this function for accesses to characteristics
-that it is registered with, and all GAP service characteristics have
-valid 16-bit UUIDs.
-
-Read access
-^^^^^^^^^^^
-
-.. code:: c
-
- case BLE_GAP_CHR_UUID16_DEVICE_NAME:
- assert(op == BLE_GATT_ACCESS_OP_READ_CHR);
- ctxt->chr_access.data = (void *)bleprph_device_name;
- ctxt->chr_access.len = strlen(bleprph_device_name);
- break;
-
-This code excerpt handles read accesses to the device name
-characteristic. The *assert()* here is another case of making sure the
-NimBLE stack is doing its job; this characteristic was registered as
-read-only, so the stack should have prevented write accesses.
-
-To fulfill a characteristic read request, the application needs to
-assign the *ctxt->chr\_access.data* field to point to the attribute data
-to respond with, and fill the *ctxt->chr\_access.len* field with the
-length of the attribute data. *bleprph* stores the device name in
-read-only memory as follows:
-
-.. code:: c
-
- const char *bleprph_device_name = "nimble-bleprph";
-
-The cast to pointer-to-void is a necessary annoyance to remove the
-*const* qualifier from the device name variable. You will need to "cast
-away const" whenever you respond to read requests with read-only data.
-
-It is not shown in the above snippet, but this function ultimately
-returns 0. By returning 0, *bleprph* indicates that the characteristic
-data in *ctxt->chr\_access* is valid and that NimBLE should include it
-in its response to the peer.
-
-**A word of warning:** The attribute data that *ctxt->chr\_access.data*
-points to must remain valid after the access function returns, as the
-NimBLE stack needs to use it to form a GATT read response. In other
-words, you must not allocate the characteristic value data on the stack
-of the access function. Two characteristic accesses never occur at the
-same time, so it is OK to use the same memory for repeated accesses.
-
-Write access
-^^^^^^^^^^^^
-
-.. code:: c
-
- case BLE_GAP_CHR_UUID16_RECONNECT_ADDR:
- assert(op == BLE_GATT_ACCESS_OP_WRITE_CHR);
- if (ctxt->chr_access.len != sizeof bleprph_reconnect_addr) {
- return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN;
- }
- memcpy(bleprph_reconnect_addr, ctxt->chr_access.data,
- sizeof bleprph_reconnect_addr);
- break;
-
-This code excerpt handles writes to the reconnect address
-characteristic. This characteristic was registered as write-only, so the
-*assert()* here is just a safety precaution to ensure the NimBLE stack
-is doing its job.
-
-For writes, the roles of the *ctxt->chr\_access.data* and
-*ctxt->chr\_access.len* fields are the reverse of the read case. The
-NimBLE stack uses these fields to indicate the data written by the peer.
-
-Many characteristics have strict length requirements for write
-operations. This characteristic has such a restriction; if the written
-data is not a 48-bit BR address, the application tells NimBLE to respond
-with an invalid attribute value length error.
-
-For writes, the *ctxt->chr\_access.data* pointer is only valid for the
-duration of the access function. If the application needs to save the
-written data, it should store it elsewhere before the function returns.
-In this case, *bleprph* stores the specified address in a global
-variable called *bleprph\_reconnect\_addr*.
diff --git a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-gap-event.rst b/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-gap-event.rst
deleted file mode 100644
index 67589f020..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-gap-event.rst
+++ /dev/null
@@ -1,160 +0,0 @@
-GAP Event callbacks
-===================
-
-Overview
-^^^^^^^^
-
-Every BLE connection has a *GAP event callback* associated with it. A
-GAP event callback is a bit of application code which NimBLE uses to
-inform you of connection-related events. For example, if a connection is
-terminated, NimBLE lets you know about it with a call to that
-connection's callback.
-
-In the `advertising section <bleprph-adv/>`__ of this tutorial, we saw
-how the application specifies a GAP event callback when it begins
-advertising. NimBLE uses this callback to notify the application that a
-central has connected to your peripheral after receiving an
-advertisement. Let's revisit how *bleprph* specifies its connection
-callback when advertising:
-
-.. code:: c
-
- /* Begin advertising. */
- memset(&adv_params, 0, sizeof adv_params);
- adv_params.conn_mode = BLE_GAP_CONN_MODE_UND;
- adv_params.disc_mode = BLE_GAP_DISC_MODE_GEN;
- rc = ble_gap_adv_start(BLE_ADDR_TYPE_PUBLIC, 0, NULL, BLE_HS_FOREVER,
- &adv_params, bleprph_gap_event, NULL);
- if (rc != 0) {
- BLEPRPH_LOG(ERROR, "error enabling advertisement; rc=%d\n", rc);
- return;
- }
-
-bleprph\_gap\_event()
-^^^^^^^^^^^^^^^^^^^^^
-
-The ``bleprph_gap_event()`` function is *bleprph*'s GAP event callback;
-NimBLE calls this function when the advertising operation leads to
-connection establishment. Upon connection establishment, this callback
-becomes permanently associated with the connection; all subsequent
-events related to this connection are communicated through this
-callback.
-
-Now let's look at the function that *bleprph* uses for all its
-connection callbacks: ``bleprph_gap_event()``.
-
-.. code:: c
-
- /**
- * The nimble host executes this callback when a GAP event occurs. The
- * application associates a GAP event callback with each connection that forms.
- * bleprph uses the same callback for all connections.
- *
- * @param event The type of event being signalled.
- * @param ctxt Various information pertaining to the event.
- * @param arg Application-specified argument; unuesd by
- * bleprph.
- *
- * @return 0 if the application successfully handled the
- * event; nonzero on failure. The semantics
- * of the return code is specific to the
- * particular GAP event being signalled.
- */
- static int
- bleprph_gap_event(struct ble_gap_event *event, void *arg)
- {
- struct ble_gap_conn_desc desc;
- int rc;
-
- switch (event->type) {
- case BLE_GAP_EVENT_CONNECT:
- /* A new connection was established or a connection attempt failed. */
- BLEPRPH_LOG(INFO, "connection %s; status=%d ",
- event->connect.status == 0 ? "established" : "failed",
- event->connect.status);
- if (event->connect.status == 0) {
- rc = ble_gap_conn_find(event->connect.conn_handle, &desc);
- assert(rc == 0);
- bleprph_print_conn_desc(&desc);
- }
- BLEPRPH_LOG(INFO, "\n");
-
- if (event->connect.status != 0) {
- /* Connection failed; resume advertising. */
- bleprph_advertise();
- }
- return 0;
-
- case BLE_GAP_EVENT_DISCONNECT:
- BLEPRPH_LOG(INFO, "disconnect; reason=%d ", event->disconnect.reason);
- bleprph_print_conn_desc(&event->disconnect.conn);
- BLEPRPH_LOG(INFO, "\n");
-
- /* Connection terminated; resume advertising. */
- bleprph_advertise();
- return 0;
-
- case BLE_GAP_EVENT_CONN_UPDATE:
- /* The central has updated the connection parameters. */
- BLEPRPH_LOG(INFO, "connection updated; status=%d ",
- event->conn_update.status);
- rc = ble_gap_conn_find(event->connect.conn_handle, &desc);
- assert(rc == 0);
- bleprph_print_conn_desc(&desc);
- BLEPRPH_LOG(INFO, "\n");
- return 0;
-
- case BLE_GAP_EVENT_ENC_CHANGE:
- /* Encryption has been enabled or disabled for this connection. */
- BLEPRPH_LOG(INFO, "encryption change event; status=%d ",
- event->enc_change.status);
- rc = ble_gap_conn_find(event->connect.conn_handle, &desc);
- assert(rc == 0);
- bleprph_print_conn_desc(&desc);
- BLEPRPH_LOG(INFO, "\n");
- return 0;
-
- case BLE_GAP_EVENT_SUBSCRIBE:
- BLEPRPH_LOG(INFO, "subscribe event; conn_handle=%d attr_handle=%d "
- "reason=%d prevn=%d curn=%d previ=%d curi=%d\n",
- event->subscribe.conn_handle,
- event->subscribe.attr_handle,
- event->subscribe.reason,
- event->subscribe.prev_notify,
- event->subscribe.cur_notify,
- event->subscribe.prev_indicate,
- event->subscribe.cur_indicate);
- return 0;
- }
-
- return 0;
- }
-
-Connection callbacks are used to communicate a variety of events related
-to a connection. An application determines the type of event that
-occurred by inspecting the value of the *event->type* parameter. The
-full list of event codes can be found on the `GAP
-events <../../../network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/>`__
-page.
-
-Guarantees
-^^^^^^^^^^
-
-It is important to know what your application code is allowed to do from
-within a connection callback.
-
-**No restrictions on NimBLE operations**
-
-Your app is free to make calls into the NimBLE stack from within a
-connection callback. *bleprph* takes advantage of this freedom when it
-resumes advertising upon connection termination. All other NimBLE
-operations are also allowed (service discovery, pairing initiation,
-etc).
-
-**All context data is transient**
-
-Pointers in the context object point to data living on the stack. Your
-callback is free to read (or write, if appropriate) through these
-pointers, but you should not store these pointers for later use. If your
-application needs to retain some data from a context object, it needs to
-make a copy.
diff --git a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-svc-reg.rst b/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-svc-reg.rst
deleted file mode 100644
index d203dd650..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph-sections/bleprph-svc-reg.rst
+++ /dev/null
@@ -1,284 +0,0 @@
-Service Registration
-====================
-
-Attribute Set
-^^^^^^^^^^^^^
-
-The NimBLE host uses a table-based design for GATT server configuration.
-The set of supported attributes are expressed as a series of tables that
-resides in your C code. When possible, we recommend using a single
-monolithic table, as it results in code that is simpler and less error
-prone. Multiple tables can be used if it is impractical for the entire
-attribute set to live in one place in your code.
-
-*bleprph* uses a single attribute table located in the *gatt\_svr.c*
-file, so let's take a look at that now. The attribute table is called
-``gatt_svr_svcs``; here are the first several lines from this table:
-
-.. code:: c
-
- static const struct ble_gatt_svc_def gatt_svr_svcs[] = {
- {
- /*** Service: GAP. */
- .type = BLE_GATT_SVC_TYPE_PRIMARY,
- .uuid128 = BLE_UUID16(BLE_GAP_SVC_UUID16),
- .characteristics = (struct ble_gatt_chr_def[]) { {
- /*** Characteristic: Device Name. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_DEVICE_NAME),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
- }, {
- /*** Characteristic: Appearance. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_APPEARANCE),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
- }, {
- // [...]
-
-As you can see, the table is an array of service definitions (
-``struct ble_gatt_svc_def``). This code excerpt contains a small part of
-the *GAP service*. The GAP service exposes generic information about a
-device, such as its name and appearance. Support for the GAP service is
-mandatory for all BLE peripherals. Let's now consider the contents of
-this table in more detail.
-
-A service definition consists of the following fields:
-
-+----------+------------+----------+
-| *Field* | *Meaning* | *Notes* |
-+==========+============+==========+
-| type | Specifies | Secondar |
-| | whether | y |
-| | this is a | services |
-| | primary or | are not |
-| | secondary | very |
-| | service. | common. |
-| | | When in |
-| | | doubt, |
-| | | specify |
-| | | *BLE\_GA |
-| | | TT\_SVC\ |
-| | | _TYPE\_P |
-| | | RIMARY* |
-| | | for new |
-| | | services |
-| | | . |
-+----------+------------+----------+
-| uuid128 | The | If the |
-| | 128-bit | service |
-| | UUID of | has a |
-| | this | 16-bit |
-| | service. | UUID, |
-| | | you can |
-| | | convert |
-| | | it to |
-| | | its |
-| | | correspo |
-| | | nding |
-| | | 128-bit |
-| | | UUID |
-| | | with the |
-| | | ``BLE_UU |
-| | | ID16()`` |
-| | | macro. |
-+----------+------------+----------+
-| characte | The array | |
-| ristics | of | |
-| | characteri | |
-| | stics | |
-| | that | |
-| | belong to | |
-| | this | |
-| | service. | |
-+----------+------------+----------+
-
-A service is little more than a container of characteristics; the
-characteristics themselves are where the real action happens. A
-characteristic definition consists of the following fields:
-
-+----------+------------+----------+
-| *Field* | *Meaning* | *Notes* |
-+==========+============+==========+
-| uuid128 | The | If the |
-| | 128-bit | characte |
-| | UUID of | ristic |
-| | this | has a |
-| | characteri | 16-bit |
-| | stic. | UUID, |
-| | | you can |
-| | | convert |
-| | | it to |
-| | | its |
-| | | correspo |
-| | | nding |
-| | | 128-bit |
-| | | UUID |
-| | | with the |
-| | | ``BLE_UU |
-| | | ID16()`` |
-| | | macro. |
-+----------+------------+----------+
-| access\_ | A callback | *For |
-| cb | function | reads:* |
-| | that gets | this |
-| | executed | function |
-| | whenever a | generate |
-| | peer | s |
-| | device | the |
-| | accesses | value |
-| | this | that |
-| | characteri | gets |
-| | stic. | sent |
-| | | back to |
-| | | the |
-| | | peer.\ * |
-| | | For |
-| | | writes:* |
-| | | this |
-| | | function |
-| | | receives |
-| | | the |
-| | | written |
-| | | value as |
-| | | an |
-| | | argument |
-| | | . |
-+----------+------------+----------+
-| flags | Indicates | The full |
-| | which | list of |
-| | operations | flags |
-| | are | can be |
-| | permitted | found |
-| | for this | under |
-| | characteri | ``ble_ga |
-| | stic. | tt_chr_f |
-| | The NimBLE | lags`` |
-| | stack | in |
-| | responds | `net/nim |
-| | negatively | ble/host |
-| | when a | /include |
-| | peer | /host/bl |
-| | attempts | e\_gatt. |
-| | an | h <https |
-| | unsupporte | ://githu |
-| | d | b.com/ap |
-| | operation. | ache/myn |
-| | | ewt-core |
-| | | /blob/ma |
-| | | ster/net |
-| | | /nimble/ |
-| | | host/inc |
-| | | lude/hos |
-| | | t/ble_ga |
-| | | tt.h>`__ |
-| | | . |
-+----------+------------+----------+
-
-The access callback is what implements the characteristic's behavior.
-Access callbacks are described in detail in the next section: `BLE
-Peripheral - Characteristic Access <bleprph-chr-access/>`__.
-
-The service definition array and each characteristic definition array is
-terminated with an empty entry, represented with a 0. The below code
-listing shows the last service in the array, including terminating zeros
-for the characteristic array and service array.
-
-\`\`\`c hl\_lines="26 31" { /\*\*\* Alert Notification Service. */ .type
-= BLE\_GATT\_SVC\_TYPE\_PRIMARY, .uuid128 =
-BLE\_UUID16(GATT\_SVR\_SVC\_ALERT\_UUID), .characteristics = (struct
-ble\_gatt\_chr\_def[]) { { .uuid128 =
-BLE\_UUID16(GATT\_SVR\_CHR\_SUP\_NEW\_ALERT\_CAT\_UUID), .access\_cb =
-gatt\_svr\_chr\_access\_alert, .flags = BLE\_GATT\_CHR\_F\_READ, }, {
-.uuid128 = BLE\_UUID16(GATT\_SVR\_CHR\_NEW\_ALERT), .access\_cb =
-gatt\_svr\_chr\_access\_alert, .flags = BLE\_GATT\_CHR\_F\_NOTIFY, }, {
-.uuid128 = BLE\_UUID16(GATT\_SVR\_CHR\_SUP\_UNR\_ALERT\_CAT\_UUID),
-.access\_cb = gatt\_svr\_chr\_access\_alert, .flags =
-BLE\_GATT\_CHR\_F\_READ, }, { .uuid128 =
-BLE\_UUID16(GATT\_SVR\_CHR\_UNR\_ALERT\_STAT\_UUID), .access\_cb =
-gatt\_svr\_chr\_access\_alert, .flags = BLE\_GATT\_CHR\_F\_NOTIFY, }, {
-.uuid128 = BLE\_UUID16(GATT\_SVR\_CHR\_ALERT\_NOT\_CTRL\_PT),
-.access\_cb = gatt\_svr\_chr\_access\_alert, .flags =
-BLE\_GATT\_CHR\_F\_WRITE, }, { 0, /* No more characteristics in this
-service. \*/ } }, },
-
-::
-
- {
- 0, /* No more services. */
- },
-
-\`\`\`
-
-Registration function
-^^^^^^^^^^^^^^^^^^^^^
-
-After you have created your service table, your app needs to register it
-with the NimBLE stack. This is done by calling the following function:
-
-.. code:: c
-
- int
- ble_gatts_register_svcs(const struct ble_gatt_svc_def *svcs,
- ble_gatt_register_fn *cb, void *cb_arg)
-
-The function parameters are documented below.
-
-+--------------+------------+----------+
-| *Parameter* | *Meaning* | *Notes* |
-+==============+============+==========+
-| svcs | The table | |
-| | of | |
-| | services | |
-| | to | |
-| | register. | |
-+--------------+------------+----------+
-| cb | A callback | Optional |
-| | that gets | ; |
-| | executed | pass |
-| | each time | NULL if |
-| | a service, | you |
-| | characteri | don't |
-| | stic, | want to |
-| | or | be |
-| | descriptor | notified |
-| | is | . |
-| | registered | |
-| | . | |
-+--------------+------------+----------+
-| cb\_arg | An | Optional |
-| | argument | ; |
-| | that gets | pass |
-| | passed to | NULL if |
-| | the | there is |
-| | callback | no |
-| | function | callback |
-| | on each | or if |
-| | invocation | you |
-| | . | don't |
-| | | need a |
-| | | special |
-| | | argument |
-| | | . |
-+--------------+------------+----------+
-
-The ``ble_gatts_register_svcs()`` function returns 0 on success, or a
-*BLE\_HS\_E[...]* error code on failure.
-
-More detailed information about the registration callback function can
-be found in the `BLE User Guide <../../../network/ble/ble_intro/>`__
-(TBD).
-
-The *bleprph* app registers its services as follows:
-
-.. code:: c
-
- rc = ble_gatts_register_svcs(gatt_svr_svcs, gatt_svr_register_cb, NULL);
- assert(rc == 0);
-
-Descriptors and Included Services
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Your peripheral can also expose descriptors and included services. These
-are less common, so they are not covered in this tutorial. For more
-information, see the `BLE User
-Guide <../../../network/ble/ble_intro/>`__.
diff --git a/docs/os/tutorials/ble/bleprph/bleprph.rst b/docs/os/tutorials/ble/bleprph/bleprph.rst
deleted file mode 100644
index fee224ba5..000000000
--- a/docs/os/tutorials/ble/bleprph/bleprph.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-BLE Peripheral Project
-----------------------
-
-.. toctree::
- :hidden:
-
- bleprph-sections/bleprph-svc-reg.rst
- bleprph-sections/bleprph-chr-access.rst
- bleprph-sections/bleprph-adv.rst
- bleprph-sections/bleprph-gap-event.rst
- bleprph-sections/bleprph-app.rst
-
-Introduction
-~~~~~~~~~~~~
-
-Overview
-^^^^^^^^
-
-*bleprph* is an example app included in the apache-mynewt-core
-repository. This app implements a simple BLE peripheral with the
-following properties:
-
-- Supports three services: GAP, GATT, and alert notification service
- (ANS).
-- Supports a single concurrent connection.
-- Automatically advertises connectability when not connected to a
- central device.
-
-This tutorial aims to provide a guided tour through the *bleprph* app
-source code. This document builds on some concepts described elsewhere
-in the Apache Mynewt documentation. Before proceeding with this
-tutorial, you might want to familiarize yourself with the following
-pages:
-
-- `Create Your First Mynewt
- Project <../../get_started/project_create/>`__
-- `BLE Bare Bones Application
- Tutorial <../../../os/tutorials/ble_bare_bones/>`__
-- `NimBLE Stack
- Initialization <../../../network/ble/ini_stack/ble_ini_intro/>`__
-
-Services, Characteristics, Descriptors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A BLE peripheral interfaces with other BLE devices by exposing
-*services*, *characteristics*, and *descriptors*. All three of these
-entities are implemented at a lower layer via *attributes*. If you are
-not familiar with these concepts, you will probably want to check out
-this
-`overview <https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx>`__
-from the Bluetooth Developer's site before proceeding.
-
-Now let's dig in to some C code.
diff --git a/docs/os/tutorials/ble/eddystone.rst b/docs/os/tutorials/ble/eddystone.rst
deleted file mode 100644
index 1c31a8875..000000000
--- a/docs/os/tutorials/ble/eddystone.rst
+++ /dev/null
@@ -1,400 +0,0 @@
-BLE Eddystone
--------------
-
-Eddystone Beacon Protocol
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A beaconing device announces its presence to the world by broadcasting
-advertisements. The Eddystone protocol is built on top of the standard
-BLE advertisement specification. Eddystone supports multiple data packet
-types:
-
-- Eddystone-UID: a unique, static ID with a 10-byte Namespace component
- and a 6-byte Instance component.
-- Eddystone-URL: a compressed URL that, once parsed and decompressed,
- is directly usable by the client.
-- Eddystone-TLM: "telemetry" packets that are broadcast alongside the
- Eddystone-UID or Eddystone-URL packets and contains beacon?s ?health
- status? (e.g., battery life).
-- Eddystone-EID to broadcast an ephemeral identifier that changes every
- few minutes and allow only parties that can resolve the identifier to
- use the beacon.
-
-`This page <https://developers.google.com/beacons/eddystone>`__
-describes the Eddystone open beacon format developed by Google.
-
-Apache Mynewt currently supports Eddystone-UID and Eddystone-URL formats
-only. This tutorial will explain how to get an Eddystone-URL beacon
-going on a peripheral device.
-
-Create an Empty BLE Application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This tutorial picks up where the `BLE bare bones application
-tutorial <../../os/tutorials/ble_bare_bones.html>`__ concludes. The first
-step in creating a beaconing device is to create an empty BLE app, as
-explained in that tutorial. Before proceeding, you should have:
-
-- An app called "ble\_app".
-- A target called "ble\_tgt".
-- Successfully executed the app on your target device.
-
-Add beaconing
-~~~~~~~~~~~~~
-
-Here is a brief specification of how we want our beaconing app to
-behave:
-
-1. Wait until the host and controller are in sync.
-2. Configure the NimBLE stack with an address to put in its
- advertisements.
-3. Advertise an eddystone URL beacon indefinitely.
-
-Let's take these one at a time.
-
-1. Wait for host-controller sync
-^^^^^^^^^^^^^^^^^^^
-
-
-The first step, waiting for host-controller-sync, is mandatory in all
-BLE applications. The NimBLE stack is inoperable while the two
-components are out of sync. In a combined host-controller app, the sync
-happens immediately at startup. When the host and controller are
-separate, sync typically occurs in less than a second.
-
-We achieve this by configuring the NimBLE host with a callback function
-that gets called when sync takes place:
-
-\`\`\`c hl\_lines="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 24" static
-void ble\_app\_set\_addr() { }
-
-static void ble\_app\_advertise(); { }
-
-static void ble\_app\_on\_sync(void) { /\* Generate a non-resolvable
-private address. \*/ ble\_app\_set\_addr();
-
-::
-
- /* Advertise indefinitely. */
- ble_app_advertise();
-
-}
-
-int main(int argc, char \*\*argv) { sysinit();
-
-::
-
- ble_hs_cfg.sync_cb = ble_app_on_sync;
-
- /* As the last thing, process events from default event queue. */
- while (1) {
- os_eventq_run(os_eventq_dflt_get());
- }
-
-} \`\`\`
-
-``ble_hs_cfg.sync_cb`` points to the function that should be called when
-sync occurs. Our callback function, ``ble_app_on_sync()``, kicks off the
-control flow that we specified above. Now we need to fill in the two
-stub functions.
-
-2. Configure the NimBLE stack with an address
-^^^^^^^^^^^^^^^^^^^
-
-
-A BLE device needs an address to do just about anything. Some devices
-have a public Bluetooth address burned into them, but this is not always
-the case. Furthermore, the NimBLE controller might not know how to read
-an address out of your particular hardware. For a beaconing device, we
-generally don't care what address gets used since nothing will be
-connecting to us.
-
-A reliable solution is to generate a *non-resolvable private address*
-(nRPA) each time the application runs. Such an address contains no
-identifying information, and they are expected to change frequently.
-
-\`\`\`c hl\_lines="4 5 6 7 8 9 10 11" static void
-ble\_app\_set\_addr(void) { ble\_addr\_t addr; int rc;
-
-::
-
- rc = ble_hs_id_gen_rnd(1, &addr);
- assert(rc == 0);
-
- rc = ble_hs_id_set_rnd(addr.val);
- assert(rc == 0);
-
-}
-
-static void ble\_app\_advertise(); { }
-
-static void ble\_app\_on\_sync(void) { /\* Generate a non-resolvable
-private address. \*/ ble\_app\_set\_addr();
-
-::
-
- /* Advertise indefinitely. */
- ble_app_advertise();
-
-} \`\`\`
-
-Our new function, ``ble_app_set_addr()``, makes two calls into the
-stack:
-
-- ```ble_hs_id_gen_rnd`` <../../network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd.html>`__:
- Generate an nRPA.
-- ```ble_hs_id_set_rnd`` <../../network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd.html>`__:
- Configure NimBLE to use the newly-generated address.
-
-You can click either of the function names for more detailed
-documentation.
-
-3. Advertise indefinitely
-^^^^^^^^^^^^^^^^^^^
-
-
-The first step in advertising is to configure the host with advertising
-data. This operation tells the host what data to use for the contents of
-its advertisements. The NimBLE host provides special helper functions
-for configuring eddystone advertisement data:
-
-- ```ble_eddystone_set_adv_data_uid`` <../../network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid.html>`__
-- ```ble_eddystone_set_adv_data_url`` <../../network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url.html>`__
-
-Our application will advertise eddystone URL beacons, so we are
-interested in the second function. We reproduce the function prototype
-here:
-
-.. code:: c
-
- int
- ble_eddystone_set_adv_data_url(
- struct ble_hs_adv_fields *adv_fields,
- uint8_t url_scheme,
- char *url_body,
- uint8_t url_body_len,
- uint8_t url_suffix
- )
-
-We'll advertise the Mynewt URL: *https://mynewt.apache.org*. Eddystone
-beacons use a form of URL compression to accommodate the limited space
-available in Bluetooth advertisements. The ``url_scheme`` and
-``url_suffix`` fields implement this compression; they are single byte
-fields which correspond to strings commonly found in URLs. The following
-arguments translate to the https://mynewt.apache.org URL:
-
-+---------------+--------------------------------------+
-| Parameter | Value |
-+===============+======================================+
-| url\_scheme | ``BLE_EDDYSTONE_URL_SCHEME_HTTPS`` |
-+---------------+--------------------------------------+
-| url\_body | "mynewt.apache" |
-+---------------+--------------------------------------+
-| url\_suffix | ``BLE_EDDYSTONE_URL_SUFFIX_ORG`` |
-+---------------+--------------------------------------+
-
-.. code:: c
-
- static void
- ble_app_advertise(void)
- {
- struct ble_hs_adv_fields fields;
- int rc;
-
- /* Configure an eddystone URL beacon to be advertised;
- * URL: https://apache.mynewt.org
- */
- fields = (struct ble_hs_adv_fields){ 0 };
- rc = ble_eddystone_set_adv_data_url(&fields,
- BLE_EDDYSTONE_URL_SCHEME_HTTPS,
- "mynewt.apache",
- 13,
- BLE_EDDYSTONE_URL_SUFFIX_ORG);
- assert(rc == 0);
-
- /* TODO: Begin advertising. */
- }
-
-Now that the host knows what to advertise, the next step is to actually
-begin advertising. The function to initiate advertising is:
-```ble_gap_adv_start`` <../../network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.html>`__.
-This function takes several parameters. For simplicity, we reproduce the
-function prototype here:
-
-.. code:: c
-
- int
- ble_gap_adv_start(
- uint8_t own_addr_type,
- const ble_addr_t *direct_addr,
- int32_t duration_ms,
- const struct ble_gap_adv_params *adv_params,
- ble_gap_event_fn *cb,
- void *cb_arg
- )
-
-This function gives an application quite a bit of freedom in how
-advertising is to be done. The default values are mostly fine for our
-simple beaconing application. We will pass the following values to this
-function:
-
-+--------------+----------+----------+
-| Parameter | Value | Notes |
-+==============+==========+==========+
-| own\_addr\_t | BLE\_OWN | Use the |
-| ype | \_ADDR\_ | nRPA we |
-| | RANDOM | generate |
-| | | d |
-| | | earlier. |
-+--------------+----------+----------+
-| direct\_addr | NULL | We are |
-| | | broadcas |
-| | | ting, |
-| | | not |
-| | | targetin |
-| | | g |
-| | | a peer. |
-+--------------+----------+----------+
-| duration\_ms | BLE\_HS\ | Advertis |
-| | _FOREVER | e |
-| | | indefini |
-| | | tely. |
-+--------------+----------+----------+
-| adv\_params | defaults | Can be |
-| | | used to |
-| | | specify |
-| | | low |
-| | | level |
-| | | advertis |
-| | | ing |
-| | | paramete |
-| | | rs. |
-+--------------+----------+----------+
-| cb | NULL | We are |
-| | | non-conn |
-| | | ectable, |
-| | | so no |
-| | | need for |
-| | | an event |
-| | | callback |
-| | | . |
-+--------------+----------+----------+
-| cb\_arg | NULL | No |
-| | | callback |
-| | | implies |
-| | | no |
-| | | callback |
-| | | argument |
-| | | . |
-+--------------+----------+----------+
-
-These arguments are mostly self-explanatory. The exception is
-``adv_params``, which can be used to specify a number of low-level
-parameters. For a beaconing application, the default settings are
-appropriate. We specify default settings by providing a zero-filled
-instance of the ``ble_gap_adv_params`` struct as our argument.
-
-\`\`\`c hl\_lines="4 19 20 21 22 23" static void
-ble\_app\_advertise(void) { struct ble\_gap\_adv\_params adv\_params;
-struct ble\_hs\_adv\_fields fields; int rc;
-
-::
-
- /* Configure an eddystone URL beacon to be advertised;
- * URL: https://apache.mynewt.org
- */
- fields = (struct ble_hs_adv_fields){ 0 };
- rc = ble_eddystone_set_adv_data_url(&fields,
- BLE_EDDYSTONE_URL_SCHEME_HTTPS,
- "mynewt.apache",
- 13,
- BLE_EDDYSTONE_URL_SUFFIX_ORG);
- assert(rc == 0);
-
- /* Begin advertising. */
- adv_params = (struct ble_gap_adv_params){ 0 };
- rc = ble_gap_adv_start(BLE_OWN_ADDR_RANDOM, NULL, BLE_HS_FOREVER,
- &adv_params, NULL, NULL);
- assert(rc == 0);
-
-} \`\`\`
-
-Conclusion
-~~~~~~~~~~
-
-That's it! Now when you run this app on your board, you should be able
-to see it with all your eddystone-aware devices. You can test it out
-with the ``newt run`` command.
-
-Source Listing
-~~~~~~~~~~~~~~
-
-For reference, here is the complete application source:
-
-.. code:: c
-
- #include "sysinit/sysinit.h"
- #include "os/os.h"
- #include "console/console.h"
- #include "host/ble_hs.h"
-
- static void
- ble_app_set_addr(void)
- {
- ble_addr_t addr;
- int rc;
-
- rc = ble_hs_id_gen_rnd(1, &addr);
- assert(rc == 0);
-
- rc = ble_hs_id_set_rnd(addr.val);
- assert(rc == 0);
- }
-
- static void
- ble_app_advertise(void)
- {
- struct ble_gap_adv_params adv_params;
- struct ble_hs_adv_fields fields;
- int rc;
-
- /* Configure an eddystone URL beacon to be advertised;
- * URL: https://apache.mynewt.org
- */
- fields = (struct ble_hs_adv_fields){ 0 };
- rc = ble_eddystone_set_adv_data_url(&fields,
- BLE_EDDYSTONE_URL_SCHEME_HTTPS,
- "mynewt.apache",
- 13,
- BLE_EDDYSTONE_URL_SUFFIX_ORG);
- assert(rc == 0);
-
- /* Begin advertising. */
- adv_params = (struct ble_gap_adv_params){ 0 };
- rc = ble_gap_adv_start(BLE_OWN_ADDR_RANDOM, NULL, BLE_HS_FOREVER,
- &adv_params, NULL, NULL);
- assert(rc == 0);
- }
-
- static void
- ble_app_on_sync(void)
- {
- /* Generate a non-resolvable private address. */
- ble_app_set_addr();
-
- /* Advertise indefinitely. */
- ble_app_advertise();
- }
-
- int
- main(int argc, char **argv)
- {
- sysinit();
-
- ble_hs_cfg.sync_cb = ble_app_on_sync;
-
- /* As the last thing, process events from default event queue. */
- while (1) {
- os_eventq_run(os_eventq_dflt_get());
- }
- }
diff --git a/docs/os/tutorials/ble/ibeacon.rst b/docs/os/tutorials/ble/ibeacon.rst
deleted file mode 100644
index fb53597f5..000000000
--- a/docs/os/tutorials/ble/ibeacon.rst
+++ /dev/null
@@ -1,352 +0,0 @@
-BLE iBeacon
------------
-
-This tutorial guides you through the process of creating an iBeacon
-application using NimBLE and Mynewt. At the conclusion of this tutorial,
-you will have a fully functional iBeacon app.
-
-iBeacon Protocol
-~~~~~~~~~~~~~~~~
-
-A beaconing device announces its presence to the world by broadcasting
-advertisements. The iBeacon protocol is built on top of the standard BLE
-advertisement specification. `This
-page <http://www.warski.org/blog/2014/01/how-ibeacons-work/>`__ provides
-a good summary of the iBeacon sub-fields.
-
-Create an Empty BLE Application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This tutorial picks up where the `BLE bare bones application
-tutorial <../../os/tutorials/ble_bare_bones.html>`__ document concludes.
-The first step in creating a beaconing device is to create an empty BLE
-app, as explained in that tutorial. Before proceeding, you should have:
-
-- An app called "ble\_app".
-- A target called "ble\_tgt".
-- Successfully executed the app on your target device.
-
-Add beaconing
-~~~~~~~~~~~~~
-
-Here is a brief specification of how we want our beaconing app to
-behave:
-
-1. Wait until the host and controller are in sync.
-2. Configure the NimBLE stack with an address to put in its
- advertisements.
-3. Advertise indefinitely.
-
-Let's take these one at a time.
-
-1. Wait for host-controller sync
-^^^^^^^^^^^^^^^^^^^
-
-
-The first step, waiting for host-controller-sync, is mandatory in all
-BLE applications. The NimBLE stack is inoperable while the two
-components are out of sync. In a combined host-controller app, the sync
-happens immediately at startup. When the host and controller are
-separate, sync typically occurs in less than a second.
-
-We achieve this by configuring the NimBLE host with a callback function
-that gets called when sync takes place:
-
-\`\`\`c hl\_lines="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 24" static
-void ble\_app\_set\_addr() { }
-
-static void ble\_app\_advertise(); { }
-
-static void ble\_app\_on\_sync(void) { /\* Generate a non-resolvable
-private address. \*/ ble\_app\_set\_addr();
-
-::
-
- /* Advertise indefinitely. */
- ble_app_advertise();
-
-}
-
-int main(int argc, char \*\*argv) { sysinit();
-
-::
-
- ble_hs_cfg.sync_cb = ble_app_on_sync;
-
- /* As the last thing, process events from default event queue. */
- while (1) {
- os_eventq_run(os_eventq_dflt_get());
- }
-
-} \`\`\`
-
-``ble_hs_cfg.sync_cb`` points to the function that should be called when
-sync occurs. Our callback function, ``ble_app_on_sync()``, kicks off the
-control flow that we specified above. Now we need to fill in the two
-stub functions.
-
-2. Configure the NimBLE stack with an address
-^^^^^^^^^^^^^^^^^^^
-
-
-A BLE device needs an address to do just about anything. Some devices
-have a public Bluetooth address burned into them, but this is not always
-the case. Furthermore, the NimBLE controller might not know how to read
-an address out of your particular hardware. For a beaconing device, we
-generally don't care what address gets used since nothing will be
-connecting to us.
-
-A reliable solution is to generate a *non-resolvable private address*
-(nRPA) each time the application runs. Such an address contains no
-identifying information, and they are expected to change frequently.
-
-\`\`\`c hl\_lines="4 5 6 7 8 9 10 11" static void
-ble\_app\_set\_addr(void) { ble\_addr\_t addr; int rc;
-
-::
-
- rc = ble_hs_id_gen_rnd(1, &addr);
- assert(rc == 0);
-
- rc = ble_hs_id_set_rnd(addr.val);
- assert(rc == 0);
-
-}
-
-static void ble\_app\_advertise(); { }
-
-static void ble\_app\_on\_sync(void) { /\* Generate a non-resolvable
-private address. \*/ ble\_app\_set\_addr();
-
-::
-
- /* Advertise indefinitely. */
- ble_app_advertise();
-
-} \`\`\`
-
-Our new function, ``ble_app_set_addr()``, makes two calls into the
-stack:
-
-- ```ble_hs_id_gen_rnd`` <../../network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd.html>`__:
- Generate an nRPA.
-- ```ble_hs_id_set_rnd`` <../../network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd.html>`__:
- Configure NimBLE to use the newly-generated address.
-
-You can click either of the function names for more detailed
-documentation.
-
-3. Advertise indefinitely
-^^^^^^^^^^^^^^^^^^^
-
-
-The first step in advertising is to configure the host with advertising
-data. This operation tells the host what data to use for the contents of
-its advertisements. The NimBLE host provides a special helper function
-for configuring iBeacon advertisement data:
-```ble_ibeacon_set_adv_data`` <../../network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data.html>`__.
-
-If you follow the API link, you'll see that this function takes three
-parameters: a 128-bit UUID, a major version, and a minor version. This
-corresponds with the iBeacon specification, as these three items are the
-primary components in an iBeacon advertisement.
-
-For now, we'll advertise the following:
-
-- *UUID*: ``11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11``
-- *Major*: 2
-- *Minor*: 10
-
-.. code:: c
-
- static void
- ble_app_advertise(void)
- {
- uint8_t uuid128[16];
- int rc;
-
- /* Fill the UUID buffer with a string of 0x11 bytes. */
- memset(uuid128, 0x11, sizeof uuid128);
-
- /* Major version=2; minor version=10. */
- rc = ble_ibeacon_set_adv_data(uuid128, 2, 10);
- assert(rc == 0);
-
- /* TODO: Begin advertising. */
- }
-
-Now that the host knows what to advertise, the next step is to actually
-begin advertising. The function to initiate advertising is:
-```ble_gap_adv_start`` <../../network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.html>`__.
-This function takes several parameters. For simplicity, we reproduce the
-function prototype here:
-
-.. code:: c
-
- int
- ble_gap_adv_start(
- uint8_t own_addr_type,
- const ble_addr_t *direct_addr,
- int32_t duration_ms,
- const struct ble_gap_adv_params *adv_params,
- ble_gap_event_fn *cb,
- void *cb_arg
- )
-
-This function gives an application quite a bit of freedom in how
-advertising is to be done. The default values are mostly fine for our
-simple beaconing application. We will pass the following values to this
-function:
-
-+--------------+----------+----------+
-| Parameter | Value | Notes |
-+==============+==========+==========+
-| own\_addr\_t | BLE\_OWN | Use the |
-| ype | \_ADDR\_ | nRPA we |
-| | RANDOM | generate |
-| | | d |
-| | | earlier. |
-+--------------+----------+----------+
-| direct\_addr | NULL | We are |
-| | | broadcas |
-| | | ting, |
-| | | not |
-| | | targetin |
-| | | g |
-| | | a peer. |
-+--------------+----------+----------+
-| duration\_ms | BLE\_HS\ | Advertis |
-| | _FOREVER | e |
-| | | indefini |
-| | | tely. |
-+--------------+----------+----------+
-| adv\_params | defaults | Can be |
-| | | used to |
-| | | specify |
-| | | low |
-| | | level |
-| | | advertis |
-| | | ing |
-| | | paramete |
-| | | rs. |
-+--------------+----------+----------+
-| cb | NULL | We are |
-| | | non-conn |
-| | | ectable, |
-| | | so no |
-| | | need for |
-| | | an event |
-| | | callback |
-| | | . |
-+--------------+----------+----------+
-| cb\_arg | NULL | No |
-| | | callback |
-| | | implies |
-| | | no |
-| | | callback |
-| | | argument |
-| | | . |
-+--------------+----------+----------+
-
-These arguments are mostly self-explanatory. The exception is
-``adv_params``, which can be used to specify a number of low-level
-parameters. For a beaconing application, the default settings are
-appropriate. We specify default settings by providing a zero-filled
-instance of the ``ble_gap_adv_params`` struct as our argument.
-
-\`\`\`c hl\_lines="4 15 16 17 18 19" static void
-ble\_app\_advertise(void) { struct ble\_gap\_adv\_params adv\_params;
-uint8\_t uuid128[16]; int rc;
-
-::
-
- /* Arbitrarily set the UUID to a string of 0x11 bytes. */
- memset(uuid128, 0x11, sizeof uuid128);
-
- /* Major version=2; minor version=10. */
- rc = ble_ibeacon_set_adv_data(uuid128, 2, 10);
- assert(rc == 0);
-
- /* Begin advertising. */
- adv_params = (struct ble_gap_adv_params){ 0 };
- rc = ble_gap_adv_start(BLE_OWN_ADDR_RANDOM, NULL, BLE_HS_FOREVER,
- &adv_params, NULL, NULL);
- assert(rc == 0);
-
-} \`\`\`
-
-Conclusion
-~~~~~~~~~~
-
-That's it! Now when you run this app on your board, you should be able
-to see it with all your iBeacon-aware devices. You can test it out with
-the ``newt run`` command.
-
-Source Listing
-~~~~~~~~~~~~~~
-
-For reference, here is the complete application source:
-
-.. code:: c
-
- #include "sysinit/sysinit.h"
- #include "os/os.h"
- #include "console/console.h"
- #include "host/ble_hs.h"
-
- static void
- ble_app_set_addr(void)
- {
- ble_addr_t addr;
- int rc;
-
- rc = ble_hs_id_gen_rnd(1, &addr);
- assert(rc == 0);
-
- rc = ble_hs_id_set_rnd(addr.val);
- assert(rc == 0);
- }
-
- static void
- ble_app_advertise(void)
- {
- struct ble_gap_adv_params adv_params;
- uint8_t uuid128[16];
- int rc;
-
- /* Arbitrarily set the UUID to a string of 0x11 bytes. */
- memset(uuid128, 0x11, sizeof uuid128);
-
- /* Major version=2; minor version=10. */
- rc = ble_ibeacon_set_adv_data(uuid128, 2, 10);
- assert(rc == 0);
-
- /* Begin advertising. */
- adv_params = (struct ble_gap_adv_params){ 0 };
- rc = ble_gap_adv_start(BLE_OWN_ADDR_RANDOM, NULL, BLE_HS_FOREVER,
- &adv_params, NULL, NULL);
- assert(rc == 0);
- }
-
- static void
- ble_app_on_sync(void)
- {
- /* Generate a non-resolvable private address. */
- ble_app_set_addr();
-
- /* Advertise indefinitely. */
- ble_app_advertise();
- }
-
- int
- main(int argc, char **argv)
- {
- sysinit();
-
- ble_hs_cfg.sync_cb = ble_app_on_sync;
-
- /* As the last thing, process events from default event queue. */
- while (1) {
- os_eventq_run(os_eventq_dflt_get());
- }
- }
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services