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