OpenPisoWiFi — Free & Open-Source Piso Wi-Fi Operating System

SECTION 1Hardware Inventory

📦 Bill of Materials & Shopee Verified Parts

All components are verified standard off-the-shelf electronics. No proprietary boards required.

✓ 100% Solderless Capable

📡

✓ Core for Build 1Router

OpenWrt Gigabit Router

Tested and verified on Ruijie Reyee EW1200G Pro (compatible with any OpenWrt gigabit router). Full Gigabit WAN + 3 Gigabit LAN ports, Dual-Band AC1200 Wi-Fi with high-power PA/LNA amplifiers.

Voltage: 12V DC (Center Positive Jack)

Clients: 100+ Concurrent Devices

OS: OpenWrt 25.12.5 (Kernel 6.6)

Buy Ruijie Router on Shopee

🎛️

Optional SatelliteController

ESP32 DevKit Board

Dual-core 240MHz SoC with hardware interrupt timers for microsecond coin pulse debouncing. Any 30 or 38-pin version (Type-C or Micro-USB) works.

Voltage: 5V (USB or VIN pin via Buck Converter)

Logic Level: 3.3V DC (White pulse wire needs 10kΩ resistor)

Interrupts: Hardware ISR on GPIO 4 (Zero pulse loss)

Open 1-Click ESP32 Web Flasher Shopee (All Pins / International) Shopee (Local PH Store)

🪙

✓ All BuildsAcceptor

Universal Multi-Coinslot

Recognizes ₱1, ₱5, ₱10, and ₱20 coins (old & new BSP series). Includes optical anti-stringing sensors and hardware drop inhibit lock line.

Voltage: 12V DC (50mA standby, 350mA pulse)

Pulse Output: 12V Pulse (White wire)

Inhibit Line: Active LOW/HIGH (Gray wire)

Allan Universal Coinslot Weiyu Universal Coinslot (Alt)

⚡

✓ All BuildsPower

12V Centralized Power Supply

12V 5A or 10A CCTV metal switching PSU. Powers router, coin acceptor, and Raspberry Pi from a single 220V plug with no voltage sags.

Input: 110V / 220V AC Mains

Output: 12V DC Regulated (Adjustable ±10%)

Safety: Short-circuit & overload cutoff

Buy 12V Centralized PSU on Shopee

🔗

SolderlessWiring

Quick Lever Terminal Blocks

Reusable spring-lever wire clamps. Eliminate electrical tape and soldering. Makes maintenance, parts replacement, and voltage testing effortless.

Gauge: 28 to 12 AWG solid / stranded

Rating: 250V / 32A

Type: 1-in-multiple-out or 2-in-4-out

Quick Connector Block (Option 1) Quick Connector Block (Option 2)

🛡️

IsolationSafety

LM2596 Buck & 10kΩ Resistors

LM2596/XL4015 steps down 12V DC to 5.1V 3A for SBC/ESP32. A 10kΩ resistor connects in series between the coinslot white pulse wire and the GPIO pin for current limiting and gate protection.

Buck Out: Tune potentiometer to exactly 5.1V (or use USB model)

Coin Resistor: 10kΩ ¼W resistor inline on signal wire

Optocoupler: Not needed — 10kΩ resistor limits input current

12V to 5V Buck Converter (USB Plug-and-Play) 12V to 5V Buck Converter (Solder / Screw Terminal)

SECTION 2Electrical Circuit

🔌 Complete Wiring Blueprint & Pinout Reference

Follow this exact circuit schematic to wire the power supply, coinslot, 10kΩ resistor, and controller.

⚡ 12V Central Rail • 🛡️ 3.3V Logic Rail

MASTER POWER & SIGNAL DISTRIBUTION

Target for Build 1: Raspberry Pi 40-Pin Header (Pins 3 & 5)

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        ⚡ CENTRALIZED 12V 5A/10A POWER SUPPLY                          │
│   [ L ] [ N ] [ EARTH ]   │   [ +V  (+12V DC) ]         [ COM  (Ground / GND) ]        │
└─────┬───┬──────┬──────────┴──────────┬─────────────────────────────┬───────────────────┘
      │   │      │                     │                             │
    220V AC MAINS                      ▼                             ▼
                            ┌─────────────────────┐       ┌─────────────────────┐
                            │ QUICK TERMINAL +12V │       │ QUICK TERMINAL GND  │
                            │  (Lever Block 1)    │       │  (Lever Block 2)    │
                            └──┬────────┬───────┬─┘       └──┬────────┬───────┬─┘
                               │        │       │            │        │       │
        ┌──────────────────────┘        │       └────────────┼────────┼───────┼────────┐
        │                               │                    │        │       │        │
        ▼ (+12V)                        ▼ (+12V)             ▼ (GND)  │       ▼ (GND)  │
