1.. _usb_device_networking_setup:
2
3USB Device Networking
4#####################
5
6.. contents::
7    :local:
8    :depth: 2
9
10This page describes how to set up networking between a Linux host
11and a Zephyr application running on USB supported devices.
12
13The board is connected to Linux host using USB cable
14and provides an Ethernet interface to the host.
15The :zephyr:code-sample:`sockets-echo-server` application from the Zephyr source
16distribution is run on supported board.  The board is connected to a
17Linux host using a USB cable providing an Ethernet interface to the host.
18
19Basic Setup
20***********
21
22To communicate with the Zephyr application over a newly created Ethernet
23interface, we need to assign IP addresses and set up a routing table for
24the Linux host.
25After plugging a USB cable from the board to the Linux host, the
26``cdc_ether`` driver registers a new Ethernet device with a provided MAC
27address.
28
29You can check that network device is created and MAC address assigned by
30running dmesg from the Linux host.
31
32.. code-block:: console
33
34   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
35
36We need to set it up and assign IP addresses as explained in the following
37section.
38
39Choosing IP addresses
40=====================
41
42To establish network connection to the board we need to choose IP address
43for the interface on the Linux host.
44
45It make sense to choose addresses in the same subnet we have in Zephyr
46application. IP addresses usually set in the project configuration files
47and may be checked also from the shell with following commands. Connect
48a serial console program (such as puTTY) to the board, and enter this
49command to the Zephyr shell:
50
51.. code-block:: console
52
53   shell> net iface
54
55   Interface 0xa800e580 (Ethernet)
56   ===============================
57   Link addr : 00:00:5E:00:53:00
58   MTU       : 1500
59   IPv6 unicast addresses (max 2):
60           fe80::200:5eff:fe00:5300 autoconf preferred infinite
61           2001:db8::1 manual preferred infinite
62   ...
63   IPv4 unicast addresses (max 1):
64           192.0.2.1 manual preferred infinite
65
66This command shows that one IPv4 address and two IPv6 addresses have
67been assigned to the board. We can use either IPv4 or IPv6 for network
68connection depending on the board network configuration.
69
70Next step is to assign IP addresses to the new Linux host interface, in
71the following steps ``enx00005e005301`` is the name of the interface on my
72Linux system.
73
74Setting IPv4 address and routing
75================================
76
77.. code-block:: console
78
79   # ip address add dev enx00005e005301 192.0.2.2
80   # ip link set enx00005e005301 up
81   # ip route add 192.0.2.0/24 dev enx00005e005301
82
83Setting IPv6 address and routing
84================================
85
86.. code-block:: console
87
88   # ip address add dev enx00005e005301 2001:db8::2
89   # ip link set enx00005e005301 up
90   # ip -6 route add 2001:db8::/64 dev enx00005e005301
91
92Testing connection
93******************
94
95From the host we can test the connection by pinging Zephyr IP address of
96the board with:
97
98.. code-block:: console
99
100   $ ping 192.0.2.1
101   PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
102   64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=2.30 ms
103   64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=1.43 ms
104   64 bytes from 192.0.2.1: icmp_seq=3 ttl=64 time=2.45 ms
105   ...
106