1.. _networking_with_native_sim: 2 3Networking with native_sim board 4################################ 5 6.. contents:: 7 :local: 8 :depth: 2 9 10Using virtual/TAP Ethernet driver 11********************************* 12 13This paragraph describes how to set up a virtual network between a (Linux) host 14and a Zephyr application running in a :ref:`native_sim <native_sim>` board. 15 16In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from 17the Zephyr source distribution is run in native_sim board. The Zephyr 18native_sim board instance is connected to a Linux host using a tuntap device 19which is modeled in Linux as an Ethernet network interface. 20 21Prerequisites 22============= 23 24On the Linux Host, find the Zephyr `net-tools`_ project, which can either be 25found in a Zephyr standard installation under the ``tools/net-tools`` directory 26or installed stand alone from its own git repository: 27 28.. code-block:: console 29 30 git clone https://github.com/zephyrproject-rtos/net-tools 31 32 33Basic Setup 34=========== 35 36For the steps below, you will need three terminal windows: 37 38* Terminal #1 is terminal window with net-tools being the current 39 directory (``cd net-tools``) 40* Terminal #2 is your usual Zephyr development terminal, 41 with the Zephyr environment initialized. 42* Terminal #3 is the console to the running Zephyr native_sim 43 instance (optional). 44 45Step 1 - Create Ethernet interface 46---------------------------------- 47 48Before starting native_sim with network emulation, a network interface 49should be created. 50 51In terminal #1, type: 52 53.. code-block:: console 54 55 ./net-setup.sh 56 57You can tweak the behavior of the net-setup.sh script. See various options 58by running ``net-setup.sh`` like this: 59 60.. code-block:: console 61 62 ./net-setup.sh --help 63 64 65Step 2 - Start app in native_sim board 66-------------------------------------- 67 68Build and start the ``echo_server`` sample application. 69 70In terminal #2, type: 71 72.. zephyr-app-commands:: 73 :zephyr-app: samples/net/sockets/echo_server 74 :host-os: unix 75 :board: native_sim 76 :goals: run 77 :compact: 78 79 80Step 3 - Connect to console (optional) 81-------------------------------------- 82 83The console window should be launched automatically when the Zephyr instance is 84started but if it does not show up, you can manually connect to the console. 85The native_sim board will print a string like this when it starts: 86 87.. code-block:: console 88 89 UART connected to pseudotty: /dev/pts/5 90 91You can manually connect to it like this: 92 93.. code-block:: console 94 95 screen /dev/pts/5 96 97Using offloaded sockets 98*********************** 99 100The main advantage over `Using virtual/TAP Ethernet driver`_ is not needing to 101setup a virtual network interface on the host machine. This means that no 102leveraged (root) privileges are needed. 103 104Step 1 - Start app in native_sim board 105====================================== 106 107Build and start the ``echo_server`` sample application: 108 109.. zephyr-app-commands:: 110 :zephyr-app: samples/net/sockets/echo_server 111 :host-os: unix 112 :board: native_sim 113 :gen-args: -DEXTRA_CONF_FILE=overlay-nsos.conf 114 :goals: run 115 :compact: 116 117Step 2 - run echo-client from net-tools 118======================================= 119 120On the Linux Host, find the Zephyr `net-tools`_ project, which can either be 121found in a Zephyr standard installation under the ``tools/net-tools`` directory 122or installed stand alone from its own git repository: 123 124.. code-block:: console 125 126 git clone https://github.com/zephyrproject-rtos/net-tools 127 128.. note:: 129 130 Native Simulator with the offloaded sockets network driver is using the same 131 network interface/namespace as any other (Linux) application that uses BSD 132 sockets API. This means that :zephyr:code-sample:`sockets-echo-server` and 133 ``echo-client`` applications will communicate over localhost/loopback 134 interface (address ``127.0.0.1``). 135 136To run UDP test, type: 137 138.. code-block:: console 139 140 ./echo-client 127.0.0.1 141 142For TCP test, type: 143 144.. code-block:: console 145 146 ./echo-client -t 127.0.0.1 147 148Setting interface name from command line 149**************************************** 150 151By default the Ethernet interface name used by native_sim is determined by 152:kconfig:option:`CONFIG_ETH_NATIVE_POSIX_DRV_NAME`, but is also possible 153to set it from the command line using ``--eth-if=<interface_name>``. 154This can be useful if the application has to be 155run in multiple instances and recompiling it for each instance would be 156troublesome. 157 158.. code-block:: console 159 160 ./zephyr.exe --eth-if=zeth2 161 162.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools 163