┌───────────────┐              ┌─────────────────┐ ┌───────────────┐  │  ┌──────────┐  │
│ RUIJIE ROUTER │              │ ALLAN / WEIYU   │ │ BUCK 12V->5V  │  │  │ COMMON   │  │
│ 12V DC JACK   │              │ COINSLOT        │ │ DC CONVERTER  │  │  │ GROUND   │  │
│ (+) Center Pin│              │ Red Wire (+12V) │ │ IN+   /   IN- │◄─┘  │ BUS      │  │
│ (-) Outer Ring│◄─────────────┤ Black Wire (GND)│ └───────┬───────┘     └────┬─────┘  │
└───────────────┘              │                 │         │ (5V Power)       │        │
                               │ White (COIN)──┐ │         │ Direct           │        │
                               │ Gray (INHIBIT)┼┐│         ▼                  │        │
                               └───────────────┘││   ┌───────────┐            │        │
                                                ││   │ 5V DC OUT │            │        │
                                                ││   │ USB-C/PIN2│            │        │
                               ┌────────────────┼┘   └─────┬─────┘            │        │
                               │                │          │                  │        │
                               │ ┌──────────────▼───┐      │                  │        │
                               │ │  10kΩ RESISTOR   │      │                  │        │
                               │ │ [== 10k OHM ==]  │      │                  │        │
                               │ └──────────────┬───┘      │                  │        │
                               │                │          │                  │        │
                               ▼ (Direct)       ▼ (Pulse)  ▼ (5V Power)       ▼ (GND)  │
┌──────────────────────────────────────────────────────────────────────────────────────┴─┐
│  🍓 RASPBERRY PI 3B+/4B/5  OR  🎛️ ESP32 DEVKIT CONTROLLER                               │
│                                                                                        │
│   • Power IN: 5V (Direct from Buck Converter OUT+)  +  GND (Pin 6 Common Ground)       │
│   • GPIO 2 (Physical Pin 3)  OR  ESP32 GPIO 4   ◄── VIA 10kΩ RESISTOR (Coin Pulse)     │
│   • GPIO 3 (Physical Pin 5)  OR  ESP32 GPIO 5   ◄── DIRECT WIRE (Inhibit / Coin Lock)  │
│   • Gigabit eth0 (Static 192.168.1.240) ───────────► Ruijie Router LAN 1 Port         │
└────────────────────────────────────────────────────────────────────────────────────────┘

⚠️ Critical Rule #1: Common Ground

All negative (COM/GND) wires from the 12V PSU, buck converter output, and coin acceptor MUST connect to the same common Ground bus block.

⚠️ Critical Rule #2: 10kΩ Resistor Protection

Always place a 10kΩ resistor inline between the coinslot White pulse wire and the Pi (Pin 3 / GPIO 2) or ESP32 (GPIO 4). It limits current to <0.3mA and prevents damage to 3.3V logic gates without needing a bulky optocoupler module.

🎨 Allan & Weiyu 4-Wire Pinout

Coinslot Harness

WIRE	SIGNAL	DESTINATION
🔴 Red	+12V Power	+12V Quick Terminal Block
⚫ Black	Ground (GND)	COM / GND Quick Terminal Block
⚪ White	Coin Pulse Signal	10kΩ Resistor inline → GPIO 2 (Pin 3) / ESP32 GPIO 4
🔘 Gray	Drop Inhibit Gate	Relay NC / Inhibit Lock Output

Coinslot Calibration Switches:

Speed Switch: Set to MED (40ms) for reliable pulse counting.
Mode Switch: Set to NO (Normally Open).
Inhibit Line: Active LOW permits insertion; HIGH rejects coin.

📌 Pinout Mapping Table

Pi & ESP32

