0
# ROM Filesystem Management
1

2
Manage ROM filesystem partitions for MicroPython devices, enabling efficient storage and deployment of Python code and data files directly in device ROM memory.
3

4
## Capabilities
5

6
### ROMFS Command Dispatcher
7

8
Main command dispatcher for ROM filesystem operations with query, build, and deploy subcommands.
9

10
```python { .api }
11
def do_romfs(state, args):
12
    """
13
    Execute ROMFS operations on device.
14
    
15
    Parameters:
16
    - state: State object with active transport
17
    - args: Arguments containing subcommand and options
18
    
19
    Subcommands: query, build, deploy
20
    """
21
```
22

23
### Query ROMFS Information
24

25
Query existing ROM filesystem partitions and their contents on the device.
26

27
```python { .api }
28
def _do_romfs_query(state, args):
29
    """
30
    Query ROM filesystem partition information.
31
    
32
    Parameters:
33
    - state: State object with transport
34
    - args: Query options including partition specification
35
    
36
    Args attributes:
37
    - partition: List containing partition number (default: 0)
38
    """
39
```
40

41
### Build ROMFS from Directory
42

43
Build ROM filesystem images from local directory structures with optional bytecode compilation.
44

45
```python { .api }
46
def _do_romfs_build(state, args):
47
    """
48
    Build ROM filesystem from directory.
49
    
50
    Parameters:
51
    - state: State object (not used for build)
52
    - args: Build arguments and options
53
    
54
    Args attributes:
55
    - path: List containing source directory path
56
    - output: Output file path for ROM filesystem image
57
    - mpy: Boolean to compile .py files to .mpy bytecode (default: True)
58
    """
59
```
60

61
### Deploy ROMFS to Device
62

63
Deploy ROM filesystem images to device partitions with verification.
64

65
```python { .api }
66
def _do_romfs_deploy(state, args):
67
    """
68
    Deploy ROM filesystem to device partition.
69
    
70
    Parameters:
71
    - state: State object with active transport
72
    - args: Deploy options including source and partition
73
    
74
    Args attributes:
75
    - path: List containing ROM filesystem image path
76
    - partition: Partition number for deployment (default: 0)
77
    """
78
```
79

80
## Command-Line Interface
81

82
### Query ROMFS Information
83

84
```bash
85
# Query default partition (0)
86
mpremote romfs query
87

88
# Query specific partition
89
mpremote romfs query --partition 1
90
mpremote romfs query -p 2
91
```
92

93
### Build ROMFS Image
94

95
```bash
96
# Build from current directory with default output
97
mpremote romfs build .
98

99
# Build with custom output file
100
mpremote romfs build --output firmware.romfs src/
101

102
# Build without bytecode compilation
103
mpremote romfs build --no-mpy src/
104

105
# Build with specific options
106
mpremote romfs build -o custom.romfs -m src/
107
```
108

109
### Deploy ROMFS to Device
110

111
```bash
112
# Deploy to default partition
113
mpremote romfs deploy firmware.romfs
114

115
# Deploy to specific partition
116
mpremote romfs deploy --partition 1 firmware.romfs
117
mpremote romfs deploy -p 2 custom.romfs
118
```
119

120
## Usage Examples
121

122
### Basic ROMFS Workflow
123

124
```python
125
from mpremote.main import State
126
from mpremote.commands import do_romfs
127

128
# Set up state with connected device
129
state = State()
130
# ... connect to device ...
131

132
# Query existing ROMFS partitions
133
args = type('Args', (), {
134
    'command': ['query'],
135
    'partition': [0]
136
})()
137
do_romfs(state, args)
138

139
# Build ROMFS from directory
140
args = type('Args', (), {
141
    'command': ['build'],
142
    'path': ['./src'],
143
    'output': 'app.romfs',
144
    'mpy': True
145
})()
146
do_romfs(state, args)
147

148
# Deploy to device
149
args = type('Args', (), {
150
    'command': ['deploy'],
151
    'path': ['app.romfs'],
152
    'partition': [0]
153
})()
154
do_romfs(state, args)
155
```
156

157
### Development Workflow
158

159
```bash
160
# Typical development cycle
161
mpremote connect auto
162

163
# Build application from source
164
mpremote romfs build --output app.romfs src/
165

166
# Deploy to device partition 1
167
mpremote romfs deploy --partition 1 app.romfs
168

169
# Query to verify deployment
170
mpremote romfs query --partition 1
171

172
# Test application
173
mpremote exec "
174
import sys
175
sys.path.insert(0, '/romfs1')
176
import main
177
main.run()
178
"
179
```
180

