You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
173 lines
5.0 KiB
173 lines
5.0 KiB
.. _networking_with_native_sim: |
|
|
|
Networking with native_sim board |
|
################################ |
|
|
|
.. contents:: |
|
:local: |
|
:depth: 2 |
|
|
|
Using virtual/TAP Ethernet driver |
|
********************************* |
|
|
|
This paragraph describes how to set up a virtual network between a (Linux) host |
|
and a Zephyr application running in a :ref:`native_sim <native_sim>` board. |
|
|
|
In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from |
|
the Zephyr source distribution is run in native_sim board. The Zephyr |
|
native_sim board instance is connected to a Linux host using a tuntap device |
|
which is modeled in Linux as an Ethernet network interface. |
|
|
|
Prerequisites |
|
============= |
|
|
|
On the Linux Host, find the Zephyr `net-tools`_ project, which can either be |
|
found in a Zephyr standard installation under the ``tools/net-tools`` directory |
|
or installed stand alone from its own git repository: |
|
|
|
.. code-block:: console |
|
|
|
git clone https://github.com/zephyrproject-rtos/net-tools |
|
|
|
|
|
Basic Setup |
|
=========== |
|
|
|
For the steps below, you will need three terminal windows: |
|
|
|
* Terminal #1 is terminal window with net-tools being the current |
|
directory (``cd net-tools``) |
|
* Terminal #2 is your usual Zephyr development terminal, |
|
with the Zephyr environment initialized. |
|
* Terminal #3 is the console to the running Zephyr native_sim |
|
instance (optional). |
|
|
|
Step 1 - Create Ethernet interface |
|
---------------------------------- |
|
|
|
Before starting native_sim with network emulation, a network interface |
|
should be created. |
|
|
|
In terminal #1, type: |
|
|
|
.. code-block:: console |
|
|
|
./net-setup.sh |
|
|
|
You can tweak the behavior of the net-setup.sh script. See various options |
|
by running ``net-setup.sh`` like this: |
|
|
|
.. code-block:: console |
|
|
|
./net-setup.sh --help |
|
|
|
|
|
Step 2 - Start app in native_sim board |
|
-------------------------------------- |
|
|
|
Build and start the ``echo_server`` sample application. |
|
|
|
In terminal #2, type: |
|
|
|
.. zephyr-app-commands:: |
|
:zephyr-app: samples/net/sockets/echo_server |
|
:host-os: unix |
|
:board: native_sim |
|
:goals: run |
|
:compact: |
|
|
|
|
|
Step 3 - Connect to console (optional) |
|
-------------------------------------- |
|
|
|
The console window should be launched automatically when the Zephyr instance is |
|
started but if it does not show up, you can manually connect to the console. |
|
The native_sim board will print a string like this when it starts: |
|
|
|
.. code-block:: console |
|
|
|
UART connected to pseudotty: /dev/pts/5 |
|
|
|
You can manually connect to it like this: |
|
|
|
.. code-block:: console |
|
|
|
screen /dev/pts/5 |
|
|
|
Using offloaded sockets |
|
*********************** |
|
|
|
The main advantage over `Using virtual/TAP Ethernet driver`_ is not needing to |
|
setup a virtual network interface on the host machine. This means that no |
|
leveraged (root) privileges are needed. |
|
|
|
Step 1 - Start app in native_sim board |
|
====================================== |
|
|
|
Build and start the ``echo_server`` sample application: |
|
|
|
.. zephyr-app-commands:: |
|
:zephyr-app: samples/net/sockets/echo_server |
|
:host-os: unix |
|
:board: native_sim |
|
:gen-args: -DEXTRA_CONF_FILE=overlay-nsos.conf |
|
:goals: run |
|
:compact: |
|
|
|
Step 2 - run echo-client from net-tools |
|
======================================= |
|
|
|
On the Linux Host, find the Zephyr `net-tools`_ project, which can either be |
|
found in a Zephyr standard installation under the ``tools/net-tools`` directory |
|
or installed stand alone from its own git repository: |
|
|
|
.. code-block:: console |
|
|
|
git clone https://github.com/zephyrproject-rtos/net-tools |
|
|
|
.. note:: |
|
|
|
Native Simulator with the offloaded sockets network driver is using the same |
|
network interface/namespace as any other (Linux) application that uses BSD |
|
sockets API. This means that :zephyr:code-sample:`sockets-echo-server` and |
|
``echo-client`` applications will communicate over localhost/loopback |
|
interface (address ``127.0.0.1``). |
|
|
|
To run UDP test, type: |
|
|
|
.. code-block:: console |
|
|
|
./echo-client 127.0.0.1 |
|
|
|
For TCP test, type: |
|
|
|
.. code-block:: console |
|
|
|
./echo-client -t 127.0.0.1 |
|
|
|
Setting interface name and IPv4 parameters from command line |
|
************************************************************ |
|
|
|
By default the Ethernet interface name used by native_sim is determined by |
|
:kconfig:option:`CONFIG_ETH_NATIVE_TAP_DRV_NAME`, but is also possible |
|
to set it from the command line using ``--eth-if=<interface_name>``. |
|
|
|
The same applies to the IPv4 address, gateway and netmask. They can be set |
|
from the command line using ``--ipv4-addr=<ip_address>``, |
|
``--ipv4-gw=<gateway>`` and ``--ipv4-nm=<netmask>``. |
|
|
|
Note that the configuration :kconfig:option:`CONFIG_NET_CONFIG_MY_IPV4_ADDR` |
|
and the command line arguments work in parallel. This means that if both are |
|
set, the interface might end up with two IP addresses. In most cases, it does |
|
make sense to only use one of both at the same time. |
|
|
|
This can be useful if the application has to be |
|
run in multiple instances and recompiling it for each instance would be |
|
troublesome. |
|
|
|
.. code-block:: console |
|
|
|
./zephyr.exe --eth-if=zeth2 --ipv4-addr=192.0.2.2 --ipv4-gw=192.0.0.1 |
|
--ipv4-nm=255.255.0.0 |
|
|
|
.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
|
|
|