1.. zephyr:code-sample:: tftp-client
2   :name: TFTP client
3   :relevant-api: tftp_client
4
5   Use the TFTP client library to get/put files from/to a TFTP server.
6
7Overview
8********
9
10Trivial File Transfer Protocol (TFTP) is a simple lockstep File Transfer Protocol
11based on UDP, and is designed to get a file from or put a file onto a remote host.
12
13This TFTP client sample application for Zephyr implements the TFTP client library
14and establishes a connection to a TFTP server on standard port 69.
15
16The source code for this sample application can be found at:
17:zephyr_file:`samples/net/tftp_client`.
18
19Requirements
20************
21
22- :ref:`networking_with_eth_qemu`, :ref:`networking_with_qemu` or :ref:`networking_with_native_sim`
23- Linux machine
24
25Building and Running
26********************
27
28There are configuration files for various setups in the
29samples/net/tftp_client directory:
30
31- :file:`prj.conf`
32  This is the standard default config.
33
34Build the tftp-client sample application like this:
35
36.. zephyr-app-commands::
37   :zephyr-app: samples/net/tftp_client
38   :board: <board to use>
39   :conf: <config file to use>
40   :goals: build
41   :compact:
42
43The easiest way to setup this sample application is to build and run it
44as a native_sim application or as a QEMU target using the default configuration :file:`prj.conf`.
45This requires a small amount of setup described in :ref:`networking_with_eth_qemu`, :ref:`networking_with_qemu` and :ref:`networking_with_native_sim`.
46
47Build the tftp-client sample application for :ref:`native_sim <native_sim>` like this:
48
49.. zephyr-app-commands::
50   :zephyr-app: samples/net/tftp_client
51   :host-os: unix
52   :board: native_sim
53   :goals: run
54   :compact:
55
56Download and run a TFTP server (like TFTPd), then create file1.bin (with data) and newfile.bin.
57
58Please note that default IP server address is 192.0.2.2 and default port is 69.
59To specify an IP server address and/or port, change these configurations in ``prj.conf``:
60
61.. code-block:: cfg
62
63    CONFIG_TFTP_APP_SERVER="10.0.0.10"
64    CONFIG_TFTP_APP_PORT="70"
65
66To connect to server using hostname, enable DNS resolver by changing these two
67configurations in ``prj.conf``:
68
69.. code-block:: cfg
70
71    CONFIG_DNS_RESOLVER=y
72    CONFIG_TFTP_APP_SERVER="my-tftp-server.org"
73
74Sample output
75==================================
76
77This sample can be run on :ref:`native_sim<native_sim>` while running a TFTP server on the host
78machine.
79
80Launch :command:`net-setup.sh` in net-tools:
81
82.. code-block:: bash
83
84   net-setup.sh
85
86.. code-block:: bash
87
88    <inf> net_config: Initializing network
89    <inf> net_config: IPv4 address: 192.0.2.1
90    <inf> net_tftp_client_app: Run TFTP client
91    <inf> net_tftp_client_app: Received data:
92            74 65 73 74 74 66 74 70  66 6f 72 7a 65 70 68 79 |testtftp forzephy
93            72 0a                                            |r.
94    <inf> net_tftp_client_app: TFTP client get done
95    <inf> net_tftp_client_app: TFTP client put done
96