# Beaconing example

@tagSupportAllCompatibleBoards

This example shows how to do concurrent beaconing, which allows an application to
advertise beacons (such as iBeacon or Eddystone beacons) while participating
in the Bluetooth mesh network. Moreover, it demonstrates the usage of the RX callback.

**Table of contents**
- [Beacon sending](@ref beaconing_example_sending_beacons)
- [RX callback](@ref beaconing_example_rx_callback)
- [Hardware requirements](@ref beaconing_example_requirements_hw)
- [Software requirements](@ref beaconing_example_requirements_sw)
- [Setup](@ref beaconing_example_setup)
- [Testing the example](@ref beaconing_example_testing)

## Beacon sending @anchor beaconing_example_sending_beacons

To send beacons, the application uses the mesh-internal packet manager and
advertiser structure directly.

The application first initializes the advertiser (initialization is needed only once).
It then allocates and fills the fields of the packet. There is no need to set
the packet type or advertisement address, because this is
taken care of by the advertiser module.

After the initialization, the application schedules the packet
for transmission by putting it in the TX queue of the advertiser, with a parameter
indicating the number of repeats that the advertiser will do. In this example,
the repeat count is set to `BEARER_ADV_REPEAT_INFINITE`, which causes the packet to
be retransmitted forever or until replaced by a different packet.

@warning
Using the packet manager and advertiser directly makes the
application compete for the same resources as the Bluetooth mesh core framework. Incorrect or
heavy usage will affect Bluetooth mesh performance or stability. Treat these modules
with caution.

## RX callback @anchor beaconing_example_rx_callback

The beaconing example also demonstrates the usage of the [RX callback](@ref nrf_mesh_rx_cb_t).
This functionality allows to receive all non-filtered, BLE-compliant advertisement packets in
the application code. These packets are captured by @ref SCANNER.

The RX callback can be registered through @ref nrf_mesh_rx_cb_set().
As an input, the RX callback function takes a pointer to a @ref nrf_mesh_adv_packet_rx_data_t struct
that contains all data available on the incoming packet.

Once a new packet is captured by the Scanner, the filtering is applied. By default, the Bluetooth mesh
filters out non-mesh packets. If the new packet is not filtered out, it is passed through the provided
RX callback to the user application.

There are various filter types that can be used to filter out the incoming packets.
See @ref MESH_API_GROUP_BEARER_FILTER for more details.

The RX callback is invoked for all packets that are processed by the Bluetooth mesh after the mesh
itself has processed them. The Bluetooth mesh assumes that all incoming packets adhere to the
Bluetooth Low Energy advertisement packet format.

In the beaconing example, in addition to the Bluetooth mesh packets' filtering, the filtering by
the Complete Local Name Advertising Data Type (AD Type) is applied. It means that the packets
containing Complete Local Name AD Type will also be passed to the RX callback.

---

## Hardware requirements @anchor beaconing_example_requirements_hw

You need one compatible development kit for this beaconing example.

See @ref md_doc_user_guide_mesh_compatibility for information about
the compatible development kits.

---

## Software requirements @anchor beaconing_example_requirements_sw

You need to install nRF Connect in one of the following versions:
- @link_nRFConnectDesktop
- @link_nRFConnectMobile


---

## Setup @anchor beaconing_example_setup

You can find the source code of the beaconing example in the following folder: `<InstallFolder>/examples/beaconing`

---

## Testing the example @anchor beaconing_example_testing

To test the beaconing example:
1. Build the example by following the instructions in [Building the Bluetooth mesh stack](@ref md_doc_getting_started_how_to_build).
2. Program the board by following the instructions in @ref md_doc_getting_started_how_to_run_examples.
3. Connect [RTT viewer](@ref segger-rtt) to see the RTT output generated by the beaconing example in the RTT log.

Once the example is running, it outputs all non-filtered incoming packets over RTT. Outgoing
beacons can be observed with nRF Connect for Desktop or nRF Connect for Mobile.