181
### Advanced Usage
182

183
```bash
184
# Build without bytecode compilation for debugging
185
mpremote romfs build --no-mpy --output debug.romfs src/
186

187
# Deploy multiple partitions
188
mpremote romfs build -o core.romfs core/ 
189
mpremote romfs deploy -p 0 core.romfs
190
mpremote romfs build -o app.romfs app/
191
mpremote romfs deploy -p 1 app.romfs
192

193
# Verify deployments
194
mpremote romfs query -p 0
195
mpremote romfs query -p 1
196
```
197

198
## ROM Filesystem Structure
199

200
ROM filesystems use a compact binary format optimized for embedded systems:
201

202
### File Organization
203
- **Header**: ROM filesystem signature and metadata
204
- **Directory entries**: Hierarchical directory structure
205
- **File data**: Compressed file contents with optional bytecode
206

207
### Supported Files
208
- **Python source**: `.py` files (optionally compiled to `.mpy`)
209
- **Data files**: Any binary or text data files
210
- **Subdirectories**: Nested directory structures
211

212
### Bytecode Compilation
213
When `--mpy` is enabled (default):
214
- Python `.py` files are compiled to `.mpy` bytecode
215
- Reduces memory usage and improves load performance
216
- Maintains source code compatibility
217

218
## Error Handling
219

220
ROMFS operations may encounter various error conditions:
221

222
```python
223
from mpremote.transport import TransportError, TransportExecError
224

225
try:
226
    do_romfs(state, args)
227
except TransportExecError as e:
228
    if "partition not found" in e.error_output:
229
        print("Invalid partition number")
230
    elif "insufficient space" in e.error_output: 
231
        print("Not enough ROM space for filesystem")
232
    elif "verification failed" in e.error_output:
233
        print("ROMFS image verification failed")
234
except TransportError as e:
235
    print(f"Communication error: {e}")
236
except FileNotFoundError:
237
    print("Source directory or ROMFS image not found")
238
```
239

240
## Integration with MicroPython
241

242
### Accessing ROMFS Content
243

244
```python
245
# Add ROMFS partition to Python path
246
import sys
247
sys.path.insert(0, '/romfs0')  # Partition 0
248
sys.path.insert(0, '/romfs1')  # Partition 1
249

250
# Import modules from ROMFS
251
import my_module
252
from config import settings
253
```
254

255
### ROMFS Mount Points
256

257
MicroPython automatically mounts ROM filesystems at:
258
- `/romfs0` - Partition 0 (default)
259
- `/romfs1` - Partition 1
260
- `/romfs2` - Partition 2
261
- etc.
262

263
### Performance Benefits
264

265
ROMFS provides several advantages:
266
- **Fast access**: Direct ROM access without filesystem overhead
267
- **Memory efficiency**: Compressed storage and optional bytecode
268
- **Reliability**: Read-only, corruption-resistant storage
269
- **Boot speed**: Faster startup compared to flash filesystem
270

271
## Best Practices
272

273
### Directory Organization
274

275
```bash
276
# Organize source for optimal ROMFS structure
277
project/
278
├── main.py          # Application entry point
279
├── config.py        # Configuration
280
├── lib/            # Libraries
281
│   ├── module1.py
282
│   └── module2.py
283
└── data/           # Data files
284
    ├── config.json
285
    └── assets/
286
```
287

288
### Build Process
289

290
```bash
291
# Use consistent build process
292
mpremote romfs build --output release.romfs --mpy project/
293
mpremote romfs deploy --partition 1 release.romfs
294

295
# Verify deployment
296
mpremote romfs query --partition 1
297
mpremote exec "import sys; print(sys.path)"
298
```
299

300
### Testing
301

302
```bash
303
# Test ROMFS content after deployment
304
mpremote exec "
305
import os
306
print('ROMFS contents:')
307
for item in os.listdir('/romfs1'):
308
    print(f'  {item}')
309
"
310

311
# Test module imports
312
mpremote exec "
313
try:
314
    import main
315
    print('Main module loaded successfully')
316
except ImportError as e:
317
    print(f'Import failed: {e}')
318
"
319
```