FUNCTION	RASPBERRY PI PIN	ESP32 PIN	SIGNAL NOTES
5V Power IN	Physical Pin 2 (5V)	VIN Pin (5V)	Fed from Buck Converter (5.1V tuned)
Ground (GND)	Physical Pin 6 (GND)	GND Pin	Common return to PSU Ground bus
COIN PULSE (ISR)	Physical Pin 3 (GPIO 2)	GPIO 4 (D4)	Microsecond pulse detection interrupt
INHIBIT GATE	Physical Pin 5 (GPIO 3)	GPIO 5 (D5)	Software lock prevents coin drops when idle
Ethernet WAN/LAN	eth0 (192.168.1.240)	Wi-Fi (Staff AP)	Direct link to OpenWrt router LAN port

💡 Software Pin Override:

You can change the assigned pins at any time without recompiling by setting COIN_GPIO_PIN=2 and INHIBIT_GPIO_PIN=3 inside /opt/open-piso-wifi/daemon/.env or directly inside the Admin portal at :3000/admin.

SECTION 3Provisioning & Scripts

💻 Step-by-Step Software Installation

Step-by-step terminal instructions tailored for Build 1.

Automated 1-Click Scripts

🚀

Step-by-Step Guide for Build 1 (Pi + OpenWrt Router)

Commercial deployment: OpenWrt handles high concurrency, Pi serves Next.js portal.

ACTIVE

STEP 1

Prepare Raspberry Pi OS & Install OpenPisoWiFi

Flash Raspberry Pi OS Lite (64-bit) or Ubuntu Server onto your micro-SD card or NVMe SSD. Boot the Pi, connect via SSH, and run the automated setup installer:

curl -fsSL https://raw.githubusercontent.com/haliknihudas666/open-piso-wifi/main/scripts/install.sh | sudo bash

This automatically installs Node.js, Bun, SQLite, systemd service daemons, and builds the Next.js captive paywall.

STEP 2

Flash & Provision OpenWrt Router (Tested on Ruijie EW1200G Pro)

Connect an Ethernet cable from Raspberry Pi eth0 to LAN 1 port on your OpenWrt router (e.g. Ruijie EW1200G Pro). Then execute our automated router deployer:

bash scripts/deploy-router.sh --router-ip 192.168.1.1 --portal-ip 192.168.1.240

✓ Injects kernel nftables rules in /etc/nftables.d/piso_portal.nft

✓ Sets alias gateway IP 10.0.0.1 & dnsmasq domain wifi.local

✓ Configures Dropbear SSH keyless exchange with the Pi daemon

STEP 3

Wire 12V Coinslot to Pi GPIO

Wire 12V and GND from your centralized power supply into the Allan or Weiyu coinslot. Connect the white pulse line through a 10kΩ resistor into Pi Physical Pin 3 (GPIO 2), and inhibit to Physical Pin 5 (GPIO 3).

STEP 4

Verify Live Pulses & Access Admin Console

Open your web browser and navigate to http://192.168.1.240:3000/admin. Default PIN is 1234. Drop a ₱1 or ₱5 coin into the slot and observe the real-time pulse monitor increment. Connect your phone to the router Wi-Fi and verify the captive portal displays instantly.

SECTION 4Cloud & Automation

☁️ Telegram, Supabase, Vercel & Cloudflare Setup

100% free remote monitoring stack. Configure Telegram bot alerts directly in the Admin GUI by simply pasting your key — zero terminal commands or .env file edits required.

🤖 Long-Polling Bot • ⚡ Supabase PostgreSQL

🤖

Telegram Bot Remote Push Alerts

Instant Phone Push • Zero .env Editing

100% FREE

Receive an instant push notification on your phone the millisecond a coin is dropped or the cash box is emptied. Operates via outbound HTTPS long-polling, meaning it works 100% seamlessly behind CGNAT, mobile hotspots, and double-NAT without opening firewall ports.

Step-by-Step Setup (Takes <60 Seconds):

Open Telegram and message @BotFather.
Send /newbot, name your bot, and copy the HTTP API Token.
Message @userinfobot and send /start to copy your numeric Chat ID.
Open http://10.0.0.1:3000/admin ➔ Cloud & Satellites.
Paste the Bot Token and Admin Chat ID into the fields, click Save & Connect, then click Send Test Alert!

Supported Remote Phone Commands:

/sales - Live revenue today

/slots - Hardware health

/emptybox - Reset audit counter

/wan - Router latency & ping

