USB Gadget
These commands are available three ways — in the FREE-WILi GUI app, in a serial terminal, and on the device itself. See Connecting it to a computer for how to reach them.
Start Gadget
Brings up the USB HID gadget on the FreeWili's second USB connector. The host PC then sees a composite keyboard/mouse/gamepad device that this firmware can type on.
Starting the gadget costs three things for as long as it stays up:
- SubGHz is locked out. The gadget and the CC1101 radio share PIO block 2 and cannot both have it, so Start is refused outright while the SubGHz app is open or the radio is mid-operation. Close it and try again.
- The display's screen becomes the gadget status screen and the menu tree is unreachable on the glass. That is deliberate, not a fault: the framebuffer memory is where the running USB code lives while the gadget is attached. CANCEL on the device stops the gadget and gives the screen back.
- LoRa keeps working throughout; only the sub-GHz CC1101 path is affected.
Success here means the request was ACCEPTED, not that the host enumerated the device. Run Status to see which of those actually happened - it distinguishes 'attached, no host' (a cable or host-side problem) from 'enumerated' (working).
Starting is also safe from this console while the device is showing any screen at all, because it does not go through the menu tree.
How to use it — press s.
Stop Gadget
Takes the USB HID gadget down. The host sees a clean detach, the display returns to the normal menus, and SubGHz becomes available again without a reboot.
The stop is LATCHED rather than immediate. If a typing script is running when you ask, the gadget stays attached until that script has finished - stopping mid-transfer would leave the host with a half-sent report and, worse, modifier keys held down. Status reports 'stopping' during that window.
Success here means the stop was accepted. Run Status afterwards to confirm it reached 'stopped'; only then has the SubGHz lockout actually cleared.
The same thing can be done on the device itself: while the gadget is attached the display shows the gadget screen, and CANCEL there stops it. That is the only button the device honours in that state.
How to use it — press t.
niceusb Status
Asks the display for the gadget's live state and prints it here. The report is taken as a single snapshot, so the state and the enumeration flag it prints always belong to the same instant.
The state word is one of:
stopped - nothing running, SubGHz is free starting (claiming PIO2) - the request was accepted; the USB stack is not up yet starting (stack up, D+ low) - the stack is up and the pull-up is about to be raised attached, no host - the device is presenting itself but nothing enumerated it. Suspect the cable, the port, or the host. enumerated - the host has accepted the device. This is the working state. stopping - teardown in flight; SubGHz is still locked out
'attached, no host' and 'enumerated' are never collapsed into one word, because they have completely different causes and completely different fixes.
The second line reports the last script error as a line number and message, or 'none'. It is not cleared by stopping the gadget, so it still names the failure after the fact.
How to use it — press i.
Run Test Script
Runs the compiled-in proof script on the host PC. It types 'FreeWili niceusb OK', presses Enter, waits three seconds, types 'still alive' and presses Enter again.
THIS TYPES INTO WHATEVER WINDOW HAS FOCUS on the host. Put the cursor somewhere harmless - a text editor or an empty document - before running it. The text is deliberately inert: plain words only, no shell metacharacters and no GUI/CTRL/ALT combinations.
Each part of the script proves something separate. The multi-character typing proves the IN endpoint is being re-armed between reports; the shifted characters prove modifiers work; and the three-second delay proves the watchdog beat inside the USB pump holds while a script blocks the display's second core.
Refused if the gadget is not attached (start it first) or if a script is already running. The command returns as soon as the script is queued - the typing happens on the display over the next few seconds.
How to use it — press r.
niceusb Script
SD path of the wusb script Start Gadget loads, or empty for the gadget's built-in personality.
How to use it — press c.
What you enter — value.
niceusb Force VID/PID
Enable to make Start Gadget present the VID/PID below instead of the script's own or the built-in personality's.
How to use it — press o.
niceusb VID
Forced USB vendor ID, used only while niceusb Force VID/PID is on.
How to use it — press v.
What you enter — value.
niceusb PID
Forced USB product ID, used only while niceusb Force VID/PID is on.
How to use it — press p.
What you enter — value.
See also: USB Gadget Scripts panel — the on-screen panel for this.