diff --git a/doc/subsystems/networking/networking.rst b/doc/subsystems/networking/networking.rst index ea0a7b7a565..3706add44b9 100644 --- a/doc/subsystems/networking/networking.rst +++ b/doc/subsystems/networking/networking.rst @@ -19,3 +19,4 @@ operation of the stacks and how they were implemented. net-app-api.rst buffers.rst qemu_setup.rst + usbnet_setup.rst diff --git a/doc/subsystems/networking/usbnet_setup.rst b/doc/subsystems/networking/usbnet_setup.rst new file mode 100644 index 00000000000..d811d461374 --- /dev/null +++ b/doc/subsystems/networking/usbnet_setup.rst @@ -0,0 +1,101 @@ +.. _usb_device_networking_setup: + +USB Device Networking +##################### + +This page describes how to set up networking between a Linux host +and a Zephyr application running on USB supported devices. + +The board is connected to Linux host using USB cable +and provides an Ethernet interface to the host. +The :ref:`echo-server-sample` application from the Zephyr source +distribution is run on supported board. The board is connected to a +Linux host using a USB cable providing an Ethernet interface to the host. + +Basic Setup +*********** + +To communicate with the Zephyr application over a newly created Ethernet +interface, we need to assign IP addresses and set up a routing table for +the Linux host. +After plugging a USB cable from the board to the Linux host, the +``cdc_ether`` driver registers a new Ethernet device with a provided MAC +address. + +You can check that network device is created and MAC address assigned by +running dmesg from the Linux host. + +.. code-block:: console + + cdc_ether 1-2.7:1.0 eth0: register 'cdc_ether' at usb-0000:00:01.2-2.7, CDC Ethernet Device, 00:00:5e:00:53:01 + +We need to set it up and assign IP addresses as explained in the following +section. + +Choosing IP addresses +===================== + +To establish network connection to the board we need to choose IP address +for the interface on the Linux host. + +It make sense to choose addresses in the same subnet we have in Zephyr +application. IP addresses usually set in the project configuration files +and may be checked also from the shell with following commands. Connect +a serial console program (such as puTTY) to the board, and enter this +command to the Zephyr shell: + +.. code-block:: console + + shell> net iface + + Interface 0xa800e580 (Ethernet) + =============================== + Link addr : 00:00:5E:00:53:00 + MTU : 1500 + IPv6 unicast addresses (max 2): + fe80::200:5eff:fe00:5300 autoconf preferred infinite + 2001:db8::1 manual preferred infinite + ... + IPv4 unicast addresses (max 1): + 192.0.2.1 manual preferred infinite + +This command shows that one IPv4 address and two IPv6 addresses have +been assigned to the board. We can use either IPv4 or IPv6 for network +connection depending on the board network configuration. + +Next step is to assign IP addresses to the new Linux host interface, in +the following steps ``enx00005e005301`` is the name of the interface on my +Linux system. + +Setting IPv4 address and routing +================================ + +.. code-block:: console + + # ip address add dev enx00005e005301 192.0.2.2 + # ip link set enx00005e005301 up + # ip route add 192.0.2.0/24 dev enx00005e005301 + +Setting IPv6 address and routing +================================ + +.. code-block:: console + + # ip address add dev enx00005e005301 2001:db8::2 + # ip link set enx00005e005301 up + # ip -6 route add 2001:db8::/64 dev enx00005e005301 + +Testing connection +****************** + +From the host we can test the connection by pinging Zephyr IP address of +the board with: + +.. code-block:: console + + $ ping 192.0.2.1 + PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. + 64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=2.30 ms + 64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=1.43 ms + 64 bytes from 192.0.2.1: icmp_seq=3 ttl=64 time=2.45 ms + ... diff --git a/samples/net/echo_server/README.rst b/samples/net/echo_server/README.rst index 22dba9da539..55105460149 100644 --- a/samples/net/echo_server/README.rst +++ b/samples/net/echo_server/README.rst @@ -60,6 +60,10 @@ echo-server directory: - :file:`prj_sam_e70_xplained.conf` Use this for Atmel SMART SAM E70 Xplained board with ethernet. +- :file:`prj_netusb.conf` + Use this for Ethernet over USB setup with supported boards. The setup is + described in :ref:`usb_device_networking_setup`. + Build echo-server sample application like this: .. zephyr-app-commands::