Apologies if this is not the correct place to post. I was hoping to update this information into the Wiki here:
However either I don't have the permissions to do that, or I can't figure out how to in this interface.
I am a 30 year IT veteran with a focus on sys admin work and had some struggles setting up OctoPi. While it was my first project ever working with a Pi, I do have some experience with Unix/Linux and while I was able to arrive at a solution myself it cost me a couple of hours. I'm hoping to save others the time.
There is something very broken in OctoPi's WiFi configuration if you install it according to most of the published documentation (including on this site: OctoPrint.org - Download & Setup OctoPrint). Luckily, even though it is broken, most users won't detect it. Initially I thought this issue would affect many more users, but it turns out that I have a bit of an edge case that caused a perfect storm. Nonetheless, it doesn't discredit the fact that following the documentation can lead to problems and may be masking an issue on some user's setups.
The primary recommended method of installation (including the link above) is to use the Raspberry Pi Imager application. The directions state that when imaging OctoPi you set the Advanced Options (Ctrl+Shift+X) to set your WiFi setting:
Configure your wifi options : Set your SSID, password and WiFi country
Herein lies the problem. To explain, we need to delve into a bit of how WiFi is handled on OctoPi (1.0.0, the current "Stable" release at time of writing):
OctoPi uses the wpa_supplicant to setup WiFi. This is configured via the /etc/wpa_supplicant/wpa_supplicant.conf file.
If you were to image OctoPi without Imager (using another way to transfer the image file), or you chose not to apply the Advanced Settings Customizations (which you probably wouldn't, since the tutorials tell you to!), you would find that no wpa_supplicant.conf file exists on your system. Or rather, I should say, wpa_supplicant.conf is actually just linked (symlinked) to /boot//boot/octopi-wpa-supplicant.txt.
There are many posts out there about editing the /boot/octopi-wpa-supplicant.txt, including the excellent Wiki post I mention above. However none of them really explain how useless this file is if you have followed the tutorial on this very site to setup OctoPi! Because, if you do choose to apply the Advanced Settings configured, it will break the symlink to the .txt file and it will not be used at all for your WiFi configuration as wpa_supplicant has no way to know about it.
Let me take a moment to stress here I am discussing all the latest software as of 1/7/2025. This includes using the Imager 1.8.5 and choosing to install OctoPi 1.0.0
I suspect that many, many people have followed the instructions and used the Imager and applied the Advanced Settings to configure their WiFi and have had no issue at all. So "why?" you might ask am I going on about this? Well, for starters, just because it works doesn't mean it is working the way you think it is (or expect it to). Again, using the Imager basically destroys the symlink and instead writes an actual copy of the /etc/wpa_supplicant/wpa_supplicant.conf file. That file will look something like this:
update_config=1
ctrl_interface=/var/run/wpa_supplicant
country=GB
network={
scan_ssid=1
ssid="MySSID"
psk="encryptedpassword"
}
Looks pretty straightforward, right? Well unfortunately the problem is with the "country" line. Because it will say country=GB regardless of what you set in the Advanced Settings in the Imager. Personally, I set the country as "US", on no less than half a dozen runs of the 1.8.5 Imager tool, and on every occasion it properly populated my network section, but left me with country=GB!
So this end result is actually a compounded issue.
- Your country is not being properly set (assuming you aren't in GB).
- Your
/boot//boot/octopi-wpa-supplicant.txtwill never be used because the symlink is overwritten with thewpa_supplicant.conffile.
However, you do still have a valid wpa_supplicant.conf file with your network info in it. If you are lucky your WiFi will just work. However you may be (like me), one of the unlucky ones. If you meet the below criteria:
- You are not actually in GB (or more specifically using WiFi equipment configured for GB bands).
- You are trying to join a 5 GHz network.
- Your 5 GHz network does not share it's SSID with your 2.4 GHz network.
- You are using a 5 GHz control band above 140.
In my case, I am in the US. I was trying to join my 5 GHz network ("home-5.0") which is different than my 2.4 GHz network (*home-2.4"). I keep them separate because I have found some older clients have issues with combined networks. Additionally, due to congestion in my area, I had manually configured my router to operate on the 149 control channel for 5 GHz.
Because (presumably) the 149 control channel in the US is different than the 149 control channel in GB, the WiFi, as configured through wpa_supplicant failed to even detect my 5 GHz network. I didn't test every single channel, but it appears that channels 140 and under might be close enough between US and GB that they can still be detected even if GB is still set (results will vary in your other countries).
I suspect only a small group of people are manually setting their 5 GHz control channel. Even fewer may be setting it above 140 (just based on randomization of congestion patterns). Additionally, it is quite possible that results may vary with your Pi and your router and how their WiFi chipsets (and drivers) interact. I am using a 3B+ with an ASUS router which uses a Broadcom chipset.
If you have a different Pi, or a different router perhaps you won't see an issue above channel 140? Or perhaps you will see it with all channels?
It is also quite possible that if, like #3 above, both your 2.4 and 5 GHz networks share the same SSID, you might believe you are on your 5 GHz control channel. However, if it cannot be detected, you might actually have fallen back to only the 2.4 GHz one.
It would seem, however, that if you follow the published instructions to install OctoPi you will break the symlink to the octopi-wpa-supplicant.txt file. This makes all troubleshooting with the file absolutely pointless. So, before you go following all the advice out there about fixing up octopi-wpa-supplicant.txt, make sure you check/restore the symlink to it from /etc/wpa_supplicant/wpa_supplicant.conf.
It is also worth noting here that if you ever use raspi-config to change your WiFi settings (including Country) it will also overwrite the symlink with its own copy of wpa_supplicant.conf, rendering anything you had set in octopi-wpa-supplicant.txt useless.
I hope that the powers that be will provide a bit of visibility into this issue. Again, while this "perfect storm" of issues may only end up affecting a small number of users, it doesn't diminish the fact that many other users configurations are actually broken "as designed" and are only working based on luck (i.e. they don't fit any of the 4 criteria outlined above).
Hope this helps someone else.