1.. _nrf52_bsim:
2
3NRF52 simulated board (BabbleSim)
4#################################
5
6.. contents::
7   :depth: 1
8   :backlinks: entry
9   :local:
10
11
12Overview
13********
14
15This is a :ref:`POSIX architecture<Posix arch>`
16based simulated NRF52 board which uses `BabbleSim`_ to simulate the radio
17activity.
18This board models some of the NRF52 SOC peripherals:
19
20* Radio
21* Timers
22* Real time counter
23* Random number generator
24* AES CCM & AES ECB encryption HW
25* Accelerated address resolver
26* Clock control
27* PPI (Programmable Peripheral Interconnect)
28* EGU (Event Generator Unit)
29* TEMP (Temperature sensor)
30* UICR (User information configuration registers)
31* NVMC (Non-volatile memory controller)
32
33The nrf52_bsim board definition uses the POSIX architecture to
34run applications natively on the development system, this has the benefit of
35providing native code execution performance and easy debugging using
36native tools, but inherits :ref:`its limitations <posix_arch_limitations>`.
37
38.. _BabbleSim:
39   https://BabbleSim.github.io
40
41.. _nrf52bsim_build_and_run:
42
43Building and running
44**********************
45
46This board requires the host 32 bit C library. See
47:ref:`POSIX Arch dependencies<posix_arch_deps>`.
48
49To target this board you also need to have `BabbleSim`_ compiled in your system.
50If you do not have it yet, the easiest way to get it, is to enable the babblesim group
51in your local west configuration, running west update, and building the simulator:
52
53.. code-block:: console
54
55   west config manifest.group-filter -- +babblesim
56   west update
57   cd ${ZEPHYR_BASE}/../tools/bsim
58   make everything -j 8
59
60.. note::
61
62   If you need more BabbleSim components, or more up to date versions,
63   you can check the `BabbleSim web page <https://BabbleSim.github.io>`_
64   for instructions on how to
65   `fetch <https://babblesim.github.io/fetching.html>`_ and
66   `build <https://babblesim.github.io/building.html>`_ it.
67
68You will now need to define two environment variables to point to your BabbleSim
69installation, ``BSIM_OUT_PATH`` and ``BSIM_COMPONENTS_PATH``.
70If you followed the previous steps, you can just do:
71
72.. code-block:: console
73
74   export BSIM_OUT_PATH=${ZEPHYR_BASE}/../tools/bsim
75   export BSIM_COMPONENTS_PATH=${BSIM_OUT_PATH}/components/
76
77.. note::
78
79   You can add these two lines to your ``~/.zephyrrc`` file, or to your shell
80   initialization script (``~/.bashrc``), so you won't need to rerun them
81   manually for each new shell.
82
83You're now ready to build applications targeting this board, for example:
84
85.. zephyr-app-commands::
86   :zephyr-app: samples/hello_world
87   :host-os: unix
88   :board: nrf52_bsim
89   :goals: build
90   :compact:
91
92Then you can execute your application using:
93
94.. code-block:: console
95
96   $ ./build/zephyr/zephyr.exe -nosim
97   # Press Ctrl+C to exit
98
99Note that the executable is a BabbleSim executable. The ``-nosim`` command line
100option indicates you want to run it detached from a BabbleSim simulation. This
101is possible only while there is no radio activity. But is perfectly fine for
102most Zephyr samples and tests.
103
104When you want to run a simulation with radio activity you need to run also the
105BableSim 2G4 (2.4GHz) physical layer simulation (phy).
106
107For example, if you would like to run a simple case with 1 BLE ``central_hr``
108sample application connecting to a BLE ``peripheral`` sample application:
109Build the ``central_hr`` application targeting this board and copy the resulting
110executable to the simulator bin folder with a sensible name:
111
112.. zephyr-app-commands::
113   :zephyr-app: samples/bluetooth/central_hr
114   :host-os: unix
115   :board: nrf52_bsim
116   :goals: build
117   :compact:
118
119.. code-block:: console
120
121   $ cp build/zephyr/zephyr.exe \
122     ${BSIM_OUT_PATH}/bin/bs_nrf52_bsim_samples_bluetooth_central_hr
123
124Do the same for the ``peripheral`` sample app:
125
126.. zephyr-app-commands::
127   :zephyr-app: samples/bluetooth/peripheral
128   :host-os: unix
129   :board: nrf52_bsim
130   :goals: build
131   :compact:
132
133.. code-block:: console
134
135   $ cp build/zephyr/zephyr.exe \
136     ${BSIM_OUT_PATH}/bin/bs_nrf52_bsim_samples_bluetooth_peripheral
137
138And then run them together with BabbleSim's 2G4 physical layer simulation:
139
140.. code-block:: console
141
142   cd ${BSIM_OUT_PATH}/bin/
143   ./bs_nrf52_bsim_samples_bluetooth_peripheral -s=trial_sim -d=0 &
144   ./bs_nrf52_bsim_samples_bluetooth_central_hr -s=trial_sim -d=1 &
145   ./bs_2G4_phy_v1 -s=trial_sim -D=2 -sim_length=10e6 &
146
147Where the ``-s`` command line option provides a string which uniquely identifies
148this simulation; the ``-D`` option tells the Phy how many devices will be run
149in this simulation; the ``-d`` option tells each device which is its device
150number in the simulation; and the ``-sim_length`` option specifies the length
151of the simulation in microseconds.
152BabbleSim devices and Phy support many command line switches.
153Run them with ``-help`` for more information.
154
155You can find more information about how to run BabbleSim simulations in
156`this BabbleSim example <https://babblesim.github.io/example_2g4.html>`_.
157
158Debugging, coverage and address sanitizer
159*****************************************
160
161Just like with :ref:`native_posix<native_posix_debug>`, the resulting
162executables are Linux native applications.
163Therefore they can be debugged or instrumented with the same tools as any other
164native application, like for example ``gdb`` or ``valgrind``.
165
166The same
167:ref:`code coverage analysis means from the POSIX arch<coverage_posix>`
168are inherited in this board.
169Similarly, the
170:ref:`address and undefined behavior sanitizers can be used as in native_posix<native_posix_asan>`.
171
172
173Note that BabbleSim will run fine if one or several of its components are
174being run in a debugger or instrumented. For example, pausing a device in a
175breakpoint will pause the whole simulation.
176
177BabbleSim is fully deterministic by design and the results are not affected by
178the host computing speed. All randomness is controlled by random seeds which can
179be provided as command line options.
180
181
182About time in BabbleSim
183************************
184
185Note that time in BabbleSim is simulated and decoupled from real time. Normally
186simulated time will pass several orders of magnitude faster than real time,
187only limited by your workstation compute power.
188If for some reason you want to limit the speed of the simulation to real
189time or a ratio of it, you can do so by connecting the `handbrake device`_
190to the BabbleSim Phy.
191
192.. _handbrake device:
193   https://github.com/BabbleSim/base/tree/master/device_handbrake
194