ThaMunsta/dibby-wemo-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all READMEs for cross-platform support and add wemo-core docs

Browse Source 
- Root README: add Linux x64 + ARM64 download targets, update release
  assets table, document background scheduler differences per OS,
  add wemo-core shared package description, use repo name dibby-wemo-manager
- apps/desktop README: full rewrite covering Windows installer/portable,
  Linux AppImage/.deb/.rpm (x64 + ARM64), all build commands per OS,
  data storage paths per OS, requirements table
- packages/wemo-core: new README documenting all exports, constants,
  helper functions, day number convention, sun sentinel codes
- about.html: fix version string from "2.0" to "2.0.0"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SRS IT
2026-03-28 16:38:31 -04:00
parent 27be1892ed
commit 328a607e28
4 changed files with 276 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+53 -19
View File
@@ -6,7 +6,7 @@ Dibby Wemo Manager gives you full local control of Belkin Wemo smart switches an
| Component | Description | | Component | Description |
|---|---| |---|---|
| 🖥️ **Desktop App** | Windows Electron app — device dashboard, power control, scheduling | | 🖥️ **Desktop App** | Cross-platform Electron app (Windows + Linux) — device dashboard, power control, scheduling |
| 🏠 **Homebridge Plugin** | HomeKit integration with custom scheduling UI inside Homebridge | | 🏠 **Homebridge Plugin** | HomeKit integration with custom scheduling UI inside Homebridge |
Both share the same local-network Wemo protocol (UPnP/SOAP) and the same DWM scheduling engine. No Belkin account, no cloud dependency, no internet required. Both share the same local-network Wemo protocol (UPnP/SOAP) and the same DWM scheduling engine. No Belkin account, no cloud dependency, no internet required.
@@ -16,12 +16,12 @@ Both share the same local-network Wemo protocol (UPnP/SOAP) and the same DWM sch
## Repository Layout ## Repository Layout
``` ```
wemo-manager/ dibby-wemo-manager/
├── apps/ ├── apps/
│ └── desktop/ # Electron desktop app (Windows) │ └── desktop/ # Electron desktop app (Windows + Linux)
├── packages/ ├── packages/
│ ├── homebridge-plugin/ # homebridge-dibby-wemo Homebridge plugin │ ├── homebridge-plugin/ # homebridge-dibby-wemo Homebridge plugin
│ └── wemo-core/ # Shared Wemo protocol helpers │ └── wemo-core/ # Shared Wemo protocol helpers (internal)
└── package.json # npm workspaces root └── package.json # npm workspaces root
``` ```
@@ -29,14 +29,24 @@ wemo-manager/
## Quick Start ## Quick Start
### Desktop App (Windows) ### Desktop App
Download the latest installer from [Releases](../../releases): Download the latest installer from [Releases](../../releases):
**Windows:**
- **`Dibby Wemo Manager Setup 2.0.0.exe`** — NSIS installer (recommended) - **`Dibby Wemo Manager Setup 2.0.0.exe`** — NSIS installer (recommended)
- **`Dibby Wemo Manager 2.0.0.exe`** — Portable single-file executable - **`Dibby Wemo Manager 2.0.0.exe`** — Portable single-file executable
Run the installer, launch the app. Wemo devices are discovered automatically via SSDP on your local network. **Linux (x64):**
- **`Dibby Wemo Manager-2.0.0.AppImage`** — Universal AppImage, runs anywhere
- **`dibby-wemo-manager_2.0.0_amd64.deb`** — Debian / Ubuntu
- **`dibby-wemo-manager-2.0.0.x86_64.rpm`** — Fedora / RHEL
**Linux (ARM64 — Raspberry Pi 4/5):**
- **`Dibby Wemo Manager-2.0.0-arm64.AppImage`**
- **`dibby-wemo-manager_2.0.0_arm64.deb`**
Run the installer (Windows) or AppImage (Linux). Wemo devices are discovered automatically via SSDP on your local network.
### Homebridge Plugin ### Homebridge Plugin
@@ -74,10 +84,14 @@ Restart Homebridge. Devices appear in HomeKit automatically.
- **Always On** — enforce a device stays on; auto-corrects within 10 seconds - **Always On** — enforce a device stays on; auto-corrects within 10 seconds
- **Trigger** — IFTTT-style: when device A changes state, control device B - **Trigger** — IFTTT-style: when device A changes state, control device B
- **Native firmware rules** — read, toggle and delete rules stored on the Wemo device itself - **Native firmware rules** — read, toggle and delete rules stored on the Wemo device itself
- **Standalone service** — Windows background service that enforces rules even when the GUI is closed - **Background scheduler** — keeps rules firing even when the GUI is closed
- Windows: native Windows service (`DibbyWemoService`)
- Linux: background process, runs while app is in system tray
- **Web remote** — optional local web interface accessible from your phone - **Web remote** — optional local web interface accessible from your phone
- **Sunrise/sunset support** — location-aware scheduling via city search - **Sunrise/sunset support** — location-aware scheduling via city search
**Platforms:** Windows 10+ (x64) · Linux x64 · Linux ARM64 (Raspberry Pi 4/5)
### 🏠 Homebridge Plugin ### 🏠 Homebridge Plugin
- All Wemo devices registered as **HomeKit switches** - All Wemo devices registered as **HomeKit switches**
@@ -141,13 +155,17 @@ The Wemo device stores rules in a SQLite database inside a ZIP archive:
The DWM (Dibby Wemo Manager) scheduler is a Node.js process that: The DWM (Dibby Wemo Manager) scheduler is a Node.js process that:
- Loads rules from a JSON store (`dibby-wemo.json`) - Loads rules from a JSON store
- Ticks every **30 seconds**, reloading rules on each tick (live edits take effect without restart) - Ticks every **30 seconds**, reloading rules on each tick (live edits take effect without restart)
- Pre-schedules events within a **65-second look-ahead window** - Pre-schedules events within a **65-second look-ahead window**
- On startup, catches up any rules missed within the last **10 minutes** - On startup, catches up any rules missed within the last **10 minutes**
- Runs a **health monitor** every 10 seconds for AlwaysOn and Trigger rules - Runs a **health monitor** every 10 seconds for AlwaysOn and Trigger rules
- Writes a **heartbeat** to the store on every tick so the UI can show scheduler status - Writes a **heartbeat** to the store on every tick so the UI can show scheduler status
### Shared Core
`packages/wemo-core` contains shared constants and utilities (day numbers, time conversions, sunrise/sunset calculator) used by both the desktop app and the Homebridge plugin without duplication. It is an internal npm workspace package, not published to npm.
--- ---
## Development ## Development
@@ -157,10 +175,10 @@ The DWM (Dibby Wemo Manager) scheduler is a Node.js process that:
- Node.js ≥ 18 - Node.js ≥ 18
- npm ≥ 9 - npm ≥ 9
### Install dependencies ### Install all dependencies
```bash ```bash
# From repo root # From repo root — installs all workspaces
npm install npm install
``` ```
@@ -171,16 +189,27 @@ cd apps/desktop
npm run dev npm run dev
``` ```
### Desktop App — build Windows installer ### Desktop App — build
```bash ```bash
# Windows installer + portable exe
cd apps/desktop cd apps/desktop
npm run build:win npm run build:win
# Linux AppImage + .deb + .rpm (x64)
cd apps/desktop
npm run build:linux
# Linux ARM64 (Raspberry Pi)
cd apps/desktop
npm run build:linux:arm64
# Windows x64 + Linux x64 in one command
cd apps/desktop
npm run build:all
``` ```
Output in `apps/desktop/dist/`: Output in `apps/desktop/dist/`.
- `Dibby Wemo Manager Setup 2.0.0.exe` — NSIS installer
- `Dibby Wemo Manager 2.0.0.exe` — portable EXE
### Homebridge Plugin — install locally ### Homebridge Plugin — install locally
@@ -197,11 +226,16 @@ Then restart Homebridge.
Each [GitHub Release](../../releases) includes: Each [GitHub Release](../../releases) includes:
| File | Description | | File | OS | Description |
|---|---| |---|---|---|
| `Dibby Wemo Manager Setup 2.0.0.exe` | Windows NSIS installer (recommended) | | `Dibby Wemo Manager Setup 2.0.0.exe` | Windows | NSIS installer (recommended) |
| `Dibby Wemo Manager 2.0.0.exe` | Windows portable executable | | `Dibby Wemo Manager 2.0.0.exe` | Windows | Portable executable |
| `homebridge-dibby-wemo-1.0.0.tgz` | Homebridge plugin npm package | | `Dibby Wemo Manager-2.0.0.AppImage` | Linux x64 | Universal AppImage |
| `dibby-wemo-manager_2.0.0_amd64.deb` | Linux x64 | Debian / Ubuntu package |
| `dibby-wemo-manager-2.0.0.x86_64.rpm` | Linux x64 | Fedora / RHEL package |
| `Dibby Wemo Manager-2.0.0-arm64.AppImage` | Linux ARM64 | Raspberry Pi 4/5 AppImage |
| `dibby-wemo-manager_2.0.0_arm64.deb` | Linux ARM64 | Raspberry Pi OS package |
| `homebridge-dibby-wemo-1.0.0.tgz` | Any | Homebridge plugin npm package |
--- ---
apps/desktop/README.md
+104 -27
View File
@@ -1,8 +1,10 @@
# Dibby Wemo Manager — Desktop App # Dibby Wemo Manager — Desktop App
**Windows desktop application for local Belkin Wemo control.** **Cross-platform desktop application for local Belkin Wemo control.**
Full device dashboard, power control, scheduling engine, Windows background service, and optional web remote — all communicating directly with your Wemo devices over your local network. No Belkin cloud account required. Full device dashboard, power control, scheduling engine, and optional web remote — all communicating directly with your Wemo devices over your local network. No Belkin cloud account required.
On Windows the scheduler can run as a background service so rules keep firing after the GUI is closed. Linux uses a background process instead.
--- ---
@@ -10,6 +12,8 @@ Full device dashboard, power control, scheduling engine, Windows background serv
Download the latest release from [GitHub Releases](../../releases): Download the latest release from [GitHub Releases](../../releases):
### Windows
| File | Description | | File | Description |
|---|---| |---|---|
| `Dibby Wemo Manager Setup 2.0.0.exe` | **NSIS installer** — recommended, installs to Program Files, adds Start Menu shortcut | | `Dibby Wemo Manager Setup 2.0.0.exe` | **NSIS installer** — recommended, installs to Program Files, adds Start Menu shortcut |
@@ -17,6 +21,32 @@ Download the latest release from [GitHub Releases](../../releases):
Run the installer or portable exe. The app opens and immediately begins discovering Wemo devices on your network. Run the installer or portable exe. The app opens and immediately begins discovering Wemo devices on your network.
### Linux
| File | Description |
|---|---|
| `Dibby Wemo Manager-2.0.0.AppImage` | **AppImage** — universal, runs on any modern Linux distro. No install needed. |
| `dibby-wemo-manager_2.0.0_amd64.deb` | **Debian / Ubuntu** package |
| `dibby-wemo-manager-2.0.0.x86_64.rpm` | **Fedora / RHEL / openSUSE** package |
| `Dibby Wemo Manager-2.0.0-arm64.AppImage` | **AppImage (ARM64)** — Raspberry Pi 4/5, Apple Silicon VMs |
| `dibby-wemo-manager_2.0.0_arm64.deb` | **Debian ARM64** — Raspberry Pi OS |
**AppImage:**
```bash
chmod +x "Dibby Wemo Manager-2.0.0.AppImage"
./"Dibby Wemo Manager-2.0.0.AppImage"
```
**Debian / Ubuntu (.deb):**
```bash
sudo dpkg -i dibby-wemo-manager_2.0.0_amd64.deb
```
**Fedora / RHEL (.rpm):**
```bash
sudo rpm -i dibby-wemo-manager-2.0.0.x86_64.rpm
```
--- ---
## Features ## Features
@@ -57,39 +87,48 @@ Read and manage rules stored directly on the Wemo device's own firmware:
> Wemo Dimmer V2 (WDS060) with newer RTOS firmware does not support firmware rule editing. > Wemo Dimmer V2 (WDS060) with newer RTOS firmware does not support firmware rule editing.
### 🛠️ Windows Background Service
The DWM scheduler can run as a **Windows service** (`DibbyWemoService`) so rules continue to fire even when the GUI is closed or the user logs out.
- Install/uninstall the service from the app's System tab
- The service reads rules from the shared data directory and syncs automatically when rules are saved in the GUI
- Service uses `node-windows` for reliable Windows service registration
### 🌐 Web Remote ### 🌐 Web Remote
Optional local web interface accessible from any device on your network (phone, tablet, another PC): Optional local web interface accessible from any device on your network (phone, tablet, another PC):
- View device status - View device status
- Toggle devices on/off - Toggle devices on/off
- Manage DWM rules
- QR code for easy mobile access - QR code for easy mobile access
- Configurable port; firewall rule created automatically (UAC prompt) - Configurable port; firewall rule created automatically on Windows (UAC prompt)
### 📍 Sunrise/Sunset Scheduling ### 📍 Sunrise/Sunset Scheduling
Set your city in the Settings tab. Schedule rules can then use local sunrise and sunset times as start/end points. Set your city in the Settings tab. Schedule rules can then use local sunrise and sunset times as start/end points.
### 🛠️ Background Scheduler
The DWM scheduler continues running rules even when the main window is closed.
**Windows** — installs as a native **Windows Service** (`DibbyWemoService`) via `node-windows`:
- Install/uninstall from the System tab
- The service reads rules from `C:\ProgramData\DibbyWemoManager\dwm-rules.json`
- Syncs automatically when rules are saved in the GUI
**Linux** — the scheduler runs as a background process spawned from the main Electron process. It continues running while the app is in the system tray.
--- ---
## Data Storage ## Data Storage
All app data is stored in `%APPDATA%\DibbyWemoManager\` (typically `C:\Users\<you>\AppData\Roaming\DibbyWemoManager\`): All app data is stored in the OS user-data directory:
| OS | Path |
|---|---|
| Windows | `%APPDATA%\DibbyWemoManager\` |
| Linux | `~/.config/DibbyWemoManager/` |
| File | Description | | File | Description |
|---|---| |---|---|
| `wemo-manager.json` | App settings, discovered devices, DWM rules | | `wemo-manager.json` | App settings, discovered devices, DWM rules |
| `dwm-rules.json` | DWM rules shared with the Windows background service | | `dwm-rules.json` | DWM rules shared with the background scheduler |
The standalone service reads `C:\ProgramData\DibbyWemoManager\dwm-rules.json`. The GUI syncs rules to this location after every create, update, or delete. On Windows the standalone service reads `C:\ProgramData\DibbyWemoManager\dwm-rules.json`. The GUI syncs rules to this location after every create, update, or delete.
--- ---
@@ -102,7 +141,7 @@ Electron Main Process
├── store.js — JSON persistence layer ├── store.js — JSON persistence layer
├── firewall.js — Windows Firewall rule management (elevated) ├── firewall.js — Windows Firewall rule management (elevated)
├── web-server.js — Express web remote server ├── web-server.js — Express web remote server
├── service-manager.js— node-windows service install/uninstall ├── service-manager.js— node-windows service install/uninstall (Windows)
└── ipc/ └── ipc/
├── devices.ipc.js ├── devices.ipc.js
├── rules.ipc.js ├── rules.ipc.js
@@ -116,7 +155,7 @@ Electron Renderer (React 18 + Zustand)
├── AllRulesTab — Native firmware rules per device ├── AllRulesTab — Native firmware rules per device
└── Settings — location, service, web remote config └── Settings — location, service, web remote config
Standalone Service (scheduler-standalone.js) Standalone Scheduler (scheduler-standalone.js)
└── Runs headless; reads dwm-rules.json; same scheduling logic └── Runs headless; reads dwm-rules.json; same scheduling logic
``` ```
@@ -141,7 +180,7 @@ Native firmware rules are stored in a SQLite database (`temppluginRules.db`) ins
- Node.js ≥ 18 - Node.js ≥ 18
- npm ≥ 9 - npm ≥ 9
- Windows (for Windows builds) - OS-specific toolchain (see below)
### Install dependencies ### Install dependencies
@@ -163,29 +202,67 @@ npm run dev
Opens the Electron app with hot-reload for the renderer. Opens the Electron app with hot-reload for the renderer.
### Production build ### Production builds
#### Windows (NSIS installer + portable exe)
Run on a Windows machine:
```bash ```bash
cd apps/desktop cd apps/desktop
npm run build:win npm run build:win
``` ```
This: Output in `apps/desktop/dist/`:
1. Compiles the renderer with `electron-vite` - `Dibby Wemo Manager Setup 2.0.0.exe` — NSIS installer
2. Bundles the standalone service script - `Dibby Wemo Manager 2.0.0.exe` — portable exe
3. Runs `electron-builder` to produce the NSIS installer and portable exe
Output appears in `apps/desktop/dist/`. > **Code signing:** The build config expects a PFX certificate at `resources/srsit-codesign.pfx`. Remove the `win.certificateFile` entry from `package.json` if you don't have a certificate.
> **Code signing:** The build configuration expects a PFX certificate at `resources/srsit-codesign.pfx`. Remove the `win.certificateFile` entry from `package.json` if you don't have a certificate. #### Linux x64 (AppImage + .deb + .rpm)
Run on a Linux machine or in WSL2 / CI:
```bash
cd apps/desktop
npm run build:linux
```
Output in `apps/desktop/dist/`:
- `Dibby Wemo Manager-2.0.0.AppImage`
- `dibby-wemo-manager_2.0.0_amd64.deb`
- `dibby-wemo-manager-2.0.0.x86_64.rpm`
#### Linux ARM64 (Raspberry Pi / Apple Silicon)
```bash
cd apps/desktop
npm run build:linux:arm64
```
Output in `apps/desktop/dist/`:
- `Dibby Wemo Manager-2.0.0-arm64.AppImage`
- `dibby-wemo-manager_2.0.0_arm64.deb`
#### All targets at once
```bash
cd apps/desktop
npm run build:all
```
Builds Windows x64 and Linux x64 targets in sequence. Requires the build host to have `wine` installed (for Windows cross-compilation on Linux), or run each command on its native OS.
--- ---
## Requirements ## Requirements
- Windows 10 or later (x64) | Component | Windows | Linux |
- Node.js ≥ 18 (only needed for building from source) |---|---|---|
- Wemo devices on the same LAN | OS | Windows 10 or later (x64) | Any modern distro (x64 or ARM64) |
| Node.js | ≥ 18 (build only) | ≥ 18 (build only) |
| Runtime deps | None — bundled | `libgtk-3`, `libnss3`, `libxss1` (auto via .deb) |
| Wemo devices | Same LAN | Same LAN |
--- ---
apps/desktop/resources/about.html
+1 -1
View File
@@ -104,7 +104,7 @@
<img src="icon.png" alt="Dibby Wemo Manager" /> <img src="icon.png" alt="Dibby Wemo Manager" />
<div class="header-text"> <div class="header-text">
<h1>Dibby Wemo Manager</h1> <h1>Dibby Wemo Manager</h1>
<div class="version">Version 2.0</div> <div class="version">Version 2.0.0</div>
</div> </div>
</div> </div>
<p class="desc"> <p class="desc">
packages/wemo-core/README.md
+118
View File
@@ -0,0 +1,118 @@
# @wemo-manager/core
**Shared Wemo protocol constants and utilities used by both the Dibby Wemo Manager desktop app and the Homebridge plugin.**
This is an internal package within the `dibby-wemo-manager` monorepo. It is not published to npm — both packages reference it via npm workspaces.
---
## What's in here
### Constants
| Export | Description |
|---|---|
| `DAY_NUMBERS` | Map of day names → Wemo day numbers (Monday=1 … Sunday=7) |
| `DAY_NAMES` | Map of Wemo day numbers → full names |
| `DAY_SHORT` | Map of Wemo day numbers → abbreviated names (Mon, Tue…) |
| `RULE_TYPES` | Wemo firmware rule type strings (Schedule, Away, Countdown, Long Press) |
| `ACTIONS` | StartAction / EndAction numeric codes (ON=1, OFF=0, TOGGLE=2, NONE=-1) |
| `NETWORK_STATUS` | GetNetworkStatus response codes |
| `RESET_CODES` | ReSetup action codes (clear data, factory reset, clear WiFi) |
| `RD_DEFAULTS` | Default field values for a new RULEDEVICES row |
| `SUN_CODES` | Sentinel values for sunrise (−2) and sunset (−3) in StartTime/EndTime |
### Helper functions
| Function | Signature | Description |
|---|---|---|
| `namesToDayNumbers` | `(names: string[]) => number[]` | Convert day name array to sorted Wemo day numbers |
| `dayNumbersToNames` | `(numbers: number[]) => string[]` | Convert day numbers to full name array |
| `dayNumbersToShort` | `(numbers: number[]) => string[]` | Convert day numbers to abbreviated name array |
| `timeToSecs` | `(hhmm: string) => number` | Parse `"HH:MM"` to seconds from midnight |
| `secsToHHMM` | `(secs: number) => string` | Format seconds from midnight to `"HH:MM"` |
| `sunTimes` | `(lat, lng, date?) => { sunrise, sunset }` | Calculate sunrise/sunset as seconds from midnight |
---
## Wemo day number convention
Wemo devices use **1-based day numbers**, not bitmasks:
| Number | Day |
|---|---|
| 1 | Monday |
| 2 | Tuesday |
| 3 | Wednesday |
| 4 | Thursday |
| 5 | Friday |
| 6 | Saturday |
| 7 | Sunday |
Multi-day rules have one `RULEDEVICES` row **per day** — not a single row with a bitmask.
---
## Sun time sentinel codes
When a rule's `StartTime` or `EndTime` is set to one of these values, the scheduler resolves it to the actual sunrise/sunset time for the configured location:
| Constant | Value | Meaning |
|---|---|---|
| `SUN_CODES.SUNRISE` | `-2` | Use today's sunrise time |
| `SUN_CODES.SUNSET` | `-3` | Use today's sunset time |
---
## Usage
```js
const {
DAY_NUMBERS,
namesToDayNumbers,
secsToHHMM,
sunTimes,
SUN_CODES,
} = require('@wemo-manager/core');
// Convert user-selected days to Wemo day numbers
const days = namesToDayNumbers(['Monday', 'Wednesday', 'Friday']);
// → [1, 3, 5]
// Format a time stored as seconds from midnight
console.log(secsToHHMM(75600)); // "21:00" (9 PM)
// Check if a StartTime is a sunrise/sunset sentinel
if (startTime === SUN_CODES.SUNRISE) {
const { sunrise } = sunTimes(lat, lng);
startTime = sunrise;
}
```
---
## File structure
```
packages/wemo-core/
├── package.json
└── src/
├── index.js — re-exports everything from sun.js and types.js
├── types.js — constants + day/time helper functions
└── sun.js — NOAA sunrise/sunset calculator (pure JS, no deps)
```
---
## Notes
- **No external dependencies** — pure JavaScript, no npm packages required.
- `sun.js` implements the NOAA Solar Calculator algorithm (Jean Meeus, *Astronomical Algorithms*). It returns `null` for each value during polar day/polar night.
- `secsToHHMM` returns `"00:00"` for negative input (used for no-time sentinel values like `−1`).
- The DWM scheduler in both the desktop app and the Homebridge plugin uses `SUN_CODES` to resolve rule times at tick time, so sunrise/sunset-based rules automatically adjust every day.
---
## License
MIT