homebridge-smartika 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philippe Blondin
+
+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,367 @@
+# Homebridge Smartika
+
+[![npm](https://img.shields.io/npm/v/homebridge-smartika.svg)](https://www.npmjs.com/package/homebridge-smartika)
+[![npm](https://img.shields.io/npm/dt/homebridge-smartika.svg)](https://www.npmjs.com/package/homebridge-smartika)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A [Homebridge](https://homebridge.io) plugin for **Smartika** (Artika) smart home devices with **100% local control** — no cloud required!
+
+## Features
+
+- 🏠 **100% Local Control** — All communication stays on your local network
+- � **Auto-Discovery** — Automatically finds your Smartika hub on the network
+- �💡 **Lights** — On/off, brightness, and color temperature control
+- 🌀 **Ceiling Fans** — On/off and speed control
+- 🔌 **Smart Plugs** — On/off control
+- 🔄 **Real-time Updates** — Device status polling keeps HomeKit in sync
+- 🔐 **Secure** — AES-128-CBC encrypted communication with your hub
+- 🛠️ **CLI Tool** — Command-line interface for debugging and direct control
+
+## Supported Devices
+
+| Category        | Devices                                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Lights**      | Champagne Track, Mini Wall Washer, Glowbox, Recessed Lighting, Pendants (1-5), Smart Bulb, Spotlight, Sandwich Lights |
+| **Fans**        | Ceiling Fan                                                                                                           |
+| **Plugs**       | Smart Plug                                                                                                            |
+| **Thermostats** | Thermostat, Smart Heater *(coming soon)*                                                                              |
+
+## Requirements
+
+- [Homebridge](https://homebridge.io) v1.8.0 or later
+- Node.js v18.20.4, v20.16.0, or v22.5.1+
+- Smartika Hub on your local network
+
+## Installation
+
+### Using Homebridge Config UI X (Recommended)
+
+1. Search for **"Smartika"** in the Plugins tab
+2. Click **Install**
+3. Configure the plugin with your hub's IP address
+
+### Manual Installation
+
+```bash
+sudo npm install -g homebridge-smartika
+```
+
+## Configuration
+
+### Auto-Discovery (Recommended)
+
+The plugin can automatically discover your Smartika hub on the network — no manual configuration needed! Simply install the plugin and restart Homebridge.
+
+The hub broadcasts its presence on UDP port 4156 every ~10 seconds. If auto-discovery doesn't work (e.g., due to network segmentation or firewall rules), you can configure the hub IP manually.
+
+### Finding Your Hub IP Address (Manual)
+
+If auto-discovery doesn't work, find your hub's IP address by:
+
+1. Checking your router's DHCP client list
+2. Using a network scanner app
+3. Looking for a device with MAC address starting with `00:12:4B`
+
+### Using Homebridge Config UI X
+
+1. Go to the **Plugins** tab
+2. Find **Homebridge Smartika** and click **Settings**
+3. Enter your hub's IP address
+4. Click **Save**
+
+### Manual Configuration
+
+Add the following to your `config.json`:
+
+```json
+{
+    "platforms": [
+        {
+            "platform": "Smartika",
+            "name": "Smartika Hub"
+        }
+    ]
+}
+```
+
+With manual hub IP (if auto-discovery doesn't work):
+
+```json
+{
+    "platforms": [
+        {
+            "platform": "Smartika",
+            "name": "Smartika Hub",
+            "hubHost": "10.0.0.122"
+        }
+    ]
+}
+```
+
+With all options:
+
+### Configuration Options
+
+| Option            | Required | Default          | Description                                                  |
+| ----------------- | -------- | ---------------- | ------------------------------------------------------------ |
+| `platform`        | ✅        | —                | Must be `"Smartika"`                                         |
+| `name`            | ❌        | `"Smartika Hub"` | Display name in Homebridge logs                              |
+| `hubHost`         | ❌        | Auto-discover    | IP address of your Smartika hub (auto-discovered if not set) |
+| `hubPort`         | ❌        | `1234`           | TCP port for hub communication                               |
+| `pollingInterval` | ❌        | `5000`           | Status polling interval in milliseconds                      |
+| `debug`           | ❌        | `false`          | Enable verbose debug logging                                 |
+
+## CLI Tool
+
+This plugin includes a powerful command-line interface for direct hub control and debugging.
+
+### Installation
+
+The CLI is installed automatically with the plugin:
+
+```bash
+# If installed globally
+smartika-cli --help
+
+# Or run directly
+npx smartika-cli --help
+```
+
+### Usage
+
+```bash
+# Discover hubs on the network (no IP needed)
+smartika-cli hub-discover
+
+# Run commands on a specific hub
+smartika-cli <hub-ip> <command> [arguments...]
+```
+
+### Examples
+
+```bash
+# Discover Smartika hubs on your network
+smartika-cli hub-discover
+
+# Get hub information (ID, MAC, firmware, encryption key)
+smartika-cli 10.0.0.122 hub-info
+
+# Get status of all devices
+smartika-cli 10.0.0.122 status
+
+# Turn on a device
+smartika-cli 10.0.0.122 on 0x28cf
+
+# Set brightness to 50%
+smartika-cli 10.0.0.122 dim 50% 0x28cf
+
+# Set color temperature (0=warm, 255=cool)
+smartika-cli 10.0.0.122 temp 128 0x28cf
+
+# List registered devices
+smartika-cli 10.0.0.122 list
+
+# Get firmware version
+smartika-cli 10.0.0.122 firmware
+
+# Preview what devices will appear in HomeKit
+smartika-cli 10.0.0.122 homekit-preview
+
+# Interactive pairing wizard for new devices
+smartika-cli 10.0.0.122 pair
+```
+
+### Available Commands
+
+| Category          | Command        | Description                               |
+| ----------------- | -------------- | ----------------------------------------- |
+| **Hub Discovery** | `hub-discover` | Find hubs on the network (no IP needed)   |
+| **System**        | `hub-info`     | Get hub ID, MAC, firmware, encryption key |
+|                   | `ping`         | Send keep-alive ping                      |
+|                   | `firmware`     | Get hub firmware version                  |
+|                   | `join-enable`  | Enable device pairing mode                |
+|                   | `join-disable` | Disable device pairing mode               |
+| **Device**        | `discover`     | Discover active devices                   |
+|                   | `status`       | Get device status                         |
+|                   | `on`           | Turn device(s) on                         |
+|                   | `off`          | Turn device(s) off                        |
+|                   | `dim`          | Set light brightness                      |
+|                   | `temp`         | Set color temperature                     |
+|                   | `fan`          | Set fan speed                             |
+| **Database**      | `list`         | List registered devices                   |
+|                   | `db-add`       | Add device(s) to database                 |
+|                   | `db-remove`    | Remove device(s) from database            |
+| **Groups**        | `groups`       | List all groups                           |
+|                   | `group-read`   | Read group members                        |
+|                   | `group-create` | Create a new group                        |
+|                   | `group-update` | Update group members                      |
+|                   | `group-delete` | Delete group(s)                           |
+| **HomeKit**       | `homekit-preview` | Preview HomeKit accessories            |
+| **Pairing**       | `pair`         | Interactive wizard to pair new devices    |
+
+## Troubleshooting
+
+### Auto-Discovery Not Working
+
+1. **macOS firewall** — On macOS, you may need to allow Node.js to receive incoming connections:
+   - Open **System Settings** → **Network** → **Firewall** → **Options**
+   - Add Node.js (run `which node` to find the path) and set to **Allow incoming connections**
+   - Or run the CLI with `sudo` to bypass the firewall temporarily
+2. **Check firewall** — Ensure UDP port 4156 is not blocked
+3. **Same network** — Hub and Homebridge must be on the same subnet
+4. **Use CLI to test** — Verify discovery works:
+   ```bash
+   # May need sudo on macOS if firewall blocks UDP
+   sudo smartika-cli hub-discover
+   ```
+5. **Fallback to manual** — Configure `hubHost` manually if discovery fails
+
+### Hub Not Connecting
+
+1. **Verify the IP address** — Make sure your hub's IP hasn't changed (consider setting a DHCP reservation)
+2. **Check network connectivity** — Ensure Homebridge can reach the hub: `ping 10.0.0.122`
+3. **Test with CLI** — Use the CLI tool to verify connectivity:
+   ```bash
+   smartika-cli 10.0.0.122 ping
+   ```
+4. **Check firewall** — Ensure port 1234 (TCP) is not blocked
+
+### Devices Not Appearing
+
+1. **Check device registration** — Devices must be registered in the hub's database:
+   ```bash
+   smartika-cli 10.0.0.122 list
+   ```
+2. **Pair new devices** — Use the interactive pairing wizard:
+   ```bash
+   smartika-cli 10.0.0.122 pair
+   ```
+   Or manually discover and add:
+   ```bash
+   smartika-cli 10.0.0.122 discover
+   smartika-cli 10.0.0.122 db-add 0x28cf
+   ```
+3. **Preview HomeKit accessories** — Check what will appear in HomeKit:
+   ```bash
+   smartika-cli 10.0.0.122 homekit-preview
+   ```
+4. **Restart Homebridge** — After adding devices, restart Homebridge to re-discover
+
+### Status Not Updating
+
+1. **Increase polling frequency** — Reduce `pollingInterval` to 2000-3000ms
+2. **Enable debug logging** — Set `"debug": true` to see communication details
+3. **Check for errors** — Look for error messages in Homebridge logs
+
+### Debug Mode
+
+Enable debug logging to see detailed communication:
+
+```json
+{
+    "platform": "Smartika",
+    "hubHost": "10.0.0.122",
+    "debug": true
+}
+```
+
+This will log:
+- Connection status
+- Request/response packets (hex)
+- Device status updates
+- Error details
+
+## Technical Details
+
+### Protocol
+
+The plugin communicates with the Smartika hub using:
+- **Transport**: TCP on port 1234
+- **Encryption**: AES-128-CBC with key derived from hub MAC address
+- **Protocol**: Custom binary protocol with XOR checksum
+
+### Security
+
+- The encryption key is derived from your hub's unique MAC address using 8-pass AES-ECB
+- All commands are encrypted before transmission
+- No data is sent to external servers
+
+### Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│   Apple Home    │────▶│    Homebridge    │────▶│  Smartika   │
+│     (iOS)       │◀────│    Plugin        │◀────│    Hub      │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+        HomeKit              TCP/AES-CBC           Local Network
+```
+
+## Development
+
+### Project Structure
+
+```
+smartika-homebridge/
+├── src/
+│   ├── index.js                 # Plugin entry point
+│   ├── settings.js              # Plugin constants
+│   ├── SmartikaPlatform.js      # Main platform class
+│   ├── SmartikaHubConnection.js # Hub communication
+│   ├── SmartikaCrypto.js        # AES encryption
+│   ├── SmartikaProtocol.js      # Binary protocol
+│   └── accessories/
+│       ├── SmartikaLightAccessory.js
+│       ├── SmartikaFanAccessory.js
+│       └── SmartikaPlugAccessory.js
+├── tools/
+│   └── smartika-cli.js          # CLI tool
+├── test/
+│   ├── test-protocol.js
+│   └── test-crypto.js
+├── config.schema.json           # Homebridge UI schema
+└── package.json
+```
+
+### Building & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/pblondin/smartika-homebridge.git
+cd smartika-homebridge
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+npm run test:crypto
+
+# Lint code
+npm run lint
+
+# Link for local development
+npm link
+```
+
+### Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [Homebridge](https://homebridge.io) team for the amazing platform
+- Smartika/Artika for the hardware
+
+---
+
+**Note**: This plugin is not officially affiliated with or endorsed by Smartika or Artika. Use at your own risk.

package/config.schema.json

@@ -0,0 +1,71 @@
+{
+  "pluginAlias": "Smartika",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge plugin for Smartika smart lighting hub with 100% local communication (no cloud required). Supports lights, fans, and smart plugs. Leave Hub IP empty for auto-discovery.",
+  "footerDisplay": "For help and documentation, see the [GitHub repository](https://github.com/pblondin/smartika-homebridge). Use `smartika-cli hub-discover` to find your hub.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "Smartika Hub",
+        "required": true,
+        "description": "The name that will appear in Homebridge logs."
+      },
+      "hubHost": {
+        "title": "Hub IP Address",
+        "type": "string",
+        "format": "ipv4",
+        "placeholder": "10.0.0.122",
+        "description": "IP address of your Smartika hub. Leave empty for auto-discovery (requires UDP port 4156). Recommended to set a static IP or DHCP reservation."
+      },
+      "hubPort": {
+        "title": "Hub Port",
+        "type": "integer",
+        "default": 1234,
+        "minimum": 1,
+        "maximum": 65535,
+        "description": "TCP port for hub communication (default: 1234)."
+      },
+      "pollingInterval": {
+        "title": "Polling Interval (ms)",
+        "type": "integer",
+        "default": 5000,
+        "minimum": 1000,
+        "maximum": 60000,
+        "description": "How often to poll the hub for device status updates (in milliseconds)."
+      },
+      "debug": {
+        "title": "Debug Mode",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable verbose debug logging for troubleshooting connection issues."
+      }
+    },
+    "required": []
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Hub Connection",
+      "expandable": false,
+      "items": [
+        "name",
+        "hubHost",
+        "hubPort"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced Settings",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "pollingInterval",
+        "debug"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "homebridge-smartika",
+  "displayName": "Homebridge Smartika",
+  "description": "Homebridge plugin for Smartika smart lighting hub with 100% local control (no cloud required). Supports lights, fans, and smart plugs.",
+  "version": "1.0.0",
+  "license": "MIT",
+  "author": "Philippe Blondin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pblondin/homebridge-smartika.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pblondin/homebridge-smartika/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/pblondin"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "smartika",
+    "artika",
+    "homekit",
+    "smart-home",
+    "lighting",
+    "local-control"
+  ],
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "tools/",
+    "config.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^18.20.4 || ^20.16.0 || ^22.5.1",
+    "homebridge": "^1.8.0 || ^2.0.0-beta.0"
+  },
+  "scripts": {
+    "cli": "node tools/smartika-cli.js",
+    "test": "node test/test-protocol.js",
+    "test:crypto": "node test/test-crypto.js",
+    "lint": "eslint src/",
+    "watch": "nodemon",
+    "prepublishOnly": "npm run lint"
+  },
+  "bin": {
+    "smartika-cli": "tools/smartika-cli.js"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "nodemon": "^3.0.0"
+  }
+}

package/src/SmartikaCrypto.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const crypto = require('crypto');
+
+// Constants from hub_security.md
+const PRIVATE_KEY = Buffer.from([
+    0x42, 0x6B, 0xD6, 0xCD, 0x00, 0x59, 0x5B, 0x03, 0xFC, 0xCB, 0xF4, 0xDD, 0x09, 0x25, 0x85, 0x1B,
+    0x3F, 0x91, 0x93, 0x81, 0xB3, 0x19, 0xB2, 0xD1, 0x41, 0x5B, 0xF7, 0x7D, 0xFD, 0x4F, 0x4C, 0xD3,
+    0x5E, 0x00, 0xE1, 0xC0, 0x89, 0xA1, 0x94, 0xD4, 0xF6, 0xEA, 0x77, 0xAA, 0xC5, 0x1B, 0x66, 0x67,
+    0xEE, 0x96, 0xCD, 0x6E, 0xC3, 0x7D, 0x8A, 0xF1, 0xD0, 0x2A, 0x10, 0x98, 0xA7, 0xF5, 0xB1, 0xC3,
+    0x90, 0x3A, 0x4A, 0xB7, 0xB9, 0xE5, 0x0E, 0x47, 0xE5, 0xA0, 0xD2, 0x1B, 0x17, 0xD0, 0x8B, 0x5A,
+    0x55, 0x7C, 0x50, 0xBA, 0x02, 0x66, 0xA7, 0xC1, 0xCC, 0x4D, 0x67, 0x3E, 0xD1, 0xB7, 0xEE, 0xC0,
+    0xE3, 0x34, 0x00, 0x1F, 0x89, 0x7A, 0x0E, 0xC7, 0xC0, 0x49, 0x2F, 0xEE, 0x01, 0x7B, 0x94, 0x52,
+    0x93, 0x22, 0xC0, 0xB9, 0xBB, 0x2C, 0x46, 0xD1, 0xBD, 0x65, 0x5F, 0x91, 0x56, 0x4B, 0x17, 0xCD
+]);
+
+const BASE_KEY = Buffer.from([
+    0xB9, 0x43, 0x34, 0xB5, 0xBE, 0xDE, 0x9E, 0x05, 0x58, 0xE2, 0xE6, 0xD8, 0xCE, 0xBA, 0x7E, 0x47
+]);
+
+const IV = Buffer.from([
+    0xA7, 0x2D, 0xD1, 0x29, 0x20, 0xDF, 0xAD, 0x61, 0x82, 0x03, 0x98, 0xFA, 0x9E, 0xEF, 0x59, 0x20
+]);
+
+const BLOCK_SIZE = 16;
+
+/**
+ * Generate encryption key from hub MAC address
+ * Uses specific bytes from the MAC address as per hub simulator's security.py
+ *
+ * @param {Buffer} macAddress - 6 bytes MAC address
+ * @returns {Buffer} - 16 bytes encryption key
+ */
+function generateKey(macAddress) {
+    if (macAddress.length !== 6) {
+        throw new Error('MAC address must be 6 bytes');
+    }
+
+    // Insert MAC address bytes in specific positions (from security.py)
+    // seed = hub_id[-6:] (entire MAC for 6-byte MAC)
+    // base_key[9] = seed[0], base_key[7] = seed[3], base_key[13] = seed[4], base_key[3] = seed[5]
+    const baseKey = Buffer.from(BASE_KEY);
+    baseKey[9] = macAddress[0];
+    baseKey[7] = macAddress[3];
+    baseKey[13] = macAddress[4];
+    baseKey[3] = macAddress[5];
+
+    // 8-pass encryption (1024-bit)
+    let result = baseKey;
+    for (let i = 0; i < 8; i++) {
+        const key = PRIVATE_KEY.subarray(i * 16, (i + 1) * 16);
+        const cipher = crypto.createCipheriv('aes-128-ecb', key, null);
+        cipher.setAutoPadding(false);
+        result = Buffer.concat([cipher.update(result), cipher.final()]);
+    }
+
+    return result;
+}
+
+/**
+ * Pad message to multiple of 16 bytes with random data
+ * @param {Buffer} message
+ * @returns {Buffer}
+ */
+function pad(message) {
+    const remainder = message.length % BLOCK_SIZE;
+    if (remainder === 0) {
+        return message;
+    }
+    const paddingLength = BLOCK_SIZE - remainder;
+    const padding = crypto.randomBytes(paddingLength);
+    return Buffer.concat([message, padding]);
+}
+
+/**
+ * Encrypt message using AES-128-CBC
+ * @param {Buffer} message - Message to encrypt
+ * @param {Buffer} key - 16 bytes encryption key
+ * @returns {Buffer} - Encrypted message
+ */
+function encrypt(message, key) {
+    const paddedMessage = pad(message);
+    const cipher = crypto.createCipheriv('aes-128-cbc', key, IV);
+    cipher.setAutoPadding(false);
+    return Buffer.concat([cipher.update(paddedMessage), cipher.final()]);
+}
+
+/**
+ * Decrypt message using AES-128-CBC
+ * @param {Buffer} message - Encrypted message
+ * @param {Buffer} key - 16 bytes encryption key
+ * @returns {Buffer} - Decrypted message
+ */
+function decrypt(message, key) {
+    const decipher = crypto.createDecipheriv('aes-128-cbc', key, IV);
+    decipher.setAutoPadding(false);
+    const decrypted = Buffer.concat([decipher.update(message), decipher.final()]);
+
+    // Remove padding by finding actual command length
+    if (decrypted.length > 11) {
+        const startMark = decrypted.readUInt16BE(0);
+        if (startMark === 0xFE00 || startMark === 0xFE01) {
+            const dataLen = decrypted.readUInt16BE(4);
+            const cmdLen = dataLen + 11; // header(8) + fcs(1) + end(2)
+            if (cmdLen <= decrypted.length) {
+                return decrypted.subarray(0, cmdLen);
+            }
+        }
+    }
+
+    return decrypted;
+}
+
+/**
+ * Parse MAC address string to Buffer
+ * @param {string} macString - MAC address like "00:12:4B:32:89:BB" or "00124B3289BB"
+ * @returns {Buffer} - 6 bytes
+ */
+function parseMacAddress(macString) {
+    const hex = macString.replace(/[:-]/g, '');
+    if (hex.length !== 12) {
+        throw new Error('Invalid MAC address format');
+    }
+    return Buffer.from(hex, 'hex');
+}
+
+module.exports = {
+    generateKey,
+    encrypt,
+    decrypt,
+    parseMacAddress,
+    IV,
+    BLOCK_SIZE,
+};