Portable Wi-Fi AirPlay Audio Receiver

A battery-powered AirPlay audio receiver using Raspberry Pi Zero 2W with I2S DAC, OLED display, rotary encoder control, and elegant LED feedback.

Hardware Requirements

Main Components

Component	Model/Spec	Notes
Single Board Computer	Raspberry Pi Zero 2W	Must be 2W for WiFi
DAC	PCM5102 I2S DAC	112dB SNR, line-level output
Display	0.96" OLED SSD1306	128x64, I2C interface
Encoder	EC11 / KY-040	Rotary encoder with push button
LED	WS2812B (NeoPixel)	Single RGB LED
Audio Output	3.5mm AUX jack	Female panel mount

Power System

Component	Spec	Notes
Battery	3.7V 2000mAh Li-ion	~3 hours runtime
Charger	TP4056 module	With battery protection
Boost Converter	3.7V to 5V, 2A+	MT3608 or similar
Power Switch	SPST toggle	Between battery and boost
Diode	IN5819 Schottky	Reverse polarity protection
Capacitor	1000uF 10V	On 5V rail for stability

GPIO Pinout

Complete Pin Reference

Component	Signal	GPIO (BCM)	Physical Pin	Wire Color (suggested)
I2S DAC (PCM5102)
	BCK	GPIO18	Pin 12	Yellow
	LCK (LRCK)	GPIO19	Pin 35	Orange
	DIN	GPIO21	Pin 40	Green
OLED Display
	SDA	GPIO2	Pin 3	Blue
	SCL	GPIO3	Pin 5	Purple
Rotary Encoder
	CLK (A)	GPIO17	Pin 11	White
	DT (B)	GPIO27	Pin 13	Gray
	SW (Button)	GPIO22	Pin 15	Brown
WS2812B LED
	DIN	GPIO10	Pin 19	Green

Power Connections

Component	Power	Ground
PCM5102 DAC	3.3V (Pin 1 or 17)	GND
OLED Display	3.3V	GND
Rotary Encoder	3.3V	GND
WS2812B LED	5V (Pin 2 or 4)	GND

Important: The WS2812B LED requires 5V power, not 3.3V. Use a 330 ohm resistor on the data line.

Installation Guide

Step 1: Flash Raspberry Pi OS

Use Raspberry Pi Imager to flash the SD card:

Download and open Raspberry Pi Imager
Click Choose OS > Raspberry Pi OS (other) > Raspberry Pi OS Lite (32-bit)
Click Choose Storage > Select your SD card
Click the gear icon or press Ctrl+Shift+X for advanced options

Configure:

Setting	Value
Set hostname	`airplay`
Enable SSH	Use password authentication
Set username and password	e.g., `ravi` / `yourpassword`
Configure wireless LAN	Enter your WiFi SSID & password
Wireless LAN country	Your country code (`IN`, `US`, `GB`, etc.)

Click Save, then Write

Step 2: First Boot & SSH

Insert SD card into Raspberry Pi Zero 2W
Power on and wait 2-3 minutes for first boot
Find your Pi's IP (check router admin page or use ping airplay.local)
SSH into your Pi:
```
ssh youruser@airplay.local
```

Step 3: Copy Project Files

From your computer:

scp -r /path/to/AirplayPortable youruser@airplay.local:~/airplay

Or on the Pi using git:

git clone https://github.com/Techposts/Airplay-Portable.git ~/airplay

Step 4: Run Installation

cd~/airplay
chmod +x install.sh
sudo ./install.sh

What the installer does:

Updates system packages
Installs build dependencies
Enables I2C and SPI interfaces
Configures I2S DAC overlay
Enables hardware watchdog
Builds NQPTP (AirPlay 2 timing)
Builds Shairport Sync (AirPlay receiver)
Sets up Python virtual environment
Installs Python dependencies
Creates systemd services
Adds user to hardware groups (gpio, i2c, spi, audio)

Installation takes 20-40 minutes on Pi Zero 2W.

Step 5: Reboot

sudo reboot

Step 6: Verify Installation

# Check AirPlay service
sudo systemctl status shairport-sync
# Check UI service
sudo systemctl status airplay-ui
# View logs
journalctl -u airplay-ui -n 30 --no-pager

Hardware Assembly

I2S DAC (PCM5102) Wiring

PCM5102 Pin	Connect To	Notes
VIN	3.3V (Pin 1)	Power
GND	GND (Pin 6)	Ground
BCK	GPIO18 (Pin 12)	Bit clock
DIN	GPIO21 (Pin 40)	Data in
LCK	GPIO19 (Pin 35)	Left/Right clock
FMT	GND	I2S format
XMT	3.3V	Soft unmute (active high)
SCK	GND	Use internal clock

OLED Display (SSD1306 I2C) Wiring

OLED Pin	Connect To	Notes
VCC	3.3V (Pin 1)	Power
GND	GND (Pin 9)	Ground
SDA	GPIO2 (Pin 3)	I2C Data
SCL	GPIO3 (Pin 5)	I2C Clock

