0
# Command-Line Interface
1

2
Command-line tools for creating LittleFS images from directories, extracting filesystem contents, and inspecting binary images. The CLI provides essential utilities for embedded systems development, build processes, and filesystem management workflows.
3

4
## Capabilities
5

6
### CLI Entry Points
7

8
The package provides a command-line executable accessible through multiple methods:
9

10
```bash
11
# Direct executable (after pip install)
12
littlefs-python --help
13

14
# Python module execution
15
python -m littlefs --help
16
```
17

18
### Global Options
19

20
Common options available across all commands:
21

22
```python { .api }
23
# Global CLI options
24
--version           # Show package version
25
-v, --verbose       # Increase verbosity (can be repeated)
26
--name-max SIZE     # Maximum filename length (default: 255)
27
```
28

29
### Create Command
30

31
Creates LittleFS binary images from files and directories with configurable filesystem parameters.
32

33
```python { .api }
34
def create(source: Path, destination: Path = "lfs.bin", *, 
35
           block_size: int, block_count: int = None, fs_size: int = None,
36
           compact: bool = False, no_pad: bool = False) -> int:
37
    """
38
    Create LittleFS image from file/directory contents.
39
    
40
    Parameters:
41
    - source: Path, source file or directory to encode
42
    - destination: Path, output binary image file (default: lfs.bin)
43
    - block_size: int, LittleFS block size (required)
44
    - block_count: int, number of blocks (mutually exclusive with fs_size)
45
    - fs_size: int, total filesystem size (mutually exclusive with block_count)
46
    - compact: bool, store data in beginning blocks only
47
    - no_pad: bool, don't pad binary to full size (only with --compact)
48
    
49
    Returns:
50
    int: 0 on success, non-zero on error
51
    """
52
```
53

54
**Command Usage:**
55
```bash
56
# Create from directory
57
littlefs-python create my_files/ filesystem.bin --block-size 4096 --fs-size 1MB
58

59
# Create from single file  
60
littlefs-python create important.txt single_file.bin --block-size 512 --block-count 256
61

62
# Create compact image
63
littlefs-python create data/ compact.bin --block-size 1024 --fs-size 512KB --compact
64

65
# Create without padding
66
littlefs-python create small_data/ minimal.bin --block-size 512 --fs-size 64KB --compact --no-pad
67
```
68

69
### Extract Command
70

71
Extracts LittleFS binary images to directory structures, recreating the original file hierarchy.
72

73
```python { .api }
74
def extract(source: Path, destination: Path = ".", *, block_size: int) -> int:
75
    """
76
    Extract LittleFS image contents to directory.
77
    
78
    Parameters:
79
    - source: Path, LittleFS binary image to extract
80
    - destination: Path, output directory (default: current directory)
81
    - block_size: int, LittleFS block size (required)
82
    
83
    Returns:
84
    int: 0 on success, non-zero on error
85
    """
86
```
87

88
**Command Usage:**
89
```bash
90
# Extract to current directory
91
littlefs-python extract filesystem.bin --block-size 4096
92

93
# Extract to specific directory
94
littlefs-python extract image.bin extracted_files/ --block-size 512
95

96
# Extract with verbose output
97
littlefs-python extract -v system.bin recovery/ --block-size 1024
98
```
99

100
### List Command
101

102
Lists contents of LittleFS binary images without extracting files, useful for inspection and verification.
103

104
```python { .api }
105
def list(source: Path, *, block_size: int) -> int:
106
    """
107
    List LittleFS image contents.
108
    
109
    Parameters:
110
    - source: Path, LittleFS binary image to inspect
111
    - block_size: int, LittleFS block size (required)
112
    
113
    Returns:
114
    int: 0 on success, non-zero on error
115
    """
116
```
117

118
**Command Usage:**
119
```bash
120
# List all files and directories
121
littlefs-python list filesystem.bin --block-size 4096
122

123
# List with detailed output
124
littlefs-python list -v image.bin --block-size 512
125
```
126

