How WiFi QR Codes Actually Work: Technical Guide 2026

Most WiFi QR codes that fail to auto-connect fail for the same three reasons: the security type field is missing, the password contains a special character that was not escaped, or the client device belongs to the small pool of hardware that never implemented the informal WIFI URI standard. This guide covers the format byte by byte, the parser differences between iOS 18 and Android 15, and how to encode enterprise networks that most consumer generators quietly skip.

Quick answer

A WiFi QR code is a plain text payload using the format WIFI:T:WPA;S:NetworkName;P:password;H:false;; that gets rendered into a standard QR Code (ISO/IEC 18004). Your phone camera reads the text, matches the WIFI: prefix, and hands the parsed credentials to the operating system's WiFi subsystem. Apple documented their parser in NEHotspotConfiguration, Google Lens and the Android camera share a parser based on ZXing, and both support WPA2 and open networks out of the box.

Table of contents

• Origin of the WIFI URI format
• The five fields, byte by byte
• Escaping rules and character edge cases
• Enterprise WPA2-EAP payloads
• iOS 18 behavior (NEHotspotHelper)
• Android 15 behavior (Google Lens, Samsung, Pixel)
• Working code: JavaScript, Python, curl
• Print contrast and DPI for reliable scans
• Common reasons scans fail
• FAQ

Origin of the WIFI URI format

The WIFI URI scheme was not created by an RFC. It started inside Java ME phones around 2010, then appeared as an informal draft (draft-harkins-wifi-qr-00) that never advanced, and finally got adopted almost verbatim by Apple and Google because the market had already standardized on it. The Wi-Fi Alliance later referenced the format in their Easy Connect whitepaper published in 2019 and updated in 2024, giving it a semi-official status.

There is no formal parser spec. Each vendor implements the format based on the ZXing reference code from 2012, which explains why all major implementations agree on the five-field shape but disagree on escaping corner cases.

The five fields, byte by byte

A WiFi QR payload looks like this:

WIFI:T:WPA;S:HomeNet;P:Passw0rd;H:false;;

The payload is a single line of ASCII. Every token is a letter, a colon, a value, and a semicolon. Two semicolons at the end close the record.

Extra fields exist for enterprise networks: A for anonymous identity, I for identity, PH2 for phase-two auth, and R for CA realm. Consumer generators typically omit these because iOS and stock Android skip them on read.

Why T cannot be blank

A surprising number of scan failures happen because the T field is empty. When iOS reads WIFI:T:;S:HomeNet;P:secret;;, it treats the security type as nopass and tries to join as an open network, which fails because the AP actually requires WPA2. Always set T explicitly, even for hidden networks.

Escaping rules and character edge cases

Five characters are reserved and must be prefixed with a backslash inside the S or P fields: \, ;, ,, :, and ". Here is a network name with a semicolon in it:

WIFI:T:WPA;S:Joe\;s Cafe;P:latte2026;H:false;;

Without the escape, the parser terminates the S field at the first semicolon and reads s Cafe;P:latte2026 as a nonsense security token.

Unicode works in both fields on iOS 13 and newer and on Android 10 and newer. Older Android versions (9 and below) silently strip non-ASCII characters on some Samsung devices, which is one of the most reported bugs on the QRCrack support tracker.

Hex-mode SSIDs are supported by wrapping the value in double quotes: S:"68656c6c6f" parses as the ASCII string hello. This is used for SSIDs that contain null bytes or that the network administrator generated from a hash.

Enterprise WPA2-EAP payloads

For university and corporate networks running RADIUS, the full payload looks like this:

WIFI:T:WPA2-EAP;S:eduroam;E:PEAP;PH2:MSCHAPV2;I:alice@uni.edu;P:SecretPass;H:false;;

iOS supports this format from iOS 14 onward via the NEHotspotConfiguration API, but the user still sees a manual confirmation dialog for the CA certificate. Android supports it inconsistently: Pixel phones accept it from Android 11, Samsung added support in One UI 5.0 (Android 13), and most custom Chinese ROMs (MIUI, ColorOS) ignore the EAP tokens as of 2026.

If you are deploying eduroam across a large campus, the official recommendation from the Wi-Fi Alliance Easy Connect guide is to use a provisioning profile (iOS .mobileconfig or Android XML) distributed via a QR code that links to the profile URL, rather than encoding the credentials directly.

iOS 18 behavior

When the iOS 18 camera app detects a QR payload starting with WIFI:, it shows a yellow banner reading "Join [SSID]". Tapping the banner calls -[NEHotspotConfigurationManager applyConfiguration:] internally, which adds the network to the known list for 48 hours by default. After 48 hours of no association, iOS removes the profile automatically unless the user manually marks it as saved.

Apple's parser has two quirks worth knowing:

1. It requires the H field even if false. A payload without H will still parse, but iOS logs a warning in Console.app that some debugging tools surface as "malformed WIFI URI".
2. It trims leading and trailing whitespace from the password but not from the middle, so a password of hello is accepted as hello, which bites people who copy credentials from badly formatted PDFs.

