homebridge-navimow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LeiterConsulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Navimow for Homebridge
+
+![Navimow icon](https://raw.githubusercontent.com/LeiterConsulting/navimowhb/main/homebridge-ui/public/navimow-icon.svg)
+
+Monitor and control Navimow robotic mowers from HomeKit through Homebridge.
+
+This repository ships a Homebridge platform plugin backed by a small Python bridge that talks to the Navimow cloud and MQTT services.
+
+## Features
+
+### Mower control
+
+Control each mower from HomeKit with:
+
+* `Mowing` switch for start, pause, and resume
+* `Dock` switch for return-to-base
+* `Stop` switch for immediate stop
+
+### Device monitoring
+
+Track live mower telemetry through Homebridge:
+
+* real-time mower status
+* battery level in HomeKit
+* command confirmation in the plugin UI
+* richer diagnostics and mower metadata in the custom Homebridge page
+
+### Runtime design
+
+The plugin uses a split runtime:
+
+* TypeScript Homebridge dynamic platform in `src/`
+* Python bridge in `bridge/navimow_bridge.py`
+* local OAuth callback hosted on the Homebridge machine
+* MQTT push updates with HTTP fallback when the live feed goes stale
+
+## Requirements
+
+* Homebridge 1.8 or newer
+* Node.js version supported by Homebridge: 18, 20, 22, or 24
+* Python 3.11 or newer
+* Python packages `navimow-sdk` and `aiohttp` installed in the configured interpreter
+* A Navimow account that can sign in to the official mobile app
+
+## Install For Development
+
+Install Node dependencies:
+
+```bash
+npm install
+```
+
+Install Python bridge dependencies into the interpreter Homebridge will use:
+
+```bash
+python3 -m pip install navimow-sdk aiohttp
+```
+
+Build the plugin:
+
+```bash
+npm run build
+```
+
+Package it for installation into another Homebridge host:
+
+```bash
+npm pack
+```
+
+Prepare and validate an npm release locally:
+
+```bash
+npm publish --dry-run
+```
+
+## Project Links
+
+* Repository: https://github.com/LeiterConsulting/navimowhb
+* Issues: https://github.com/LeiterConsulting/navimowhb/issues
+* Release checklist: `PUBLISHING.md`
+
+## Homebridge Configuration
+
+The plugin includes both a Homebridge config schema and a custom setup UI, so most setups can be completed from the Homebridge web interface.
+
+Example `config.json` platform entry:
+
+```json
+{
+  "platform": "NavimowPlatform",
+  "name": "Navimow",
+  "pythonPath": "/absolute/path/to/python3",
+  "authCallbackPort": 47129,
+  "authCallbackHost": "192.168.1.71",
+  "mqttStaleSeconds": 300,
+  "httpFallbackMinIntervalSeconds": 3600,
+  "updateIntervalSeconds": 30
+}
+```
+
+Configuration fields:
+
+* `pythonPath`: Python interpreter with `navimow-sdk` and `aiohttp` installed
+* `pythonBridgePath`: optional override for the bridge script path
+* `authCallbackPort`: local HTTP port used for the OAuth callback
+* `authCallbackHost`: optional LAN hostname or IP used instead of `127.0.0.1`
+* `authCallbackBaseUrl`: optional full callback base URL override
+* `tokenStoragePath`: optional override for persisted OAuth tokens
+* `mqttStaleSeconds`: how long MQTT state may remain unchanged before HTTP refresh becomes eligible
+* `httpFallbackMinIntervalSeconds`: minimum delay between HTTP fallback refreshes
+* `updateIntervalSeconds`: polling interval used alongside push updates
+
+## First Login
+
+On first launch, the plugin logs a Navimow login URL.
+
+1. Open the login URL from the Homebridge log.
+2. Sign in with your Navimow account.
+3. Allow the browser to redirect back to the callback URL on the Homebridge host.
+4. The plugin stores the returned tokens and begins mower discovery.
+
+If the callback URL is not reachable from your browser, authentication will not complete.
+
+## HomeKit Mapping
+
+Each discovered mower is exposed as:
+
+* `Mowing` switch
+* `Dock` switch
+* `Stop` switch
+* HomeKit battery service
+
+Command behavior:
+
+* turning `Mowing` on sends `start` or `resume`
+* turning `Mowing` off sends `pause`
+* turning `Dock` on sends `dock` and then resets the switch
+* turning `Stop` on sends `stop` and then resets the switch
+
+The custom Homebridge UI also shows richer telemetry than the Home app, including last plugin command, command status, bridge source, battery details, signal strength, and mower metrics when Navimow reports them.
+
+## Repository Layout
+
+Key paths in this repository:
+
+* `src/`: Homebridge platform, accessories, and bridge client
+* `bridge/navimow_bridge.py`: Python runtime for OAuth, cloud API access, MQTT, and command execution
+* `homebridge-ui/`: custom Homebridge plugin UI
+* `config.schema.json`: Homebridge form schema
+
+## Troubleshooting
+
+Check the Homebridge logs first. Most failures come from one of these conditions:
+
+* the configured Python interpreter does not have `navimow-sdk` installed
+* the callback URL points to an address the browser cannot reach
+* the OAuth response differs from the bridge expectations
+* the host is running a Node.js version unsupported by Homebridge
+
+Useful log lines to capture when diagnosing issues:
+
+* login URL and callback result
+* bridge startup messages
+* command failures
+* MQTT disconnects
+* HTTP fallback warnings
+
+## Notes
+
+This plugin is under active development. The current implementation focuses on reliable authentication, discovery, state updates, command execution, and a better Homebridge operator experience.