127
### Size Parser Utility
128

129
Built-in parser for filesystem and block sizes with unit support:
130

131
```python { .api }
132
def size_parser(size_str: str) -> int:
133
    """
134
    Parse size strings with unit suffixes.
135
    
136
    Parameters:
137
    - size_str: str, size with optional suffix
138
    
139
    Supported formats:
140
    - Decimal: "1024", "2048"
141
    - Hexadecimal: "0x400", "0x800" 
142
    - With units: "1KB", "2MB", "1GB"
143
    - Base suffix: "1024B" (B suffix ignored)
144
    
145
    Units (case-insensitive):
146
    - KB: 1024 bytes
147
    - MB: 1024² bytes  
148
    - GB: 1024³ bytes
149
    
150
    Returns:
151
    int: Size in bytes
152
    """
153
```
154

155
## CLI Configuration Details
156

157
### Block Size Requirements
158

159
Block size must meet LittleFS constraints:
160
- Minimum: 128 bytes
161
- Typical: 512, 1024, 2048, 4096 bytes
162
- Must match target flash memory erase block size
163

164
### Filesystem Size Options
165

166
Two mutually exclusive ways to specify filesystem size:
167

168
1. **Block Count**: `--block-count N` (direct block specification)
169
2. **Total Size**: `--fs-size SIZE` (automatically calculates blocks)
170

171
The filesystem size must be a multiple of block size.
172

173
### Compact Mode
174

175
When `--compact` is used:
176
- Files are stored in the minimum number of blocks
177
- Reduces image size for embedded systems
178
- Can be combined with `--no-pad` to eliminate trailing 0xFF bytes
179
- Original block count is preserved unless `--no-pad` is used
180

181
## Usage Examples
182

183
### Build System Integration
184

185
```bash
186
#!/bin/bash
187
# build_filesystem.sh - Build script for embedded project
188

189
SOURCE_DIR="firmware_files"
190
OUTPUT_IMAGE="firmware_fs.bin"
191
BLOCK_SIZE=4096
192
FS_SIZE="2MB"
193

194
echo "Building LittleFS image..."
195
littlefs-python create "$SOURCE_DIR" "$OUTPUT_IMAGE" \
196
    --block-size $BLOCK_SIZE \
197
    --fs-size $FS_SIZE \
198
    --compact \
199
    --verbose
200

201
if [ $? -eq 0 ]; then
202
    echo "Filesystem image created: $OUTPUT_IMAGE"
203
    littlefs-python list "$OUTPUT_IMAGE" --block-size $BLOCK_SIZE
204
else
205
    echo "Failed to create filesystem image"
206
    exit 1
207
fi
208
```
209

210
### Development Workflow
211

212
```bash
213
# Development cycle: create, test, extract, modify
214

215
# 1. Create filesystem from development files
216
littlefs-python create dev_files/ test.bin --block-size 1024 --fs-size 256KB -v
217

218
# 2. List contents to verify
219
littlefs-python list test.bin --block-size 1024 -v
220

221
# 3. Extract to verify round-trip
222
mkdir -p extracted
223
littlefs-python extract test.bin extracted/ --block-size 1024 -v
224

225
# 4. Compare original and extracted
226
diff -r dev_files/ extracted/
227
```
228

229
### Multiple Image Sizes
230

231
```bash
232
# Create different image sizes for different targets
233

234
# Small embedded device (64KB flash)
235
littlefs-python create config/ small.bin --block-size 512 --fs-size 64KB --compact
236

237
# Medium device (1MB flash)  
238
littlefs-python create app_data/ medium.bin --block-size 2048 --fs-size 1MB
239

240
# Large device (8MB flash)
241
littlefs-python create full_system/ large.bin --block-size 4096 --fs-size 8MB
242

243
# List sizes
244
ls -lh *.bin
245
```
246

247
### CI/CD Integration
248

