Add Matter support via publishMatterAccessories API with external accessories compatibility (#186)

Author: Copilot

.changeset/evil-impalas-juggle.md

@@ -0,0 +1,5 @@
+---
+"@homebridge-plugins/homebridge-roomba": minor
+---
+
+Add external accessories support for Matter compatibility

.changeset/stale-paths-open.md

@@ -0,0 +1,5 @@
+---
+"@homebridge-plugins/homebridge-roomba": patch
+---
+
+Add accessory category configuration option and document iOS 18 vacuum support limitations

.github/copilot-instructions.md

@@ -4,6 +4,68 @@ Homebridge plugin for iRobot Roomba vacuum cleaners. This is a TypeScript-based
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+## PR Workflow and Beta Branch Requirements
+
+### Branch Targeting Strategy
+**ALL PULL REQUESTS MUST TARGET A BETA BRANCH FIRST** - never target the `latest` branch directly.
+
+1. **Check for existing beta branch**: Look for branches starting with `beta-` (e.g., `beta-2.1.1`, `beta-2.2.0`)
+2. **If no beta branch exists**: Create one based on the next possible version according to semantic versioning
+3. **Target the beta branch**: Always target your PR to the appropriate beta branch
+
+### Version Label Requirements
+**CRITICAL**: Before assigning any issue to Copilot, one of these labels MUST be set to determine the version increment:
+
+- **`patch`** - For bug fixes (2.1.0 → 2.1.1)
+- **`minor`** - For new features (2.1.0 → 2.2.0) 
+- **`major`** - For breaking changes (2.1.0 → 3.0.0)
+
+**No work should begin without the appropriate version label being assigned first.**
+
+### Beta Branch Creation Process
+If no appropriate beta branch exists:
+
+1. **For patch changes**: Create `beta-X.Y.Z+1` (e.g., if current is 2.1.0, create `beta-2.1.1`)
+2. **For minor changes**: Create `beta-X.Y+1.0` (e.g., if current is 2.1.0, create `beta-2.2.0`)  
+3. **For major changes**: Create `beta-X+1.0.0` (e.g., if current is 2.1.0, create `beta-3.0.0`)
+
+```bash
+# Example: Creating a beta branch for a minor feature
+git checkout latest
+git pull origin latest
+git checkout -b beta-2.2.0
+git push origin beta-2.2.0
+```
+
+**Current State**: As of this writing, the current release is 2.1.0 and there is an existing `beta-2.1.1` branch for patch releases.
+
+### Examples of Branch Targeting
+- **Bug fix (patch label)** → Target `beta-2.1.1` (if exists) or create it
+- **New feature (minor label)** → Target `beta-2.2.0` (create if needed)
+- **Breaking change (major label)** → Target `beta-3.0.0` (create if needed)
+
+### Workflow Summary
+1. ✅ Check issue has `patch`, `minor`, or `major` label assigned
+2. ✅ Identify or create appropriate beta branch
+3. ✅ Target PR to beta branch (not `latest`)
+4. ✅ Follow normal development workflow below
+5. ✅ Use changesets to document your changes (see Publishing Workflow section)
+
+### Integration with Changesets
+This project uses [Changesets](https://github.com/changesets/changesets) for version management. When making changes:
+
+1. **Create a changeset** describing your change:
+   ```bash
+   npm exec changeset
+   ```
+2. **Select the change type** that matches your issue label:
+   - Patch → patch (bug fixes)
+   - Minor → minor (new features) 
+   - Major → major (breaking changes)
+3. **Commit the changeset file** as part of your PR
+
+The changeset type should align with the issue label that was set before assignment.
+
 ## Working Effectively
 
 ### Bootstrap and Build Process
@@ -34,8 +96,18 @@ Key build commands with validated timings:
 - `npm run docs:theme` - Generate docs with default-modern theme
 
 ### Publishing Workflow
+
+This project uses Changesets for version management and release automation:
+
+- `npm exec changeset` - Create a changeset describing your changes (do this for each PR)
+- `npm exec changeset version` - Update package.json and CHANGELOG.md (maintainer only)
+- `npm exec changeset publish` - Publish to npm (maintainer only)
 - `npm run prepublishOnly` - Complete CI workflow: lint + build + docs. Takes ~15 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
 
+**For Contributors**: Always create a changeset when making changes. The type (patch/minor/major) should match the issue label.
+
+**Beta Release Process**: Beta versions are automatically published from beta branches. When a beta branch is ready, it gets merged to `latest` for stable release.
+
 ## Validation
 
 ### Manual Testing Requirements

EXTERNAL_ACCESSORIES.md

@@ -0,0 +1,136 @@
+# External Accessories and Matter Support
+
+This plugin now supports publishing each Roomba as an external accessory with automatic Matter compatibility detection. When using Homebridge 2.0.0-alpha.28 or later, the plugin will automatically use the new `publishMatterAccessories` API for enhanced Matter support.
+
+## What are External Accessories?
+
+**Platform Accessories** (default behavior):
+- All Roomba devices appear under a single "Roomba" bridge
+- Devices are grouped together in the Home app
+- Traditional Homebridge plugin behavior
+
+**External Accessories** (new feature):
+- Each Roomba appears as a separate, independent device in HomeKit
+- Automatic Matter protocol support when available (Homebridge alpha.28+)
+- Better compatibility with Matter bridging protocols
+- Future-proof for advanced HomeKit/Matter features
+
+## Configuration
+
+Add the `externalAccessories` option to your platform configuration:
+
+```json
+{
+  "platform": "Roomba",
+  "name": "Roomba",
+  "email": "[email protected]", 
+  "password": "your-password",
+  "externalAccessories": true
+}
+```
+
+## Matter Support Detection
+
+The plugin automatically detects and uses the best available API:
+
+- **Homebridge 2.0.0-alpha.28+**: Uses `publishMatterAccessories` for native Matter protocol support
+- **Older versions**: Falls back to `publishExternalAccessories` for standard external accessory behavior
+
+This ensures compatibility across all supported Homebridge versions while providing Matter support when available.
+
+## Benefits of External Accessories
+
+### Matter Compatibility
+- **Automatic Matter support** when using Homebridge alpha versions with Matter capabilities
+- Each device can be individually exposed to Matter networks
+- Better integration with Thread/Matter ecosystems
+- Prepares for future Matter protocol enhancements
+
+### Individual Device Management
+- Each Roomba appears as a separate tile in the Home app
+- Independent device management and troubleshooting
+- Cleaner organization in larger smart home setups
+
+### Enhanced Reliability
+- If one Roomba has connectivity issues, it doesn't affect others
+- Individual device restarts and management
+- Reduced dependency on the main bridge
+
+## Migration Notes
+
+### Switching from Platform to External Accessories
+1. **Backup your current setup** - Export your Home app configuration
+2. **Update plugin configuration** - Add `"externalAccessories": true`
+3. **Restart Homebridge** - The devices will appear as new accessories
+4. **Re-add to Home app** - You'll need to scan the new QR codes
+5. **Reconfigure automations** - Update any scenes/automations using the old accessories
+
+### Important Considerations
+- External accessories require individual pairing in the Home app
+- Each external accessory has its own HomeKit pairing code
+- Switching modes will require re-pairing all devices
+- Existing automations and scenes will need to be recreated
+
+## Matter Support Preparation
+
+This feature prepares your Roomba devices for future Matter support:
+
+### Current Status
+- **HomeKit HAP**: Full support with external accessories
+- **Matter**: Ready for future Homebridge Matter implementation
+- **iOS 18 Vacuum Features**: Matter-only (not available in HomeKit HAP)
+
+### Future Roadmap
+When Homebridge adds full Matter support:
+- External accessories will be easier to bridge to Matter
+- Individual device control via Matter controllers
+- Enhanced iOS 18 vacuum features when bridged to Matter
+
+## Troubleshooting
+
+### Accessories Not Appearing
+1. Check Homebridge logs for errors
+2. Ensure `externalAccessories: true` is set
+3. Restart Homebridge completely
+4. Check QR codes in Homebridge UI
+
+### Re-pairing Issues  
+1. Reset HomeKit database if needed: `homebridge-config-ui-x > Settings > Reset Accessory Cache`
+2. Clear iOS Home app cache: Remove and re-add the Home
+3. Check Homebridge logs for pairing errors
+
+### Performance Considerations
+- External accessories may use slightly more system resources
+- Each device maintains its own connection state
+- Monitor Homebridge performance if you have many devices
+
+## Advanced Configuration
+
+You can combine external accessories with other plugin features:
+
+```json
+{
+  "platform": "Roomba",
+  "name": "Roomba", 
+  "email": "[email protected]",
+  "password": "your-password",
+  "externalAccessories": true,
+  "devices": [
+    {
+      "name": "Kitchen Roomba",
+      "blid": "your-blid",
+      "robotpwd": "your-password", 
+      "ipaddress": "192.168.1.100",
+      "accessoryCategory": "switch",
+      "dockContactSensor": true,
+      "runningContactSensor": true
+    }
+  ]
+}
+```
+
+## Related Documentation
+
+- [Main README](./README.md) - General plugin setup and configuration
+- [iOS 18 Vacuum Support](./iOS18_VACUUM_SUPPORT.md) - Matter vs HomeKit vacuum limitations
+- [Homebridge External Accessories Documentation](https://developers.homebridge.io/#/api/platform-accessories?id=external-accessories)

README.md

@@ -114,6 +114,31 @@ Here is example JSON for configuring a Roomba accessory:
 | `user_pmapv_id`        | The version id of your map in the iRobot app (contains Date and Time last modified) |               |
 | `stopBehaviour`        | Roomba can go home or pause when stopped                                            | `home`        |
 
+### External Accessories & Matter Support
+
+This plugin supports **External Accessories** mode, which publishes each Roomba as a separate HomeKit device instead of grouping them under a bridge. This feature provides:
+
+- **Automatic Matter Support**: Uses `publishMatterAccessories` API when available (Homebridge 2.0.0-alpha.28+)
+- **Individual Device Management**: Each Roomba appears as a separate tile in the Home app  
+- **Enhanced Reliability**: Independent device management and troubleshooting
+- **Future-Proof**: Ready for Matter protocol expansion
+
+To enable external accessories, add `"externalAccessories": true` to your platform configuration:
+
+```json
+{
+  "platform": "Roomba",
+  "name": "Roomba",
+  "email": "[email protected]",
+  "password": "your-password", 
+  "externalAccessories": true
+}
+```
+
+**Important**: Switching to external accessories requires re-pairing all devices and recreating scenes/automations.
+
+📖 For detailed information, see [External Accessories Documentation](./EXTERNAL_ACCESSORIES.md)
+
 ### Cleaning Mission configuration
 
 This plugin can instruct the Roomba to clean everywhere or go on a specific cleaning job when started. Follow these steps to get the mission configuration values from the iRobot app.

config.schema.json

@@ -39,6 +39,13 @@
                 "description": "Disable automatic discovery of Roomba devices. If you have multiple Roomba devices, you can disable discovery and manually configure each device.",
                 "required": false
             },
+            "externalAccessories": {
+                "type": "boolean",
+                "title": "External Accessories",
+                "description": "Publish each Roomba as an external accessory instead of platform accessories. External accessories appear as separate devices in HomeKit and support Matter bridging.",
+                "required": false,
+                "default": false
+            },
             "devices": {
                 "type": "array",
                 "items": {
@@ -232,6 +239,33 @@
                             "title": "Idle Poll Interval (minutes)",
                             "description": "How often to poll Roomba's status when it is idle. Defaults to 15 minutes.",
                             "required": false
+                        },
+                        "accessoryCategory": {
+                            "type": "string",
+                            "title": "HomeKit Accessory Category",
+                            "description": "Note: iOS 18 vacuum support is Matter-only, not HomeKit HAP. This setting only affects the accessory icon.",
+                            "default": "other",
+                            "required": false,
+                            "oneOf": [
+                                {
+                                    "title": "Other (Generic)",
+                                    "enum": [
+                                        "other"
+                                    ]
+                                },
+                                {
+                                    "title": "Switch",
+                                    "enum": [
+                                        "switch"
+                                    ]
+                                },
+                                {
+                                    "title": "Sensor",
+                                    "enum": [
+                                        "sensor"
+                                    ]
+                                }
+                            ]
                         }
                     }
                 }