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