249
```yaml
250
# .github/workflows/build.yml
251
name: Build Filesystem Images
252

253
on: [push, pull_request]
254

255
jobs:
256
  build-fs:
257
    runs-on: ubuntu-latest
258
    steps:
259
    - uses: actions/checkout@v3
260
    
261
    - name: Set up Python
262
      uses: actions/setup-python@v4
263
      with:
264
        python-version: '3.9'
265
        
266
    - name: Install littlefs-python
267
      run: pip install littlefs-python
268
      
269
    - name: Create filesystem images
270
      run: |
271
        littlefs-python create firmware/ firmware.bin --block-size 4096 --fs-size 2MB --compact -v
272
        littlefs-python create bootloader/ boot.bin --block-size 512 --fs-size 128KB --compact -v
273
        
274
    - name: Verify images
275
      run: |
276
        littlefs-python list firmware.bin --block-size 4096 -v
277
        littlefs-python list boot.bin --block-size 512 -v
278
        
279
    - name: Upload artifacts
280
      uses: actions/upload-artifact@v3
281
      with:
282
        name: filesystem-images
283
        path: '*.bin'
284
```
285

286
### Advanced Size Calculations
287

288
```bash
289
# Calculate optimal sizes for different scenarios
290

291
# Exact fit (no wasted space)
292
SOURCE_SIZE=$(du -sb source_files/ | cut -f1)
293
BLOCK_SIZE=1024
294
BLOCKS_NEEDED=$(( (SOURCE_SIZE + BLOCK_SIZE - 1) / BLOCK_SIZE ))  # Ceiling division
295
FILESYSTEM_SIZE=$(( BLOCKS_NEEDED * BLOCK_SIZE ))
296

297
echo "Source: ${SOURCE_SIZE} bytes"
298
echo "Blocks needed: ${BLOCKS_NEEDED}"  
299
echo "Filesystem size: ${FILESYSTEM_SIZE} bytes"
300

301
littlefs-python create source_files/ exact.bin \
302
    --block-size $BLOCK_SIZE \
303
    --block-count $BLOCKS_NEEDED \
304
    --compact
305

306
# With overhead for future additions (25% extra)
307
OVERHEAD_BLOCKS=$(( BLOCKS_NEEDED * 125 / 100 ))
308
littlefs-python create source_files/ with_overhead.bin \
309
    --block-size $BLOCK_SIZE \
310
    --block-count $OVERHEAD_BLOCKS
311
```
312

313
### Validation and Testing
314

315
```bash
316
# Comprehensive validation script
317
validate_filesystem() {
318
    local IMAGE=$1
319
    local BLOCK_SIZE=$2
320
    local TEMP_DIR=$(mktemp -d)
321
    
322
    echo "Validating $IMAGE..."
323
    
324
    # Extract image
325
    littlefs-python extract "$IMAGE" "$TEMP_DIR" --block-size $BLOCK_SIZE
326
    
327
    if [ $? -eq 0 ]; then
328
        echo "✓ Extraction successful"
329
        
330
        # Count files
331
        FILE_COUNT=$(find "$TEMP_DIR" -type f | wc -l)
332
        echo "✓ Contains $FILE_COUNT files"
333
        
334
        # Check for corruption by re-creating and comparing
335
        littlefs-python create "$TEMP_DIR" test_recreate.bin --block-size $BLOCK_SIZE --fs-size 1MB
336
        
337
        # List both images to compare
338
        echo "Original image contents:"
339
        littlefs-python list "$IMAGE" --block-size $BLOCK_SIZE
340
        
341
        echo "Recreated image contents:"
342
        littlefs-python list test_recreate.bin --block-size $BLOCK_SIZE
343
        
344
        rm -f test_recreate.bin
345
    else
346
        echo "✗ Extraction failed"
347
    fi
348
    
349
    rm -rf "$TEMP_DIR"
350
}
351

352
# Test multiple images
353
validate_filesystem firmware.bin 4096
354
validate_filesystem config.bin 512
355
```