openhab-item@phoehnel: Initial submission

openhab-item@phoehnel/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.1.0
+
+- ⏱️ Auto-close popup menu after configurable timeout (default 10s)
+- 🖱️ Scroll-wheel dimmer control directly on the panel (auto-populated for Dimmer items)
+- 🔒 Read-only mode to disable all controls
+- 🎨 Configurable color swatch dimensions and option to hide brightness % from panel
+- 🛠️ Cinnamon Spices best practices (GLib.SOURCE_REMOVE, proper timer cleanup)
+- 🐛 Fixed color swatch stretching to full panel height
+- 🐛 Fixed scroll-wheel not sending commands on sliders
+- 📄 Added CONTRIBUTING.md with development setup guide
+
+## 1.0.0
+
+- 🏠 Display any standard OpenHAB item on the panel (Switch, Dimmer, Number, String, Contact, Rollershutter, Color, DateTime, Player, Group)
+- 🔁 Multi-instance support — add the applet multiple times for different items
+- 🔗 Shared server configuration across instances via `~/.config/` with Gio.FileMonitor
+- 👆 Double-click toggle for Switch/Dimmer items (configurable)
+- ➕ Additional items in popup menu (e.g. lamp + brightness slider together)
+- 📌 Popup menu stays open during interaction
+- 🎨 Custom icons per instance
+- 💬 Configurable tooltip fields
+- 📐 stateDescription pattern formatting (e.g. `%.1f °C`)
+- 🌈 Color items with live color swatch on panel and brightness slider in popup
+- 📅 DateTime items with Java-style stateDescription patterns
+- 🎛️ Dimmer ON/OFF toggle (configurable, default off)

openhab-item@phoehnel/CLAUDE.md

@@ -0,0 +1,36 @@
+# cinnamon-spice-openhab
+
+Cinnamon panel applet to display and control OpenHAB smart home items.
+
+## Guidelines
+
+The Cinnamon Spices contributor guidelines MUST be followed:
+- https://github.com/linuxmint/cinnamon-spices-applets/blob/master/.github/CONTRIBUTING.md
+- https://github.com/linuxmint/cinnamon-spices-applets/blob/master/.github/copilot-instructions.md
+
+Key rules from those guides:
+- Never write to the installation directory (`metadata.path`) — use `GLib.get_user_config_dir()` / `GLib.get_user_state_dir()` / `GLib.get_user_cache_dir()`
+- Clean up all timers and signal handlers in `on_applet_removed_from_panel()`
+- Use `GLib.SOURCE_REMOVE` / `GLib.SOURCE_CONTINUE` for timer return values
+- Use `Clutter.EVENT_STOP` / `Clutter.EVENT_PROPAGATE` for event handlers
+- No synchronous network calls — use async Soup APIs
+- No compiled code, binaries, or minified JS
+- JS must be compatible with SpiderMonkey 102+ (Linux Mint Cinnamon)
+
+## Architecture
+
+- **UUID**: `openhab-item@phoehnel`
+- **applet.js**: Main `TextIconApplet` class — settings binding, polling, panel display (incl. color swatch), popup menu, double-click toggle, scroll-wheel dimmer
+- **httpClient.js**: Soup 2/3 compatible HTTP GET/POST with Bearer auth
+- **serverConfig.js**: Shared server config in `$XDG_CONFIG_HOME/UUID/server.json` with `Gio.FileMonitor` for cross-instance sync
+- **itemRenderers.js**: Per-type icons, state formatting (printf patterns, Java date patterns, HSB→hex), popup menu controls (keeps menu open, debounced sliders)
+- **settings-schema.json**: 3 pages (Server, Item, Display) with per-instance settings
+
+## Resources
+
+- Cinnamon Spices repo: https://github.com/linuxmint/cinnamon-spices-applets
+  - Reference popular applets like `Weather@mockturtl` and `Cinnamenu@json` for best practices
+- OpenHAB docs: use context7 MCP with libraryId `/openhab/openhab-docs`
+  - context7 also works for Cinnamon and other library docs
+- OpenHAB Basic UI (no auth): http://<OPENHAB IP>:8080/basicui/app
+  - You'll have to ask user for the IP

