{"id":35125467,"url":"https://github.com/luxc1101/raspi-usb-sim","last_synced_at":"2026-02-08T16:09:25.297Z","repository":{"id":303687424,"uuid":"1015639311","full_name":"luxc1101/raspi-usb-sim","owner":"luxc1101","description":"Rpi USB Device Simulator (Raspberry Pi zero w) ","archived":false,"fork":false,"pushed_at":"2025-12-28T22:30:25.000Z","size":4931,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-30T04:31:19.142Z","etag":null,"topics":["cdc","ecm","hid","msc","mtp","ncm","productid","pyqt5","raspberry-pi","simulator","usb-devices","vendorid"],"latest_commit_sha":null,"homepage":"https://github.com/luxc1101/raspi-usb-sim/releases","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luxc1101.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-07T20:11:16.000Z","updated_at":"2025-12-27T21:00:17.000Z","dependencies_parsed_at":"2025-12-27T23:07:05.253Z","dependency_job_id":null,"html_url":"https://github.com/luxc1101/raspi-usb-sim","commit_stats":null,"previous_names":["luxc1101/raspi-usb-sim"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/luxc1101/raspi-usb-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxc1101%2Fraspi-usb-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxc1101%2Fraspi-usb-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxc1101%2Fraspi-usb-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxc1101%2Fraspi-usb-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luxc1101","download_url":"https://codeload.github.com/luxc1101/raspi-usb-sim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxc1101%2Fraspi-usb-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29236234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T14:18:14.570Z","status":"ssl_error","status_checked_at":"2026-02-08T14:18:14.071Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdc","ecm","hid","msc","mtp","ncm","productid","pyqt5","raspberry-pi","simulator","usb-devices","vendorid"],"created_at":"2025-12-28T02:31:36.859Z","updated_at":"2026-02-08T16:09:25.293Z","avatar_url":"https://github.com/luxc1101.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[TOC]\n\n\n\u003c!-- \n\n[![download][mdversion-button]][md-pypi]\n\n[mdversion-button]: downlaod\n[md-pypi]: https://pypi.org/project/Markdown/ --\u003e\n\n# USB Simulator\n\n\u003cimg src=\"https://content.instructables.com/ORIG/F60/5H8G/KNHGQNWP/F605H8GKNHGQNWP.png?auto=webp\u0026frame=1\u0026width=810\u0026fit=bounds\u0026md=38489d1a10177d77d78f77287ad3bd0a\" width=\"100\" \u003e\n\nThe idea aims to reduice the amount of work for USB sticks plug in \u0026 out during the testing. Raspberry Pi Zero can emulate USB devices: \n - MSC\n - HID\n - ECM\n - CDC\n - NCM\n - MTP\n - UAC\n \n The tool can also automate tests via SSH communication. The PID/VID of the emulated USB devices can be easily adjusted as well.\n\n## Big Picture\n\n\u003cimg src=\"image/BigPic.png\" width=\"350\"\u003e\n\n## Prerequisites\n\n| Hardware                   | Software                                                       |\n| -------------              | -------------                                                  |\n| RaspberryPi zero W         | [Raspberry Pi Imanger (download)](https://www.raspberrypi.com/software/)  |\n| USB Mico-B Cable (OTG)     | [The latest released USBTool](https://github.com/luxc1101/raspi-usb-sim/releases) |\n| USB Mico-B Cable (Power)   |                                                                |\n| micoSD Card (e.g. 128 GB)  |                                                                |\n| micoSD Card Reader         |                                                                |\n| WiFi with known SSID and Password (router or 2.4 GHz Mobile Hotspot)             |                                                                |\n| USB WiFi adapter |                                                                |\n\n\u003e **NOTE**:  \n\u003e if the PC is unable to receive WiFi, then USB WiFi adapter is needed, once USB WiFi adapter is plunged in, to connect WiFi through adapter should be available\n\n## Quick Tutorial\n\n### Operation System Installation\n\n#### SD card format\n\n- right click → format as FAT32\n- or in Raspberry Pi Imager app format SD card\n\n#### [Rpi Imager (download)](https://www.raspberrypi.com/software/)\n\n- Raspberry Pi Modell: Raspberry Pi Zero\n- Select OS: \n  - `Raspberry Pi OS (Legacy, 32-bit) Lite` (**bullseye**) (old OS)\n  - `Raspberry Pi OS (Legacy, 32-bit) Lite` (**bookworm**) (recommand)\n  - `Raspberry Pi OS (32-bit) Lite` (**trixie**) (latest OS, ssh connection somehow slow)\n- Choose SD card\n- Setting option\n  - Hostname: rpi\u003c?\u003e.local # e.g. rpi0.local\n  - Username: pi\n  - PW: pass\n  - WiFi:\n    - SSID: \u003cWiFi network name (ssid)\u003e\n    - PW: \u003cpassword of ssid\u003e\n    - country: DE\n  - Timezone: Europe/Berlin\n  - Keyboard layout: de\n  - SSH activate\n\n### Download USBTool Software\n\nfind the latest released version from [Releases · Raspi-USB-Simulator · Github](https://github.com/luxc1101/raspi-usb-sim/releases), click packages usbtool-vx.x.x to download.\n\nunzip the downloaded packages, the downloaded release folder structure:\n\u003cdetails\u003e\n  \u003csummary\u003efolder structure (./usb-tool_vx.x.x/dist/)\u003c/summary\u003e\n  \n  ```\n  .\n  │   USBSimulator.exe\n  │\n  ├───config\n  │       Config.json\n  │       device_proj.json\n  │\n  ├───usbtool_install\n  │   │   device_proj.json\n  │   │   fswd.service\n  │   │   fswd.sh\n  │   │   install.sh\n  │   │   kybd-descriptor.bin\n  │   │   mount_app.py\n  │   │   mount_robot.py\n  │   │   requirements.txt\n  │   │   umtprd\n  │   │   umtprd.conf\n  │   │\n  │   └───src\n  │           acm_device.py\n  │           a_device.py\n  │           a_validator.py\n  │           device_data.py\n  │           device_dictcreator.py\n  │           ecm_device.py\n  │           fscreator.py\n  │           hid_device.py\n  │           msc_device.py\n  │           mtp_device.py\n  │           ncm_device.py\n  │           rndis_device.py\n  │           samba_service.py\n  │           stdout_writer.py\n  │           uac_devcie.py\n  │           usb_peripheral.py\n  │           watchdog_service.py\n  │\n  └───wificonfig\n          ssh\n          wpa_supplicant.conf\n  ```\n\n\u003c/details\u003e\n\n### Connections\n\nBefore starting, it is important to know that the Raspberry Pi and the test PC need to be on the same wireless network. Therefore, you must first secure that PC is able to connect to the desired 2.4 GHz WiFi network wirelessly.\n\n#### Preparing the Rpi: Editing the WiFi Configuration File\n\u003e\n\u003e **NOTE**:  \n\u003eOnce you have already configured the WiFi SSID and PSK in step [Operation System Installation](#operation-system-installation) and the WiFi is not changed (SSID, PSK) and still available, you can skip this step.\n\n\u003cdetails\u003e\n  \u003csummary\u003eChange WiFi for old rpi OS e.g. bullseye\u003c/summary\u003e\n  \n  Only if WiFi network was changed, `ssh` (without file typ) and `wpa_supplicant.conf` (with new WiFi ssid and password) should write into bootfs partition of SD card.\n\n  \u003cdetails\u003e\n    \u003csummary\u003ewpa_supplicant.conf\u003c/summary\u003e\n  \n    # Datei wpa_supplicant.conf in der Boot-Partition (Raspbian Stretch)\n    country=DE\n    update_config=1\n    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev\n    network={\n     key_mgmt=WPA-PSK\n     ssid=\"\u003cSSID\u003e\u003e\"\n     psk=\"\u003cpassword\u003e\"\n    }\n\n  \u003c/details\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eChange WiFi for new rpi OS e.g. bookworm/trixie\u003c/summary\u003e\n  \n  scan availabel wifi list\n\n  ```shell\n  sudo iwlist scan | grep \"\u003cSSID\u003e\"\n  ```\n  list availbale WiFi metworks\n  \n  ```shell\n  nmcli dev wifi list\n  ```\n  Connect to new WiFi\n  \n  ```shell\n  sudo nmcli dev wifi connect \"YourWiFiName\" password \"YourPassword\"\n  ```\n\u003c/details\u003e\n  \n#### Preparing the Rpi: Mounting and Connections\n\nOnce the microSD card has been updated, remove it from the microSD card reader and mount it on the Rpi.\n\nThen plugin USB Micro-B cable (Power) and USB Micro-B cable (OTG). Now, the tester is instructed to make the following connections.\n\n\u003cimg src=\"image/RaspiZeroW.png\" width=\"250\"\u003e\n\u003cimg src=\"image/RaspiZeroWAssembly.png\" width=\"250\"\u003e\n\n#### Preparing the SSH Connection: IP, Port, SSID and Password\n\u003e\n\u003e **NOTE**:  \n\u003eit could take few mins at FIRST time until Rpi connected to the WiFi.\n\nWiFi sources may be different, such as routers, hotspots, etc. Raspberry IP address could be check in different ways:\n\n##### Router\n\u003e\n\u003e **Hint**:  \n\u003e if WiFi network was changed, ssh (without file typ) and wpa_supplicant.conf (with new WiFi ssid and password) should be firstly written into bootfs partition of micoSD card.\n\u003cdetails\u003e\n\n- solution 1 (recommend)\n  - connect local machine to WiFi via USB WiFi adapter, e.g. WiFi SSID: `AMB-StreamWLAN`, PW: *********\n  - typing router ip address http://xxx.xxx.xxx.xxx/ on browser, check IP-Address of the conencted device with name e.g. `raspberrypi`\n\n      \u003cimg src=\"image/RouterIPList.png\" width=\"500\"\u003e\n\n- solution 2\n  - Using Putty to connect to Rpi to allow access to the Rpi via ssh and save login info as session\n    - Hostname: e.g. `raspberrypi.local`→[enter]\n    - Login as: `pi`\n    - PW: `raspberry`\n\n        ```bash\n        hostname -I # 192.168.188.xx\n        ```\n\n- solution 3\n  - open a terminal\n\n      ```powershell\n      ping \u003cHostname\u003e # ping raspberrypi.local\n      ```\n\n      expected output\n\n      ```\n      Ping wird ausgeführt für raspberrypi.local [192.168.188.38] mit 32 Bytes Daten:\n      Antwort von 192.168.188.38: Bytes=32 Zeit=22ms TTL=64\n      ...\n      ```\n\u003c/details\u003e\n\n##### Mobile Hotspot\n\u003e\n\u003e **Hint**:  \n\u003e if WiFi network was changed, ssh (without file typ) and wpa_supplicant.conf (with new WiFi ssid and password) should firstly be written into bootfs partition of micoSD card.\n\u003cdetails\u003e\n\n- activate Hotspot with Band **2.4 GHz** through mobile hotspot device (e.g. Samsung Galaxy S21)\n- make sure that PC and Rpi device is connected to Android Phone Hotspot\n  \n    \u003cimg src=\"image/Mobile_hotspot.jpg\" width=\"100\"\u003e\n- check rapberry pi device IP address from Android Phone\n\n    \u003cimg src=\"image/IP_in_Phone.jpg\" width=\"100\"\u003e\n\nonce WiFi connection in Rpi is establish, connect PC to the same WiFi, and go ping Rpi device is to find out if a device is reachable at a particular IP address:\n\nopen a terminal (PC or VM)\n\n```powershell\nping \u003craspi ip address\u003e \n```\n\nexpected output\n\n```Confluence\nPing wird ausgeführt für 192.168.209.31 mit 32 Bytes Daten:\nAntwort von 192.168.209.31: Bytes=32 Zeit=241ms TTL=64\nAntwort von 192.168.209.31: Bytes=32 Zeit=12ms TTL=64\n...\n```\n\u003c/details\u003e\n\n### SSHClient Creation\n\nWith the GUI `USBSimulator.exe` launched, click on the `SSH Connect` button and new menu (Raspi SSH Connection) will pop up asking you for details such as IP Address, Port Number, Username, and SSID, etc., as shown below:\n\n\u003cimg src=\"image/SSHConnectionDialog.png\" width=\"250\"\u003e\n\nNow input the IP address in the SSH connect sub menu, select the SSID and  input its corresponding password and hit Connect.\n\n\u003cimg src=\"image/SSHClient.png\" width=\"250\"\u003e\n\nNow a SSHClient is via USB Tool created, you can try to type and sent command through command line editor, e.g. pwd, it should work.\n\n\u003cimg src=\"image/SSHPwd.png\" width=\"250\"\u003e\n\n### Configuration\n\n#### Preparing package installation and configuration for Rpi\n\nclick button `Install USB Gadget`, installation dialog will pop up, select folder `./usbtool_install` from browser\n\n\u003cimg src=\"image/USBSwUpload.png\" width=\"250\"\u003e\n\nclick button `install`, start the installation and wait until the progress is complete\n\n\u003cimg src=\"image/USBSwInstall.png\" width=\"250\"\u003e\n\nIf no errors occur during the installation process, the Rpi device will automatically reboot.\n\u003cdetails\u003e\n\n  ```\n  apt-get update and upgrade\n  Get:1 http://raspbian.raspberrypi.org/raspbian bullseye InRelease [15.0 kB]\n  Get:2 http://archive.raspberrypi.org/debian bullseye InRelease [39.0 kB]\n  Get:3 http://raspbian.raspberrypi.org/raspbian bullseye/main armhf Packages [13.2 MB]\n  Get:4 http://archive.raspberrypi.org/debian bullseye/main armhf Packages [327 kB]\n  Fetched 13.6 MB in 25s (542 kB/s)\n  Reading package lists...\n  Reading package lists...\n  Building dependency tree...\n  Reading state information...\n  ...\n  USBTool enabled. Rebooting system now...\n  ```\n\u003c/details\u003e\n\n### GUI and Elements\n\n\u003cdetails\u003e\n\nUI Design Elements:\n\n\u003cimg src=\"image/UI_Explain.jpg\" width=\"1000\"\u003e\n\nState Machine:\n\n\u003cimg src=\"image/State_Machine.png\" width=\"800\"\u003e\n\n#### Menubar\n\n- **Calls**\n  - **SSH Connect**: connect WiFi and build SSHClient connection with correct login parameters\n  - **SSH Disconnect**: disconnect SSHClient\n  - **Mount**: mount device.\n  - **Eject**: eject device.\n  \u003c!-- - **Remote Folder**: open remote folder (NAS) of mounted filesystem only if samba service is enable. It will provide a possibility to modify the files in remote folder. The modifications will also be synchronised at the raspi mount point. --\u003e\n  - **Clear**: clear the trace window up.\n  - **Install USB Gadget**: USB tool installation and configuration for Rpi\n  \u003c!-- - **Delete**: delete filesystem image. --\u003e\n  - **Help**: quick user guaid.\n- **Project**\n  - MIB3 (Done)\n  - GEI (Progressing)\n  - User (Progressing)\n  \n#### Device Tab\n\n- **Mass Storage Class (MSC)**: mount MSC device with different filesystems, it is able to create and delete filesystem and open its shared folder\n- **Ethernet Adapter (ECM)**: mount ECM devices with specific VID and PID\n- **Human Interface Device (HID)**: mount HID devices with specific VID and PID\n- **Communication Device Class (CDC)**: mount CDC devices with specific VID and PID\n- **Network Control Model (NCM)**: mount NCM devices with specific VID and PID\n- **Media Transfer Protocal (MTP)**: mount MTP devices with specific VID and PID\n- **USB Audio Class (UAC)**: mount UAC devices with specific VID and PIP (stereo, 48kHz, 16bits) \n\n#### Trace\n\n- **Trace Window**: (read only) shows commands and the standard output and error, in case standard input as well\n- **Command LineEdit**: send command to remote Rpi device via SSHClient\n\n#### Statusbar\n\n- QLed will indicate the SSHClient connection state. \u003cspan style=\"color:lime\"\u003eGreen\u003c/span\u003e: SSH Connected \u003cspan style=\"color:gray\"\u003eGray\u003c/span\u003e: SSH Disconnected\n\n\u003c/details\u003e\n\n## Checklist\n\n- [x] WiFi with known SSID and Passport\n- [x] microSD card within correct OS, needed scripts and installed packages\n- [x] Rpi, USB micro-B to USB A Cabel x2, USB WiFi adapter (if needed)\n- [x] WiFi for rpi ssh connection is succefully configured\n- [x] power Rpi up and connect Rpi to DUT, USB WiFi adapter is connected to PC (if needed)\n- [x] WiFi \u0026 SSH connection is establish\n- [x] `config` folder and `USBSimulator.exe` should be in **SAME** folder or root path\n\n## Troubleshooting\n- Unclean file system\n  - if NTFS file system is removed from windows system but without safely removing before, then at next time after mounting the same NTFS filesystem those warnings will be shown on trace usbtool trace window.\n    ```text\n    WARN: The disk contains an unclean file system (0, 0).\n    WARN: The file system wasn't safely closed on Windows. Fixing.\n    ```\n\n- Shared folder will not be able to access xxx.xxx.xxx.xxx\n  - [AllowInsecureGuestAuth | Microsoft Learn](https://learn.microsoft.com/de-de/windows-hardware/customize/desktop/unattend/microsoft-windows-workstationservice-allowinsecureguestauth)\n\n    | Value           | Info           |\n    | -------------   | -------------  |\n    | 0 | SMB client rejects insecure guest logons.This is the default, and recommended value |\n    | 1 | SMB client allows insecure guest logons. |\n  - win + R → regedit → HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\LanmanWorkstation\\Parameters\n    \n    \"AllowInsecureGuestAuth\"=dword:00000001\n    \n    \u003cimg src=\"image/AllowInsecureGuestAuth.png\" width=\"400\"\u003e\n  \n  - If there is no AllowInsecureGuestAuth file, please create AllowInsecureGuestAuth and assign value as a DWORD\n\n- [BUG: Wi-Fi config via Raspberry Pi Imager failed](https://github.com/raspberrypi/rpi-imager/issues/1067) \n  - resolved in Raspberry Pi Imager version 1.9.5\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluxc1101%2Fraspi-usb-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluxc1101%2Fraspi-usb-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluxc1101%2Fraspi-usb-sim/lists"}