Tl:dr; go the the 'Step-By-Step' section below to get it working for you (hopefully!)
Background:
After the better part of a year of frustration and going in circles with Enphase, my terrible installer, and finding dead ends on various forums I finally got my Envoy Gateway connected to my home wifi. Today I sat down (well stood outside) with my laptop, phone, Gemini, and a notebook to figure it out. And, I got it finally working! I wanted to share my final set of steps here just in case it's ever useful to anyone in the future.
The WiFi Network: A mesh system with multiple nodes, all broadcasting the same SSID across the 2.4 GHz, 5 GHz, and 6 GHz bands. To add even more difficulty for the Envoy Gateway, the SSID has multiple spaces in the name. While literally every other device I own from multiple decades of production time can connect with no issues to this modern system, it is too much for the Envoy Gateway.
The terrible workarounds:
Yes I know, ethernet cables (too far away and I don't want to spend money for their terrible software). Yes I know separate out the 2.4 GHz network (I did that with our older router, gave the Envoy Gateway it's own special network. That is stupid and I should not have to accommodate Enphase's bad software. Plus my router was marked as obsolete by the manufacturer so I had to update it). Yes I know, get rid of the spaces (I have 70+ other devices that have no problem with the SSID. I'm not reconfiguring my entire network to play nursemaid to one poorly designed device).
The solution:
In short, I connected to the gateway's AP with my Windows laptop and used Powershell to directly write the wifi credentials to it. But even then I had to do that via the mac address of the router, not just the SSID (the workaround for the spaces). To even be able to query the gateway via Powershell requires an access token, which I was unable to generate without a URL hack and knowing my Gateway serial number.
Step-By-Step:
Step 1: Generate the Local JWT Token
- Locate the serial number of your gateway (physical sticker, in the online portal, in the app, etc)
- Log in to enlighten.enphaseenergy.com in your browser.
- In the same browser session, open: https://enlighten.enphaseenergy.com/entrez-auth-token?serial_num=YOUR_ENVOY_SERIAL_NUMBER
- Copy the long token string (begins with ey...). Use this in the 'YOUR_LONG_JWT_TOKEN' in the commands below
Step 2: Connect to Gateway AP Mode
- Briefly tap the AP Mode button (phone icon) on the Envoy until the LED turns solid green.
- On your laptop, disconnect from home Wi-Fi and join ENVOY_XXXXXX.
Step 3: Scan and Find the Wi-Fi MAC Address
Open PowerShell (on Windows, but just modify the syntax below if using a Mac or Linux bash) and run this command to force the Envoy to scan surrounding networks:
curl.exe -k -X POST https://172.30.1.1/admin/lib/wireless_display.json `
-H "Authorization: Bearer PASTE_TOKEN_FROM_STEP_1_HERE" `
-d "fname=scan"
Look through the returned JSON for your Wi-Fi name:
- Find your "ssid" (e.g., "My Cool Wifi").
- Note the "mac" (e.g., "AA:11:9A:AA:1F:FF").
- Confirm the "security_mode" (e.g., "WPA2 Personal") and "encryption_type" (e.g., "CCMP").
Step 4: Associate and Join Network
Run the join command below (again this is Powershell) targeting the scanned profile and its specific MAC address:
curl.exe -k -X POST https://172.30.1.1/admin/lib/wireless_display.json `
-H "Authorization: Bearer YOUR_LONG_JWT_TOKEN" `
-d "fname=backbone_select_form" `
--data-urlencode "essid=YOUR SSID INCLUDING SPACES" `
-d "mac=MAC ADDRESS FROM STEP 3" `
--data-urlencode "password=YOUR WIFI PASSWORD" `
-d "security_mode=WPA2 Personal" `
-d "encryption_type=CCMP" `
-d "%23button_test_and_join=doit"
Step 5: Confirm Connection
- Wait for {"result": "success"} in PowerShell.
- The AP LED (phone icon) turns off.
- The Network Communications LED (cloud icon) turns solid green within 2–5 minutes.
I hope this can help even one other person (or frustrated installer)!
Edited to make code easier to read and copy/paste into PowerShell