Rotary Encoder (EC11/KY-040) Wiring

Encoder Pin	Connect To	Notes
GND	GND (Pin 14)	Ground
+	3.3V (Pin 17)	Power
CLK	GPIO17 (Pin 11)	Rotation signal A
DT	GPIO27 (Pin 13)	Rotation signal B
SW	GPIO22 (Pin 15)	Push button

WS2812B LED Wiring

LED Pin	Connect To	Notes
VCC	5V (Pin 2)	Must be 5V, not 3.3V
GND	GND (Pin 20)	Ground
DIN	GPIO10 (Pin 19)	Via 330 ohm resistor

Features

Audio

High-quality I2S DAC output (112dB SNR)
Hardware digital volume control via ALSA
Volume persisted across reboots
Multi-room AirPlay 2 sync support
Audio profiles: Normal, Night Mode (max 50% volume), Loud

Controls (Rotary Encoder)

Action	Function
Rotate clockwise	Volume up
Rotate counter-clockwise	Volume down
Short press (<2s)	Open menu
Long press (2-5s)	Mute/unmute
Very long press (>5s)	Force AP mode

LED Status Indicators

State	LED Behavior	Meaning
Booting	White fade in	System starting
Ready	Solid green	Connected, not playing
Playing	Blinking green	Streaming audio
AP Mode	Slow amber blink	WiFi setup mode
Low Voltage	Solid red	Power issue detected
Error	Rapid red blink (3x)	Problem detected
Disabled	Off	LED turned off in settings

OLED Display

Home Screen:

Device name
Playback status (Ready/Streaming)
Volume level with progress bar

Now Playing Screen:

Track title (with auto-scrolling for long titles)
Artist name (with auto-scrolling)
Volume bar

Menu System:

Audio > Volume, Mute, Mode (Normal/Night/Loud)
Network > Status, Saved WiFi (up to 5), Start AP Mode, Device Name
Display > Auto Sleep, Sleep Timer, Clock Saver, LED Enabled, LED Brightness
Power > Power Saver, Restart Streaming
System > Reboot, Shutdown, About (shows CPU temp, memory, uptime, WiFi signal)

Power Management

The device includes comprehensive power management for battery-powered operation.

Features

Feature	Description
Hardware Watchdog	Auto-reboots device if app hangs (15s timeout)
CPU Scaling	`powersave` when idle, `ondemand` when playing
WiFi Power Save	Reduces WiFi power consumption when idle
Voltage Monitoring	Detects undervoltage via `vcgencmd get_throttled`
Display Sleep	Dims after 30s, turns off or shows clock after 60s
Clock Screensaver	Shows time and power status when idle
Safe Shutdown	Graceful shutdown after 3 consecutive low voltage readings

How It Works

Idle State: CPU runs at minimum frequency, WiFi in power save mode
Playing State: CPU switches to on-demand scaling for responsive audio
User Input: Any encoder action wakes the display immediately
Low Voltage: LED turns red, 3 consecutive readings triggers safe shutdown

Battery Life Tips

Enable power saver mode (default: on)
Use shorter display timeout
Disable LED if not needed
Keep volume reasonable (lower = less amplifier power)

Settings (via OLED Menu or Web UI)

Setting	Options	Default
Display Sleep	On/Off	On
Sleep After	15-120 seconds	60s
Clock Saver	On/Off	On
Power Saver	On/Off	On
Audio Mode	Normal/Night/Loud	Normal

Web UI Settings

When connected to WiFi, access the settings page at http://[device-ip]

Available Settings

Section	Settings
Device	Device Name (shown in AirPlay)
Audio	Volume (0-100%), Mute toggle
LED	Enable/Disable, Brightness (5-50%)
Power & Display	Display Sleep, Sleep timeout, Power Saver
Network	WiFi info, Change WiFi button
Track Info (MQTT)	Enable MQTT metadata, Broker settings
System	Power status, Restart AirPlay, Reboot button

Features

Auto-save on change
Real-time power status monitoring
Responsive design for mobile

Changing WiFi Networks

The device saves up to 5 WiFi networks and automatically connects to any available saved network on startup.

Option 1: Via Encoder (Recommended)

Press and hold encoder button for 5 seconds
LED turns amber (blinking) - AP mode active
Connect phone/laptop to "AirPlay-Setup" WiFi network
Open browser to http://192.168.4.1
Select new WiFi network and enter password
Device reboots and connects to new network

Option 2: Via Web UI (When Connected)

Find device IP on your router or check the display
Open browser to http://[device-ip]
Click "Change Wi-Fi Network" in settings
Device enters AP mode for reconfiguration

Viewing Saved Networks

Navigate to Network > Saved WiFi in the OLED menu to see your saved networks.

Troubleshooting

Service Issues

# Check service status
sudo systemctl status airplay-ui
sudo systemctl status shairport-sync
# View detailed logs
journalctl -u airplay-ui -n 50 --no-pager
# Run manually for debuggingcd~/airplay
source venv/bin/activate
python3 src/main.py

Audio Issues

