Connect legacy Orvibo WiWo S20 smart sockets to Wi-Fi from the terminal

The original WiWo app is no longer available, but the sockets still work. This command-line tool recreates the pairing flow used by the app, so you can connect the socket to your Wi-Fi network from a computer.

If your socket looks like this, you're probably in the right place!

‼️ Caution
Home Assistant's Orvibo integration page warns about the European ORVIBO Wi-Fi SMART SOCKET S20 (LGS-20) and links to the RAPEX recall entry. That warning is about electrical safety, not software support. Use this repo to pair hardware you already own. It is not a recommendation to buy, keep using, or power up a recalled device without making your own safety assessment.

• An Orvibo WiWo S20 socket
• A Mac or Linux computer with Wi-Fi and Terminal access
  Windows may also work, but the tool was not tested there
• Node.js 22 or newer installed
• The Wi-Fi name and password that the socket should use

You do not need to clone this repo or know JavaScript. If node --version or npm --version fail, install Node.js first and then come back here.

1. Install the tool while your computer is connected to the internet:

   npm install --global s20-wifi-setup

   Using npx here will usually fail. Running npx s20-wifi-setup still checks the npm registry, which is unavailable once you switch to the socket's temporary Wi-Fi network.

   💡 Tip
   If a global install is inconvenient, you can install the tool into a throwaway local project instead:

   cd /path/to/some/empty/directory
   npm init --yes
   npm install --save-dev s20-wifi-setup

   If you install the tool locally, run npm exec s20-wifi-setup -- [args] from that directory instead of s20-wifi-setup [args]. The rest of this README assumes a global install.

2. Make sure the pairing tool starts correctly:

   s20-wifi-setup --help

   You should see the help output.

3. Plug the S20 into a power socket.

4. Put the socket into pairing mode by pressing and holding the button on it. The LED should start flashing blue. If it flashes red instead, press and hold the button again.

5. On your computer, turn off any VPNs or other tools that change network routing until the socket is paired.

6. Connect your computer to the socket's temporary Wi-Fi network, usually WiWo-S20.

7. Run the pairing command and replace the Wi-Fi details with your own:

   s20-wifi-setup pair --ssid "MyWifi" --password "super-secret"

   💡 Tip
   This command includes your Wi-Fi password, so it might be saved in your shell history.
   In many setups, adding a space before the command prevents that.

8. Wait for the command to finish. You should see:

   Done. The S20 should now reboot and join your Wi-Fi.
   

9. Wait a few seconds for the socket to reconnect to your usual Wi-Fi.

10. Reconnect your computer to your usual Wi-Fi network if needed.

11. Enjoy your smart socket!

    🎉 🎉 🎉
    🎉 🔌 🎉
    🎉 🎉 🎉

    Consider integrating it with Home Assistant or your preferred home automation system.

12. Uninstall the tool if you no longer need it:

    npm uninstall --global s20-wifi-setup

Start with these checks:

• Make sure the LED is still quickly flashing blue.
• Confirm that your computer got a 10.10.100.x address while joined to WiWo-S20.
• Turn off VPNs or other tools that change network routing.
• If the socket uses a non-default IP, try --target-ip.

Example:

s20-wifi-setup pair \
  --ssid "MyWifi" \
  --password "super-secret" \
  --target-ip 10.10.100.254

If that still does not work and you are on macOS or Linux, collect a diagnostic report:

s20-wifi-setup diagnose

The diagnose command prints a full report to stdout. It may prompt for sudo so it can clear stale ARP state and run tcpdump.

You can create an issue describing the details, but please be mindful about sharing private information such as MAC addresses or Wi-Fi names. If you want a quicker first pass, paste the report into an LLM alongside a link to this repo instead of opening an issue right away. If you manage to find and fix a bug in s20-wifi-setup, please consider opening a pull request.

The S20 exposes a temporary Wi-Fi network while in pairing mode. Once your computer is connected to that network, this tool talks to the socket over UDP and reproduces the same AP-mode commands used by the original WiWo app.

It also handles a macOS-specific failure mode where discovery works, but direct sends to 10.10.100.254 fail with EHOSTUNREACH. When that happens, the CLI retries via subnet broadcast automatically.

On Windows, pairing may still work because the actual pairing flow is just UDP over the socket's temporary network. The unsupported part is diagnostics, not the core pairing protocol.

Show built-in help:

s20-wifi-setup --help

Use environment variables instead of command-line flags:

WIFI_SSID="MyWifi" WIFI_PASSWORD="super-secret" \
  s20-wifi-setup pair

pair is supported on macOS and Linux. It may also work on Windows, but that path is experimental.

diagnose is intended for macOS and Linux only. On Windows, it shows a warning and only produces a best-effort report.

This section is for contributing to the tool itself. If you only want to pair a socket, you can ignore it.

Install dependencies:

pnpm install

Run the main checks:

pnpm lint
pnpm test

Useful commands:

• pnpm build produces the bundled dist/cli.js artifact used for npm publishing.
• node src/cli.ts pair --ssid "MyWifi" --password "super-secret" runs the pairing flow from source.
• node src/cli.ts diagnose runs the diagnostics flow from source.
• pnpm lint runs linters (cspell, eslint, knip, markdownlint, pnpm dedupe, prettier, and TypeScript).
• pnpm fix applies available autofixes for linters.
• pnpm test runs the hardware-free unit tests.

This project was inspired by darrensteele/s20, a Python tool for pairing Orvibo S20 sockets. That project helped confirm the basic UDP pairing flow, even though it did not work on my setup without further changes.