You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+27Lines changed: 27 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -208,12 +208,39 @@ If Windows doesn't show this adapter in Device Manager or the Control Panel, the
208
208
209
209
You can also configure this functionality directly within the [Raspberry Pi Imager](https://raspberrypi.com/software) tool (requires version 2.0 or newer). Simply select "USB Gadget mode" in the `Interfaces & Features` customization tab to enable it and make sure you have also configured ssh for remote access in imager.
210
210
211
+
> **Note:** Imager **2.0 is currently in beta** and requires enabling a **custom repository** to show this option. **Therefore, we recommend waiting for a stable release** before trying this out.
212
+
211
213
For command-line users, this feature can also be activated with the `--usb-gadget` flag when using the rpi-imager-cli.
212
214
213
215
```bash
214
216
rpi-imager-cli --usb-gadget
215
217
```
216
218
219
+
> **Image availability:** You’ll need an **RPi OS image with `rpi-usb-gadget` preinstalled**. This will be included in the next image release of Raspberry Pi OS.
220
+
221
+
### Using Cloud-Init
222
+
223
+
If you're working with **fresh Raspberry Pi OS Trixie images**, USB Gadget Mode can also be enabled **via Cloud-Init**, without using Raspberry Pi Imager.
224
+
225
+
> ⚠ **Note:** This requires the **next Raspberry Pi OS image release** with `cloud-init` and `rpi-usb-gadget` preinstalled in the base image. Older images will **not enable gadget mode correctly**, even if the YAML syntax is valid.
226
+
227
+
To enable gadget mode through Cloud-Init:
228
+
229
+
1. Mount the **`boot`** partition of the SD card.
230
+
2. Edit the **`user-data`** file and append:
231
+
232
+
```yaml
233
+
rpi:
234
+
enable_usb_gadget: true
235
+
enable_ssh: true # Optional but recommended for headless access
236
+
```
237
+
238
+
3. *(Optional but strongly recommended)* — In the same file, define a user and SSH key so you can log in immediately over USB without needing peripherals.
239
+
240
+
On **first boot**, Cloud-Init will apply the configuration and switch the USB port into gadget mode automatically — no need to run any commands or enable features manually.
241
+
242
+
> 💡 This method is ideal for **automated provisioning**, scripting, or preparing **multiple SD cards / fleet setups** without using the Imager UI.
243
+
217
244
## Contributions
218
245
219
246
Contributions are welcome! Please submit a pull request or open an issue for feedback and improvements.
0 commit comments