🛡️ Security: Locked strictly to your Admin Chat IDAnti-Spam Filtered

⚡

Supabase PostgreSQL Fleet Sync

Cloud Database • Multi-Branch Telemetry

$0/MO FREE TIER

Centralize coin revenue, transaction records, voucher logs, and kiosk heartbeats from all your machines across multiple barangays into a single high-performance PostgreSQL cloud database.

Step-by-Step Setup:

Create a free account at supabase.com.
Create a new project (e.g. openpiso-fleet, Region: Singapore).
In SQL Editor, paste and run the contents of supabase/schema.sql.
Copy your Project URL and API Key from Settings ➔ API.
Paste them into your kiosk /admin/cloud console. Telemetry queues in memory and flushes every 60s!

Fail-Soft Offline Resilience:

If the kiosk ISP drops offline, transactions queue in memory safely. The moment connection restores, all buffered coin records automatically flush to Supabase with zero data loss.

📊 Production Tables: piso_machines, piso_transactionsRow Level Security

▲

Vercel Cloud Fleet Dashboard

24/7 Web App • Global Access

SERVERLESS

Deploy the OpenPisoWiFi admin portal to Vercel for a public cloud dashboard (https://your-piso.vercel.app) to check daily earnings, transaction logs, and kiosk uptime from any smartphone or laptop worldwide.

Deployment Steps:

Push your repository fork to GitHub.
In vercel.com, click Add New Project and import your repo.
Set Root Directory to portal. Vercel automatically detects Next.js.
Add environment variables: NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
Click Deploy. Open /admin/cloud on your live Vercel URL to monitor all machines!

⚙️ Preconfigured: portal/vercel.jsonZero Config Next.js

🟠

Cloudflare Zero-Trust Tunnel

CGNAT Bypass • Zero Port Forwarding

SECURE ENCLAVE

Want direct remote web access to your physical Raspberry Pi's local admin dashboard (http://10.0.0.1:3000/admin) from anywhere on earth without opening ports or risking hacker scans? Use a free Cloudflare Tunnel.

3-Step Tunnel Setup:

In dash.cloudflare.com, open Zero Trust ➔ Networks ➔ Tunnels.
Click Add a Tunnel (select cloudflared) and name it pisowifi-gateway.
Run the single provided curl command on your Raspberry Pi terminal to install the lightweight daemon.
Route public hostname (e.g. kiosk1.yourdomain.com) to http://localhost:3000. That's it!

📖 Detailed manual: docs/CLOUD_AND_INTEGRATIONS_GUIDE.mdDDoS Protected

SECTION 5Field Diagnostics

⚙️ Calibration, Testing & Common Troubleshooting

Solutions to common hardware gotchas encountered by DIY operators.

1. Coin Falls Through or Gets Rejected

Inhibit Gate Locked: Ensure the gray inhibit line is not held HIGH. If disconnected on some models, it defaults to locked. In the admin console, verify the inhibit line is UNLOCKED during coin drop windows.
Voltage Drop: Measure 12V PSU output with a multimeter under load. If it sags below 11.2V, the optical coin sensors cannot calibrate.
Dirty Sensor: Blow compressed air through the coin chute to clear dust.

2. Phantom Pulses or Double Counting

Pulse Speed Too Fast: Switch the coinslot DIP toggle from FAST (20ms) to MEDIUM (40ms). 20ms pulses often produce switch-bounce jitter.
Missing 10kΩ Resistor: Direct unbuffered wiring picks up inductive RF noise and overcurrent. Always install a 10kΩ resistor inline on the white signal line.
Floating Ground: Ensure 12V COM and 5V GND are tied together at the common bus block.

3. Captive Portal Doesn't Pop Up Automatically

DNS Masquerade: Verify wifi.local resolves to 10.0.0.1 on the client phone.
Firewall Table: SSH into OpenWrt or Pi and run sudo nft list table inet piso_portal to confirm port 80 redirect rules are loaded.
Manual Access: Open browser and navigate directly to http://10.0.0.1:3000 or http://wifi.local.

4. Router Reboots When Coins Are Inserted

Power Supply Under-capacity: When the coin solenoid fires, it draws a 350mA spike. A weak 12V 1A adapter will brown out and reset the router.
Solution: Always use the recommended 12V 5A or 10A Centralized Metal PSU.