{"id":19360275,"url":"https://github.com/kts-o7/raspberrypi_zero_setup_headless","last_synced_at":"2026-02-13T00:47:46.485Z","repository":{"id":189318966,"uuid":"680464866","full_name":"KTS-o7/RaspberryPi_Zero_Setup_Headless","owner":"KTS-o7","description":"This repository contains the guide to setup a headless Raspberry Pi Zero","archived":false,"fork":false,"pushed_at":"2023-08-19T10:41:42.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-24T12:18:39.630Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KTS-o7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-19T10:27:10.000Z","updated_at":"2023-08-19T10:27:10.000Z","dependencies_parsed_at":"2023-08-19T11:55:58.273Z","dependency_job_id":null,"html_url":"https://github.com/KTS-o7/RaspberryPi_Zero_Setup_Headless","commit_stats":null,"previous_names":["kts-o7/raspberrypi_zero_setup_headless"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KTS-o7/RaspberryPi_Zero_Setup_Headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTS-o7%2FRaspberryPi_Zero_Setup_Headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTS-o7%2FRaspberryPi_Zero_Setup_Headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTS-o7%2FRaspberryPi_Zero_Setup_Headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTS-o7%2FRaspberryPi_Zero_Setup_Headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KTS-o7","download_url":"https://codeload.github.com/KTS-o7/RaspberryPi_Zero_Setup_Headless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTS-o7%2FRaspberryPi_Zero_Setup_Headless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274880368,"owners_count":25367100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-11-10T07:17:36.772Z","updated_at":"2026-02-13T00:47:46.426Z","avatar_url":"https://github.com/KTS-o7.png","language":null,"readme":"# Raspberry Pi Zero  Headless WiFi Setup Using Linux\n\nThe following instructions will ultimately enable your Pi Zero to connect the WiFi to the router during every boot up,\nfor a headless management.\n\n## Appendix\n\n1. [Prerequisite](#1-prerequisite)\n2. [Enabling USB ethernet gadget mode on Pi](#2-enabling-usb-ethernet-gadget-mode-on-pi)\n3. [Things to do once connected to Pi via USB](#3-things-to-do-once-connected-to-pi-via-usb)  \n    3.1. [Enabling Internet access in Raspberry Pi](#31-enabling-internet-access-in-raspberry-pi)  \n    3.2. [SSH into Raspberry Pi](#32-ssh-into-raspberry-pi)  \n    3.3. [Change locale settings](#33-change-locale-settings)  \n    3.4. [Update the OS](#34-update-the-os)\u003cbr\u003e\n    3.5. [ WiFi configuration for auto connecting to the access point](#35-wifi-configuration-for-auto-connecting-to-the-access-point)\n\n## 1. Prerequisite\n\na) Raspberry Pi Zero v1.3  \nb) USB data cable  \nc) Raspbian OS  \nd) A charger  \ne) Manjaro Linux ( mentioned as host OS in this article )  \nf) Raspberry Pi Imager tool  \ng) SD card\n\n## 2. Enabling USB ether net gadget mode on Pi\n\nTo enable the gadget mode, edit `config.txt` and `cmdline.txt` files in\nthe`boot`partition of the SD card.\\\n\nAdd `dtoverlay=dwc2` to `config.txt` and\\\nAdd `modules-load=dwc2,g_ether` after the `rootwait` in `cmdline.txt`\n\n---\n\n**Note**: Leave a space before and after the `add modules-load=dwc2,g_ether` line.\n\n---\n\nMake an empty `ssh` file inside the same partition to enable SSH on boot.\n\nNow connect the USB data cable to the USB port of the Pi and plug it in the PC's  \nUSB port.\n\n## Important !\n\nIn the newer version of Raspbian there is no default `pi` user. We have to create it ourselves.\nFollowing steps will instruct you how to create that default user.\n\n1. Create an empty file called `userconf` in the boot partition.\n\n```shell\ntouch useconf\n```\n\n2. Now copy paste the following into the file\n\n```\npi:$6$/4.VdYgDm7RJ0qM1$FwXCeQgDKkqrOU3RIRuDSKpauAbBvP11msq9X58c8Que2l1Dwq3vdJMgiZlQSbEXGaY5esVHGBNbCxKLVNqZW1\n```\n\nThe above will create a default user named `pi` and password is `raspberry`.\nYou can change it later on.\nWithout this you wont be able to SSH into the raspberry pi zero.\n\n## 3. Things to do once connected to Pi via USB\n\n### 3.1 Enabling Internet access in Raspberry Pi\n\nBefore enabling the internet, make sure that the Pi is connected as a USB gadget.\nCheck `sudo dmesg` to confirm it. Look for lines similar to\n\n```shell\n[  343.853507] usb 1-4: new full-speed USB device number 3 using xhci_hcd\n[  345.088725] usb 1-4: new high-speed USB device number 4 using xhci_hcd\n[  345.243731] usb 1-4: New USB device found, idVendor=0525, idProduct=a4a2, bcdDevice= 5.10\n[  345.243740] usb 1-4: New USB device strings: Mfr=1, Product=2, SerialNumber=0\n[  345.243743] usb 1-4: Product: RNDIS/Ethernet Gadget\n[  345.243746] usb 1-4: Manufacturer: Linux 5.10.17+ with 20980000.usb\n[  345.463183] cdc_subset: probe of 1-4:1.0 failed with error -22\n[  345.464195] cdc_subset 1-4:1.1 usb0: register 'cdc_subset' at usb-0000:03:00.3-4, Linux Device, e2:38:73:2d:01:39\n[  345.464248] usbcore: registered new interface driver cdc_subset\n[  345.464297] cdc_ether: probe of 1-4:1.0 failed with error -16\n[  345.464337] usbcore: registered new interface driver cdc_ether\n[  345.743346] bpfilter: Loaded bpfilter_umh pid 4407\n[  345.743711] Started bpfilter\n```\n\n---\n\n**Note**:  \nGive at least 30 seconds or more before trying the `dmesg`\n\n---\n\nIf the last line says something like\n\n```shell\n[  887.699447] usb 1-4: USB disconnect, device number 4\n[  887.699969] cdc_subset 1-4:1.1 usb0: unregister 'cdc_subset' usb-0000:03:00.3-4, Linux Device\n```\n\nthat means the USB gadget mode was enabled and for some reason it got disconnected.  \nIf you get this, check whether the USB cable was connected to the USB port on the Pi, not on the power port.\n\nOnce confirmed that everything is working fine, goto gnome-network-manager gui and change the USB ethernet's\nIPv4 setting to `shared to other computers`.\n\nDisconnect and then reconnect the USB ethernet in the gui. If that doesn't allow you to ssh into the Pi, you might also need to dis/reconnect the PCI ethernet option.\n\nNow you should be able to SSH into the Internet ready Pi.\n\n### 3.2 SSH into Raspberry Pi\n\n```shell\nssh pi@IP_ADDRESS\n```\n\n```shell\npassword: raspberry\n```\n\nreplace the IP_ADDRESS with the IP Address of the Raspberry Pi zero.\n\n### 3.3 Change locale settings\n\n1. To eliminate perl: LC errors during package installations;\n\n```shell\nsudo dpkg-reconfigure locales\n```\n\nselect the appropriate locale.\nFor example; en_US.UTF-8\n\n2. Set timezone\n\n```shell\nsudo ln -sf /usr/share/timezone/Country/Region /etc/localtime\n```\n\n3. Expand file system\n\nexpand the file system by using\n\n```shell\nsudo raspi-config\n```\n\nNow its time to shutdown the Pi to take effect the changes.\n\nReboot seems to be breaking the USB ether net gadget mode for some reason. Hence you need to shutdown the system.\n\n---\n\n**Note** :\n\nCheck `dmesg` again . If you see some messages similar to below, reboot the host linux OS. Only then re-connect the Pi.\n\n```shell\n[ 1131.255131] ------------[ cut here ]------------\n[ 1131.255137] NETDEV WATCHDOG: enx1a4d1a4fb05e (cdc_ether): transmit queue 0 timed out\n[ 1131.255158] WARNING: CPU: 6 PID: 0 at net/sched/sch_generic.c:467 dev_watchdog+0x24f/0x260\n.\n.\n.\n[ 1131.255535] ---[ end trace 07a143fded20143c ]---\n```\n\nI got this message even after a reboot. In that case disconnect the Pi and check the SD card for any file system errors. Reboot the host OS\nagain and reconnect the Pi.\n\n---\n\nThen follow the instructions on [3.1](#31-enabling-internet-access-in-raspberry-pi).\n\n### 3.4 Update the OS\n\nIt's better to setup the WiFi connection and then upgrade the OS.\nIt can be done by referring to\n\n```shell\nsudo apt update\n```\n\n```shell\nsudo apt upgrade\n```\n\nShutdown and unplug or re plug the Pi. Follow [3.1](#31-enabling-internet-access-in-raspberry-pi).\n\nNow we need to setup the WiFi to automatically connect to the access point during the next reboot.\n\n### 3.5 WiFi configuration for auto connecting to the access point\n\nYou can add the WiFi Configuration using `raspi-config` after SSH-ing via USB.\n\n```shell\narp -a\n```\n\nThis will display the IP address of the USB Ethernet ( usually its of form `10.42.0.x` )\nSSH into the board.\nUse the following command to enter the Raspi configuration\n\n```shell\nsudo raspi-config\n```\n\nThen connect to WiFi via the Connection options by entering the SSID and Password of your network.\n\nOR\n\nAdd these lines to `/etc/wpa_supplicant/wpa_supplicant.conf`;\n\n```shell\ncountry=\"your country code\"\n\nnetwork={\n    scan_ssid=1\n    ssid=\"wifi name\"\n    psk=\"wifi password\"\n}\n```\n\nNow shutdown the Pi. Connect the WiFi adapter and power cable then turn it on.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkts-o7%2Fraspberrypi_zero_setup_headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkts-o7%2Fraspberrypi_zero_setup_headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkts-o7%2Fraspberrypi_zero_setup_headless/lists"}