openhab-item@phoehnel/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to OpenHAB Item Applet
+
+Contributions are welcome! 🎉 Whether it's bug fixes, new features, or documentation improvements — feel free to open an issue or submit a pull request.
+
+Please make sure your contributions respect the [Cinnamon Spices contributing guidelines](https://github.com/linuxmint/cinnamon-spices-applets/blob/master/.github/CONTRIBUTING.md) and the [code review instructions](https://github.com/linuxmint/cinnamon-spices-applets/blob/master/.github/copilot-instructions.md).
+
+## Prerequisites
+
+- Cinnamon Desktop Environment (5.4+)
+- OpenHAB server accessible on your network
+
+## Install from Repository for Development
+
+1. **Clone this repository:**
+   ```bash
+   git clone <repo-url>
+   cd cinnamon-spice-openhab
+   ```
+
+2. **Create a symlink to your local Cinnamon applets directory:**
+   ```bash
+   mkdir -p ~/.local/share/cinnamon/applets
+   ln -sf "$(pwd)/files/openhab-item@phoehnel" \
+     ~/.local/share/cinnamon/applets/openhab-item@phoehnel
+   ```
+
+3. **Restart Cinnamon:**
+   - Press `Alt+F2`, type `r`, press `Enter` (X11 only)
+   - Or log out and back in (works on both X11 and Wayland)
+
+4. **Add the applet to your panel:**
+   - Right-click on the panel -> **Applets**
+   - Search for "OpenHAB Item"
+   - Click the **+** button to add it
+
+5. **Configure the applet:**
+   - Right-click the new applet -> **Configure...**
+   - On the **Server** tab: enter your OpenHAB server URL (e.g., `http://openhabianpi:8080`)
+   - On the **Item** tab: enter an OpenHAB item name (e.g., `LivingRoom_Light`)
+
+6. **Add more instances** for additional items:
+   - Right-click panel -> **Applets** -> add another "OpenHAB Item"
+   - The server URL is shared automatically -- just configure the item name
+
+## View Logs
+
+- **Looking Glass**: Press `Alt+F2`, type `lg`, go to the **Log** tab
+- **Journal**: `journalctl -f /usr/bin/cinnamon`
+
+## After Code Changes
+
+Restart Cinnamon (`Alt+F2` -> `r` -> `Enter`) to reload the applet.
+
+## Uninstall
+
+```bash
+rm ~/.local/share/cinnamon/applets/openhab-item@phoehnel
+```
+Then restart Cinnamon.
+
+## Project Structure
+
+- `files/openhab-item@phoehnel/applet.js` -- Main TextIconApplet class
+- `files/openhab-item@phoehnel/httpClient.js` -- Soup 2/3 compatible HTTP client
+- `files/openhab-item@phoehnel/serverConfig.js` -- Shared server config with file monitoring
+- `files/openhab-item@phoehnel/itemRenderers.js` -- Per-type icons, formatting, and popup menu controls
+- `files/openhab-item@phoehnel/settings-schema.json` -- Settings UI definition
+
+## Cinnamon Spices Guidelines
+
+This applet follows the [Cinnamon Spices contributing guidelines](https://github.com/linuxmint/cinnamon-spices-applets/blob/master/.github/CONTRIBUTING.md).

openhab-item@phoehnel/README.md

@@ -0,0 +1,102 @@
+# 🏠 OpenHAB Item Applet for Cinnamon
+
+Display and control [OpenHAB](https://www.openhab.org/) smart home items directly from your Cinnamon desktop panel.
+
+<img src="screenshot.png" alt="Screenshot" style="max-height: 300px;">
+
+
+## ✨ Features
+
+- 🔁 **Multi-instance** — Add the applet multiple times to monitor different items
+- 🔗 **Shared configuration** — Configure the OpenHAB server URL once, all instances share it
+- 🎛️ **Rich item support** — Switch, Dimmer, Rollershutter, Color, Player, and read-only types like Number, String, Contact, DateTime, and Group
+- ➕ **Additional items** — Show related items in the popup (e.g. lamp switch + brightness dimmer together)
+- 👆 **Double-click toggle** — Quickly toggle Switch/Dimmer items without opening the menu
+- 🖱️ **Scroll-wheel dimmer** — Control brightness by scrolling directly on the panel — no popup needed (auto-populated for Dimmer items)
+- 🎨 **Configurable display** — Choose what to show on the panel (icon, label, state) with a custom format string and configurable tooltip
+- 🔒 **Read-only mode** — Disable all controls to use the applet as a display-only monitor
+- ⏱️ **Auto-close popup** — Popup menu auto-closes after a configurable timeout
+- 🔄 **Auto-polling** — Configurable refresh interval (1–300 seconds)
+
+## 📋 Supported Item Types
+
+| Type | Panel Display | Controls |
+|------|--------------|----------|
+| Switch | ON / OFF | Toggle switch |
+| Dimmer | Percentage | Brightness slider (optional ON/OFF toggle) |
+| Number | Formatted value | Read-only |
+| String | Text | Read-only |
+| Contact | Open / Closed | Read-only |
+| Rollershutter | Position % | UP / STOP / DOWN + slider |
+| Color | Color swatch + brightness % | ON/OFF toggle, color preview, brightness slider |
+| DateTime | Formatted (supports OpenHAB patterns) | Read-only |
+| Player | Play state | Play / Pause / Next / Previous |
+| Group | Aggregated value (AVG, SUM, etc.) | Read-only |
+
+## 🛠️ Configuration
+
+Right-click the applet → **Configure...** to access settings across three tabs.
+
+### 🌐 Server Settings (shared across all instances)
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Server URL | OpenHAB server URL (e.g. `http://openhabianpi:8080`) | *(empty)* |
+| API Token | Bearer token for authentication (optional) | *(empty)* |
+| Poll Interval | How often to refresh item state, in seconds | 30 |
+
+### 📦 Item Settings (per instance)
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Item Name | Exact OpenHAB item name (e.g. `LivingRoom_Light`) | *(empty)* |
+| Custom Label | Override the item label from OpenHAB | *(empty)* |
+| Additional Items | Comma-separated item names to show in popup | *(empty)* |
+| Scroll-wheel Dimmer Item | Item to control via scroll wheel on the panel | *(auto for Dimmer)* |
+| Scroll Step Size | Percentage step per scroll tick | 5% |
+| Read-only Mode | Disable all controls (display only) | OFF |
+
+### 🖥️ Display Settings (per instance)
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Show Icon | Show item type icon on the panel | ON |
+| Custom Icon | Override with a custom icon (name or file path) | *(auto by type)* |
+| Show Label | Show item label text on the panel | OFF |
+| Show State | Show state value on the panel | ON |
+| Panel Text Format | Format string using `{label}`, `{state}`, `{name}` | `{state}` |
+| Double-click Toggle | Toggle Switch/Dimmer items on double-click | ON |
+| Dimmer Toggle | Show ON/OFF toggle for Dimmer items in popup | OFF |
+| Color Show % | Show brightness percentage on panel for Color items | ON |
+| Color Swatch Width | Width of color preview swatch on panel | 16 px |
+| Color Swatch Height | Height of color preview swatch on panel | 16 px |
+| Auto-close Popup | Automatically close popup menu after timeout | ON |
+| Auto-close Delay | Seconds before popup auto-closes | 10 |
+
+### 💬 Tooltip Settings (per instance)
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Show Label | Show item label in tooltip | ON |
+| Show Item Type | Show the OpenHAB item type | OFF |
+| Show State Value | Show current state in tooltip | ON |
+| Show Item Name | Show the technical item name | OFF |
+| Show Server URL | Show the configured server URL | OFF |
+
+## 🐛 Known Issues
+
+- **Color items: no full color picker** — The Color item type currently only supports brightness control and ON/OFF toggle. Hue and saturation cannot be changed from the applet because Cinnamon's toolkit (St/Clutter) does not provide a color picker widget. Contributions welcome if you know a viable approach!
+
+## 🧑‍💻 Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local testing, development setup, and project structure.
+
+## 👤 Author
+
+[phoehnel](https://github.com/phoehnel)
+
+## 📄 License
+
+GPL-3.0
+
+> ⚠️ **Disclaimer:** This applet is an independent community project and is **not affiliated with, endorsed by, or supported by** the openHAB Foundation or the openHAB project. It simply interfaces with the [OpenHAB REST API](https://www.openhab.org/docs/configuration/restdocs.html).