Skip to content

Commit 05ff094

Browse files
committed
docs(README): Update Imager availability and add cloud-init section
Signed-off-by: paulober <[email protected]>
1 parent 479cca7 commit 05ff094

File tree

1 file changed

+27
-0
lines changed

1 file changed

+27
-0
lines changed

README.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,12 +208,39 @@ If Windows doesn't show this adapter in Device Manager or the Control Panel, the
208208
209209
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.
210210
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+
211213
For command-line users, this feature can also be activated with the `--usb-gadget` flag when using the rpi-imager-cli.
212214
213215
```bash
214216
rpi-imager-cli --usb-gadget
215217
```
216218

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+
217244
## Contributions
218245
219246
Contributions are welcome! Please submit a pull request or open an issue for feedback and improvements.

0 commit comments

Comments
 (0)