262 lines
11 KiB
Markdown
262 lines
11 KiB
Markdown
---
|
|
title: "Wi-Fi QR Code Protocol: WIFI: String Syntax Specification & Mobile OS Parsing"
|
|
description: "A comprehensive developer guide to the unofficial WIFI: URI protocol specification, character escaping rules, WPA2/WPA3 network formats, and creating a print qr code for Wi-Fi access."
|
|
tags: networking, mobile, webdev, security
|
|
keywords: qr wifi, wifi qr code generator, print qr code, print a qr code, free static qr code generator, static qr code generator
|
|
canonical_url: https://www.qrmaster.net/blog/wifi-qr-code-generator
|
|
---
|
|
|
|
# Wi-Fi QR Code Protocol: WIFI: String Syntax Specification & Mobile OS Parsing
|
|
|
|
Scanning a **qr wifi** code to automatically connect a smartphone to a Wi-Fi network without manually typing complex WPA3 passwords is one of the most common physical tech interactions.
|
|
|
|
Unlike vCards or geo-locations which have formal IETF RFC standards, a **wifi qr code generator** uses an de facto industry standard string syntax originally popularized by ZXing ("Zebra Crossing").
|
|
|
|
In this technical guide, we will inspect the exact `WIFI:` connection string syntax, character escaping rules, WPA2/WPA3 security flags, hidden network parameters, and build a TypeScript utility to generate a **print qr code** for physical tabletop stands using a **free static qr code generator**.
|
|
|
|
---
|
|
|
|
## 1. The `WIFI:` String Protocol Syntax
|
|
|
|
The payload generated by a **wifi qr code generator** is a formatted key-value string prefixed with `WIFI:`.
|
|
|
|
### Protocol Format:
|
|
```text
|
|
WIFI:S:<SSID>;T:<SECURITY_TYPE>;P:<PASSWORD>;H:<HIDDEN_FLAG>;;
|
|
```
|
|
|
|
### Parameter Specification:
|
|
|
|
| Parameter Key | Description | Allowed Values | Required? |
|
|
|---|---|---|---|
|
|
| **S** | Network SSID (Name) | Any string (UTF-8) | ✅ Mandatory |
|
|
| **T** | Security Encryption Type | `WPA`, `WEP`, `nopass` | ✅ Mandatory |
|
|
| **P** | Pre-shared Key (Password) | Network password string | Conditional (Skip if `nopass`) |
|
|
| **H** | Hidden SSID Flag | `true` or `false` | Optional (Default: `false`) |
|
|
|
|
---
|
|
|
|
## 2. Character Escaping Rules: Avoiding Connection Failures
|
|
|
|
The most frequent bug when building a **wifi qr code generator** is failing to escape special delimiter characters in the SSID or Password.
|
|
|
|
### Characters Requiring Backslash Escaping (`\`):
|
|
If an SSID or Wi-Fi password contains any of the following four characters:
|
|
- Colon `:`
|
|
- Semicolon `;`
|
|
- Backslash `\`
|
|
- Comma `,`
|
|
|
|
They **must be escaped with a preceding backslash (`\`)**.
|
|
|
|
### Escaping Examples:
|
|
|
|
```text
|
|
# Example 1: SSID containing a semicolon ("Coffee;Bar") and password "secret:123"
|
|
WIFI:S:Coffee\;Bar;T:WPA;P:secret\:123;;
|
|
|
|
# Example 2: Unencrypted Open Network ("Guest_WiFi")
|
|
WIFI:S:Guest_WiFi;T:nopass;;
|
|
|
|
# Example 3: Hidden WPA2/WPA3 Network ("Vault") with password "P@$$w0rd"
|
|
WIFI:S:Vault;T:WPA;P:P@$$w0rd;H:true;;
|
|
```
|
|
|
|
> **Important**: Notice the double semicolon (`;;`) at the very end of the string. Mobile camera scanners use the trailing double semicolon as the string termination marker when parsing **qr wifi** codes!
|
|
|
|
---
|
|
|
|
## 3. iOS vs. Android OS Parser Behavior
|
|
|
|
Understanding how mobile operating systems parse `WIFI:` barcodes prevents support headaches when users **print a qr code**.
|
|
|
|
```
|
|
┌───────────────────────────┬───────────────────────────────────────────┬───────────────────────────────────────────┐
|
|
│ Feature │ Apple iOS (Camera App) │ Android (Google Lens / Native Scanner) │
|
|
├───────────────────────────┼───────────────────────────────────────────┼───────────────────────────────────────────┤
|
|
│ User Interaction Prompt │ Displays banner: "Join 'SSID' Network?" │ Displays modal with "Connect to Network" │
|
|
│ One-Tap Auto Connect │ ✅ Yes (Connects without typing password) │ ✅ Yes (Saves & connects automatically) │
|
|
│ WPA3 Compatibility │ Map `T:WPA` for both WPA2 & WPA3 │ Map `T:WPA` for both WPA2 & WPA3 │
|
|
│ Enterprise (802.1X / EAP)│ ❌ Unsupported via standard `WIFI:` string│ ❌ Requires mobile profile (.mobileconfig)│
|
|
└───────────────────────────┴───────────────────────────────────────────┴───────────────────────────────────────────┘
|
|
```
|
|
|
|
*Note on WPA3:* Neither iOS nor Android requires a separate `T:WPA3` tag. Specifying `T:WPA` in your **static qr code generator** covers WPA, WPA2, and WPA3 Personal networks seamlessly.
|
|
|
|
---
|
|
|
|
## 4. TypeScript Implementation: Wi-Fi Payload Generator
|
|
|
|
Below is a complete, production-ready TypeScript utility class that formats, escapes, and validates payloads for a **free static qr code generator**.
|
|
|
|
### `src/services/wifiPayloadBuilder.ts`
|
|
|
|
```typescript
|
|
export type WifiSecurityType = 'WPA' | 'WEP' | 'nopass';
|
|
|
|
export interface WifiConfig {
|
|
ssid: string;
|
|
password?: string;
|
|
securityType: WifiSecurityType;
|
|
isHidden?: boolean;
|
|
}
|
|
|
|
export class WifiPayloadBuilder {
|
|
/**
|
|
* Generates a fully escaped, validated WIFI: connection string.
|
|
*/
|
|
public static buildPayload(config: WifiConfig): string {
|
|
const { ssid, password = '', securityType, isHidden = false } = config;
|
|
|
|
if (!ssid || ssid.trim().length === 0) {
|
|
throw new Error('Wi-Fi SSID is mandatory.');
|
|
}
|
|
|
|
if (securityType !== 'nopass' && (!password || password.length === 0)) {
|
|
throw new Error(`Password is required for security type "${securityType}".`);
|
|
}
|
|
|
|
// Escape special delimiter characters
|
|
const escapedSSID = this.escapeString(ssid);
|
|
const escapedPassword = securityType !== 'nopass' ? this.escapeString(password) : '';
|
|
|
|
let payload = `WIFI:S:${escapedSSID};T:${securityType};`;
|
|
|
|
if (securityType !== 'nopass') {
|
|
payload += `P:${escapedPassword};`;
|
|
}
|
|
|
|
if (isHidden) {
|
|
payload += `H:true;`;
|
|
}
|
|
|
|
// Append compulsory double-semicolon termination marker
|
|
payload += ';';
|
|
|
|
return payload;
|
|
}
|
|
|
|
private static escapeString(str: string): string {
|
|
return str.replace(/([\\;:,])/g, '\\$1');
|
|
}
|
|
|
|
public static isValidWifiPayload(payload: string): boolean {
|
|
return payload.startsWith('WIFI:') && payload.endsWith(';;');
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. How to Print a QR Code: Printable Wi-Fi Tabletop Sign Template
|
|
|
|
When you **print a qr code** for physical venues (hotels, cafes, coworking spaces), pairing the vector barcode with clean printable HTML typography ensures guests know how to scan **qr wifi**.
|
|
|
|
### Example Printable HTML Template (`public/wifi-stand-card.html`):
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>Wi-Fi Access Sign - Print QR Code</title>
|
|
<style>
|
|
@media print { body { -webkit-print-color-adjust: exact; } }
|
|
body { font-family: 'Inter', system-ui, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; background: #F8FAFC; margin: 0; }
|
|
.card { background: white; width: 320px; padding: 36px 28px; border-radius: 20px; box-shadow: 0 10px 25px rgba(0,0,0,0.08); text-align: center; border: 1px solid #E2E8F0; }
|
|
h1 { font-size: 22px; color: #0F172A; margin: 0 0 6px; }
|
|
p.subtitle { color: #64748B; font-size: 14px; margin: 0 0 24px; }
|
|
.qr-container { background: #F1F5F9; padding: 16px; border-radius: 16px; display: inline-block; margin-bottom: 24px; }
|
|
.qr-container svg { display: block; }
|
|
.info-box { background: #F8FAFC; padding: 12px 16px; border-radius: 12px; border: 1px solid #E2E8F0; text-align: left; font-size: 13px; }
|
|
.info-row { display: flex; justify-content: space-between; margin-bottom: 6px; }
|
|
.info-row:last-child { margin-bottom: 0; }
|
|
.label { color: #64748B; font-weight: 500; }
|
|
.val { color: #0F172A; font-weight: 600; font-family: monospace; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="card">
|
|
<h1>Connect to Wi-Fi</h1>
|
|
<p class="subtitle">Scan with your phone camera to join</p>
|
|
|
|
<div class="qr-container">
|
|
<!-- Insert Vector SVG QR Code Here -->
|
|
<svg width="180" height="180" viewBox="0 0 180 180">
|
|
<!-- SVG Paths -->
|
|
</svg>
|
|
</div>
|
|
|
|
<div class="info-box">
|
|
<div class="info-row">
|
|
<span class="label">Network:</span>
|
|
<span class="val">Guest_Lounge_5G</span>
|
|
</div>
|
|
<div class="info-row">
|
|
<span class="label">Password:</span>
|
|
<span class="val">Welcome2026!</span>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
---
|
|
|
|
## 6. End-to-End Test Suite with Jest
|
|
|
|
Let's write a unit test suite to verify string escaping and boundary conditions.
|
|
|
|
### `tests/wifiPayload.test.ts`
|
|
|
|
```typescript
|
|
import { WifiPayloadBuilder } from '../src/services/wifiPayloadBuilder';
|
|
|
|
describe('WifiPayloadBuilder', () => {
|
|
test('should generate standard WPA2 payload', () => {
|
|
const payload = WifiPayloadBuilder.buildPayload({
|
|
ssid: 'MyHomeWiFi',
|
|
password: 'SuperSecretPassword123',
|
|
securityType: 'WPA',
|
|
});
|
|
expect(payload).toBe('WIFI:S:MyHomeWiFi;T:WPA;P:SuperSecretPassword123;;');
|
|
});
|
|
|
|
test('should escape colons and semicolons in SSID and Password', () => {
|
|
const payload = WifiPayloadBuilder.buildPayload({
|
|
ssid: 'Cafe;WiFi:5G',
|
|
password: 'pass;word:123,key\\',
|
|
securityType: 'WPA',
|
|
});
|
|
expect(payload).toBe('WIFI:S:Cafe\\;WiFi\\:5G;T:WPA;P:pass\\;word\\:123\\,key\\\\;;');
|
|
});
|
|
|
|
test('should handle open unencrypted networks', () => {
|
|
const payload = WifiPayloadBuilder.buildPayload({
|
|
ssid: 'FreePublicWiFi',
|
|
securityType: 'nopass',
|
|
});
|
|
expect(payload).toBe('WIFI:S:FreePublicWiFi;T:nopass;;');
|
|
});
|
|
|
|
test('should include hidden flag when network is hidden', () => {
|
|
const payload = WifiPayloadBuilder.buildPayload({
|
|
ssid: 'HiddenNetwork',
|
|
password: 'secretpassword',
|
|
securityType: 'WPA',
|
|
isHidden: true,
|
|
});
|
|
expect(payload).toBe('WIFI:S:HiddenNetwork;T:WPA;P:secretpassword;H:true;;');
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
Understanding the `WIFI:` payload specification and implementing strict character escaping in a **wifi qr code generator** ensures seamless, friction-free auto-connections when you **print a qr code** for hotel guests, restaurant customers, and office visitors.
|
|
|
|
To generate customizable vector Wi-Fi QR codes with custom brand colors, logo embedding, and printable tabletop stand templates, check out [QR Master Free Wi-Fi QR Generator](https://www.qrmaster.net/blog/wifi-qr-code-generator).
|