1.. zephyr:code-sample:: shell-fs
2   :name: File system shell
3   :relevant-api: file_system_api
4
5   Access a LittleFS file system partition in flash using the file system shell.
6
7Overview
8********
9
10This example provides shell access to a LittleFS file system partition in flash.
11
12Requirements
13************
14
15A board with LittleFS file system support and UART console
16
17Building
18********
19
20native_sim
21==========
22
23You can build this sample for :ref:`native_sim <native_sim>` with:
24
25.. zephyr-app-commands::
26   :zephyr-app: samples/subsys/shell/fs
27   :board: native_sim
28   :goals: build
29   :compact:
30
31Which by default will use the flash simulator. The flash simulator will use a file,
32:file:`flash.bin`, in the current directory to keep the flash content.
33You have several options to control this. You can check them with:
34
35.. code-block:: console
36
37  zephyr/zephyr.exe -help
38
39Check the :ref:`native_sim UART documentation <native_ptty_uart>` for information on how to connect
40to the UART.
41
42With FUSE access in the host filesystem
43---------------------------------------
44
45If you enable the :ref:`host FUSE filsystem access <native_fuse_flash>`
46you will also have the flash filesystem mounted and accessible from your Linux host filesystem.
47
48Before starting a build, make sure that the i386 pkgconfig directory is in your
49search path and that a 32-bit version of libfuse is installed. For more
50background information on this requirement check
51:ref:`the native_sim documentation <native_fuse_flash>`.
52
53.. code-block:: console
54
55  export PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig
56
57.. zephyr-app-commands::
58   :zephyr-app: samples/subsys/shell/fs
59   :board: native_sim
60   :gen-args: -DCONFIG_FUSE_FS_ACCESS=y
61   :goals: build
62   :compact:
63
64Reel Board
65==========
66
67.. zephyr-app-commands::
68   :zephyr-app: samples/subsys/shell/fs
69   :board: reel_board
70   :goals: build
71   :compact:
72
73Particle Xenon
74==============
75
76This target is customized to support the same SPI NOR partition table as
77the :zephyr:code-sample:`littlefs` sample.
78
79.. zephyr-app-commands::
80   :zephyr-app: samples/subsys/shell/fs
81   :board: particle_xenon
82   :goals: build
83   :compact:
84
85Flash load
86==========
87
88If you want to use the 'flash load' command then build the sample with the
89'prj_flash_load.conf' configuration file. It has defined a larger RX buffer.
90If the buffer is too small then some data may be lost during transfer of large
91files.
92
93Running
94*******
95
96Once the board has booted, you will be presented with a shell prompt.
97All file system related commands are available as sub-commands of fs.
98
99Begin by mounting the LittleFS file system.
100
101.. code-block:: console
102
103  fs mount littlefs /lfs
104
105Loading filesystem from host PC to flash memory
106===============================================
107
108Use command:
109
110.. code-block:: console
111
112  flash load <address> <size>
113
114It allows loading the data via UART, directly into flash memory at a given
115address. Data must be aligned to a value dependent on the target flash memory,
116otherwise it will cause an error and nothing will be loaded.
117
118From the host side file system must be loaded with 'dd' tool with 'bs=64'
119(if the file is loaded in chunks greater than 64B the data is lost and isn't
120received by the Zephyr shell).
121
122Example in Zephyr console:
123
124.. code-block:: console
125
126  flash load 0x7a000 0x5000
127
128Example in the host PC:
129
130.. code-block:: console
131
132  dd if=filesystem of=/dev/ttyACM0 bs=64
133
134During the transfer there are printed messages indicating how many chunks are
135already written. After the successful transfer the 'Read all' message is
136printed.
137
138Files System Shell Commands
139===========================
140
141Mount
142-----
143
144Mount a file system partition to a given mount point
145
146.. code-block:: console
147
148  fs mount (littlefs|fat) <path>
149
150Ls
151--
152
153List all files and directories in a given path
154
155.. code-block:: console
156
157  fs ls [path]
158
159Cd
160--
161
162Change current working directory to given path
163
164.. code-block:: console
165
166  fs cd [path]
167
168Pwd
169---
170
171List current working directory
172
173.. code-block:: console
174
175  fs pwd
176
177Write
178-----
179
180Write hexadecimal numbers to a given file.
181Optionally a offset in the file can be given.
182
183.. code-block:: console
184
185  fs write <path> [-o <offset>] <hex number> ...
186
187Read
188----
189
190Read file and dump in hex and ASCII format
191
192.. code-block:: console
193
194  fs read <path>
195
196Trunc
197-----
198
199Truncate a given file
200
201.. code-block:: console
202
203  fs trunc <path>
204
205Mkdir
206-----
207
208Create a directory
209
210.. code-block:: console
211
212  fs mkdir <path>
213
214Rm
215--
216
217Remove a file or directory
218
219.. code-block:: console
220
221  fs rm <path>
222
223Flash Host Access
224=================
225
226For the :ref:`native sim board <native_sim>` the flash partitions can be accessed from the host
227Linux system.
228
229By default the flash partitions are accessible through the directory *flash*
230relative to the directory where the build is started.
231