Android 15 behavior

Google Lens is the default QR scanner on Pixel and most recent Android phones. It uses the ZXing library with Google-specific patches. The parser accepts the same five fields as iOS but ships with two extensions:

• TP for transition profiles, used when an SSID migrates from WPA2 to WPA3
• WPA3 as a valid T value, which Pixel supports and Samsung silently downgrades to WPA2

Samsung phones running One UI 6.1 route WiFi QR scans through Bixby Vision by default, which sometimes fails to recognize the URI and shows a generic "copy text" dialog. The fix is to disable Bixby Vision under Camera Settings and let the stock camera app handle the scan.

Working code examples

JavaScript (browser, zero dependencies)

function buildWifiUri({ ssid, password, security = 'WPA', hidden = false }) {
  const esc = (s) => String(s).replace(/([\\;,:"])/g, '\\$1');
  const fields = [
    `T:${security}`,
    `S:${esc(ssid)}`,
    security === 'nopass' ? null : `P:${esc(password)}`,
    `H:${hidden ? 'true' : 'false'}`,
  ].filter(Boolean);
  return `WIFI:${fields.join(';')};;`;
}

const uri = buildWifiUri({ ssid: 'HomeNet', password: 'latte2026' });
// WIFI:T:WPA;S:HomeNet;P:latte2026;H:false;;

Python (with qrcode package)

import qrcode

def build_wifi_uri(ssid, password, security='WPA', hidden=False):
    def esc(s):
        return str(s).translate(str.maketrans({c: '\\' + c for c in '\\;,:"'}))
    fields = [f'T:{security}', f'S:{esc(ssid)}']
    if security != 'nopass':
        fields.append(f'P:{esc(password)}')
    fields.append(f'H:{"true" if hidden else "false"}')
    return f'WIFI:{";".join(fields)};;'

uri = build_wifi_uri('HomeNet', 'latte2026')
qrcode.make(uri).save('wifi.png')

curl (call QRCrack's public API)

curl -X POST https://qrcrack.com/api/qr \
  -H 'Content-Type: application/json' \
  -d '{"type":"wifi","ssid":"HomeNet","password":"latte2026","security":"WPA"}' \
  -o wifi.png

Print contrast and DPI for reliable scans

WiFi QR codes are read more often from paper than URL QR codes are, because they get taped to hotel nightstands, cafe walls, and conference room doors. Contrast and DPI dominate scan reliability more than the data payload.

Contrast must stay above 70 percent between foreground and background. A dark navy QR on pure white passes. A mid-gray QR on cream fails at low light. Always test the print under the actual lighting of the venue, not the studio where you designed it.

Common reasons scans fail

1. Missing T field or T set to an empty string
2. Unescaped semicolon inside the SSID or password
3. Mixed-case security value (Wpa instead of WPA)
4. Hidden SSID with H set to false, which blocks auto-join on iOS 17 and newer
5. Password length above 63 ASCII characters, which exceeds the WPA2 limit
6. QR code printed below 2 cm square at 150 DPI
7. Emoji or zero-width characters in the SSID, which some Android ROMs choke on
8. Missing trailing double semicolon, which some strict parsers treat as malformed

FAQ

Does a WiFi QR code expose the password?

Yes. The password is stored in plain text inside the QR payload. Anyone who photographs the sign can decode it. For venues, the safer pattern is a separate guest SSID with a password that rotates monthly or a captive portal that issues per-session credentials.

Can I encode a WPA3 network?

Pixel 7 and later devices accept T:WPA3. iOS 17 and later also accept it. Older phones fall back to WPA2 if the AP is configured in transition mode. If your AP is WPA3-only, budget for some older devices being unable to join.

Why does my code work on Android but not on iPhone?

The usual cause is a space or non-ASCII character in the SSID that Android tolerates and iOS rejects. Try typing the exact SSID characters into a hex converter to check for hidden bytes.

Is there an RFC?

No formal RFC. The closest document is the 2018 IETF draft draft-harkins-wifi-qr-00, which expired. The format is a de facto standard maintained by the Wi-Fi Alliance via their 2024 Easy Connect documentation.

Do QR codes support WPA2-Enterprise certificates?

Not directly. You can reference a provisioning profile URL inside a generic URL QR code, but the X.509 certificate itself is too large for a QR payload. A 2 KB profile would need a QR size of roughly 177 by 177 modules, which prints poorly below 15 cm.

Sources

• IETF draft draft-harkins-wifi-qr-00 (expired, 2018)
• Wi-Fi Alliance Easy Connect Specification 3.0 (2024 revision)
• Apple Developer documentation on NEHotspotConfiguration (2025)
• Google ZXing source at github.com/zxing/zxing
• Android 15 Compatibility Definition Document, section 7.4
• ISO/IEC 18004:2024 QR code symbology specification

Use QRCrack's WiFi QR generator to generate a WIFI URI with correct escaping, WPA3 support, and print-ready SVG output. No signup, no server storage, runs fully in the browser.

_By the QRCrack engineering team. Published April 15, 2026. Last verified 2026-04-15._