# Check if DAC overlay is loaded
aplay -l
# Test audio output
speaker-test -t sine -f 440 -c 2 -D hw:0
# Check ALSA mixer
amixer -c 0

Display Issues

# Check I2C is enabled
ls /dev/i2c*# Scan for I2C devices (OLED should show at 0x3C)
sudo i2cdetect -y 1

AirPlay Not Visible

# Check shairport-sync
sudo systemctl status shairport-sync
# Check avahi (mDNS/Bonjour)
sudo systemctl status avahi-daemon
# Restart services
sudo systemctl restart shairport-sync avahi-daemon

Project Structure

airplay/
├── install.sh # Installation script
├── device_config.json # Runtime configuration
├── config/
│ ├── shairport-sync.conf # AirPlay config template
│ ├── asound.conf # ALSA configuration
│ ├── hostapd.conf # AP mode hotspot config
│ └── dnsmasq.conf # AP mode DHCP config
├── src/
│ ├── main.py # Main entry point & orchestration
│ ├── config.py # JSON config management
│ ├── display.py # OLED SSD1306 handler
│ ├── encoder.py # Rotary encoder with debouncing
│ ├── led.py # WS2812B animations
│ ├── menu.py # Menu system & navigation
│ ├── audio.py # ALSA volume control
│ ├── network.py # WiFi & AP mode management
│ ├── power.py # Power management & watchdog
│ └── wifi_portal.py # Flask web UI
├── templates/
│ ├── portal.html # WiFi setup page (AP mode)
│ └── settings.html # Device settings page
├── services/
│ ├── airplay-ui.service # Main UI systemd service
│ └── wifi-portal.service # WiFi portal systemd service
└── venv/ # Python virtual environment

Configuration File

The device configuration is stored in ~/airplay/device_config.json:

{
"device_name": "Portable AirPlay",
"volume": 70,
"muted": false,
"led_enabled": true,
"led_brightness": 20,
"display_timeout_enabled": true,
"display_timeout_secs": 60,
"screensaver_clock": true,
"power_saver_enabled": true,
"audio_profile": "normal",
"wifi_configured": true,
"wifi_ssid": "YourNetworkName",
"saved_networks": [
{"ssid": "Network1", "password": "****"},
{"ssid": "Network2", "password": "****"}
]
}

Settings are automatically saved when changed via the OLED menu or Web UI.

API Reference

Endpoints

Endpoint	Method	Description
`/`	GET	Main page (settings or WiFi setup)
`/api/status`	GET	Get all current settings
`/api/settings`	POST	Update multiple settings
`/api/volume`	POST	Set volume level
`/api/mute`	POST	Toggle mute state
`/api/restart-airplay`	POST	Restart AirPlay (shairport-sync) service
`/scan`	GET	Scan WiFi networks
`/connect`	POST	Connect to WiFi
`/reboot`	POST	Reboot device
`/restart-wifi`	POST	Enter AP mode

Example: Update Settings

curl -X POST http://192.168.1.100/api/settings \
-H "Content-Type: application/json" \
-d '{"volume": 50, "led_enabled": true}'

Known Limitations

Pi Zero 2W only - Requires WiFi and sufficient CPU for AirPlay 2
No Bluetooth - WiFi-only for better audio quality and sync
Single LED - Minimal visual feedback by design
3-hour battery - With 2000mAh battery; larger battery = longer runtime

License

MIT License - Feel free to modify and share!

Credits

Shairport Sync - AirPlay audio receiver
NQPTP - PTP timing for AirPlay 2
Adafruit CircuitPython libraries for hardware support

Name		Name	Last commit message	Last commit date
STLs		STLs
config		config
scripts		scripts
services		services
src		src
templates		templates
QUICK_START.md		QUICK_START.md
README.md		README.md
SETUP.md		SETUP.md
install.sh		install.sh

Latest commit

History

Folders and files

Repository files navigation

Portable Wi-Fi AirPlay Audio Receiver

Table of Contents

Hardware Requirements

Main Components

Power System

GPIO Pinout

Complete Pin Reference

Power Connections

Installation Guide

Step 1: Flash Raspberry Pi OS

Step 2: First Boot & SSH

Step 3: Copy Project Files

Step 4: Run Installation

Step 5: Reboot

Step 6: Verify Installation

Hardware Assembly

I2S DAC (PCM5102) Wiring

OLED Display (SSD1306 I2C) Wiring

Rotary Encoder (EC11/KY-040) Wiring

WS2812B LED Wiring

Features

Audio

Controls (Rotary Encoder)

LED Status Indicators

OLED Display

Power Management

Features

How It Works

Battery Life Tips

Settings (via OLED Menu or Web UI)

Web UI Settings

Available Settings

Features

Changing WiFi Networks

Option 1: Via Encoder (Recommended)

Option 2: Via Web UI (When Connected)

Viewing Saved Networks

Troubleshooting

Service Issues

Audio Issues

Display Issues

AirPlay Not Visible

Project Structure

Configuration File

API Reference

Endpoints

Example: Update Settings

Known Limitations

License

Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages