homebridge-frontier-silicon-plugin 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented in this file.
 
 The format is based on Keep a Changelog, and this project follows Semantic Versioning.
 
+## [1.1.0] – 2025-12-28
+
+### Added
+1. Added an optional native HomeKit Speaker service for volume control using the Volume characteristic.
+2. Added configuration switches to expose the Speaker service and the Apple Home slider independently.
+
+### Changed
+1. Volume can now be controlled through either the Speaker service, the Apple Home slider service, or both.
+
+### Improved
+1. Better compatibility with third party HomeKit apps via the Speaker service.
+2. Apple Home usability retained via the Brightness based slider.
+3. Non linear volume mapping remains for precise low volume control.
+
 ## [1.0.2] – 2025-12-28
 
 ### Changed

package/config.schema.json

@@ -1,29 +1,71 @@
 {
-  "name": "homebridge-frontier-silicon-plugin",
-  "version": "1.0.0",
-  "description": "Homebridge plugin for Frontier Silicon FSAPI devices, power and volume with safe polling",
-  "license": "ISC",
-  "main": "index.js",
-  "keywords": [
-    "homebridge-pluginconfig.schema.json",
-    "homebridge",
-    "frontier",
-    "silicon",
-    "fsapi",
-    "internet-radio"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/boikedamhuis/homebridge-frontier-silicon"
-  },
-  "bugs": {
-    "url": "https://github.com/boikedamhuis/homebridge-frontier-silicon/issues"
+  "pluginAlias": "frontier-silicon",
+  "pluginType": "accessory",
+  "singular": false,
+  "headerDisplay": "Frontier Silicon FSAPI radios",
+  "footerDisplay": "Tip: most devices use PIN 1234. If the device is offline, Homebridge will keep the last known state and recover automatically.",
+  "schema": {
+    "type": "object",
+    "required": ["name", "ip"],
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Living Room Radio",
+        "description": "The name shown in HomeKit."
+      },
+      "ip": {
+        "title": "IP Address",
+        "type": "string",
+        "default": "192.168.1.50",
+        "description": "The IP address of the radio on your network.",
+        "pattern": "^(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$"
+      },
+      "pin": {
+        "title": "FSAPI PIN",
+        "type": "string",
+        "default": "1234",
+        "description": "FSAPI PIN for the radio. Default is usually 1234."
+      },
+      "pollIntervalSeconds": {
+        "title": "Poll interval (seconds)",
+        "type": "integer",
+        "default": 5,
+        "minimum": 2,
+        "maximum": 120,
+        "description": "How often to poll the device for updates."
+      },
+      "enableVolume": {
+        "title": "Enable volume control",
+        "type": "boolean",
+        "default": true,
+        "description": "Enable volume support."
+      },
+      "exposeSpeakerService": {
+        "title": "Expose Speaker service",
+        "type": "boolean",
+        "default": true,
+        "description": "Adds a native HomeKit Speaker service using the Volume characteristic. Some apps show this, Apple Home often does not."
+      },
+      "exposeVolumeSlider": {
+        "title": "Expose Apple Home volume slider",
+        "type": "boolean",
+        "default": true,
+        "description": "Adds a Lightbulb Brightness slider for volume control that is visible in the Apple Home app."
+      }
+    }
   },
-  "author": {
-    "name": "Boike Damhuis"
-  },
-  "engines": {
-    "node": ">=18.0.0",
-    "homebridge": ">=1.6.0"
+  "form": [
+    "name",
+    "ip",
+    "pin",
+    "pollIntervalSeconds",
+    "enableVolume",
+    "exposeSpeakerService",
+    "exposeVolumeSlider"
+  ],
+  "display": {
+    "name": "Frontier Silicon Radio",
+    "description": "Control power and volume via FSAPI."
   }
 }

package/index.js

@@ -21,11 +21,18 @@ function FrontierSiliconAccessory(log, config) {
   this.ip = config.ip;
   this.pin = String(config.pin ?? "1234");
   this.pollIntervalSeconds = Number(config.pollIntervalSeconds ?? 5);
+
   this.enableVolume = config.enableVolume !== false;
 
+  // In 1.1.0 we expose both by default
+  // Speaker service is for correct semantics
+  // Lightbulb slider is for Apple Home app usability
+  this.exposeSpeakerService = config.exposeSpeakerService !== false;
+  this.exposeVolumeSlider = config.exposeVolumeSlider !== false;
+
   this.lastKnownPower = null;
 
-  // This stores the last known radio volume (0..100, device scale)
+  // Store last known RADIO volume on device scale 0..100
   this.lastKnownRadioVolume = null;
 
   if (!this.ip) {
@@ -38,39 +45,62 @@ function FrontierSiliconAccessory(log, config) {
     log: this.log
   });
 
-  this.switchService = new Service.Switch(this.name);
+  this.informationService = new Service.AccessoryInformation()
+    .setCharacteristic(Characteristic.Manufacturer, "Frontier Silicon")
+    .setCharacteristic(Characteristic.Model, "FSAPI Radio")
+    .setCharacteristic(Characteristic.SerialNumber, this.ip || "unknown");
 
+  // Power as Switch
+  this.switchService = new Service.Switch(this.name);
   this.switchService
     .getCharacteristic(Characteristic.On)
     .on("get", this.handleGetPower.bind(this))
     .on("set", this.handleSetPower.bind(this));
 
   if (this.enableVolume) {
-    // Volume is exposed as a separate slider using Lightbulb Brightness
-    this.volumeService = new Service.Lightbulb(this.name + " Volume");
-
-    this.volumeService
-      .getCharacteristic(Characteristic.On)
-      .on("get", (cb) => cb(null, true))
-      .on("set", (_val, cb) => cb(null));
-
-    this.volumeService
-      .getCharacteristic(Characteristic.Brightness)
-      .on("get", this.handleGetVolume.bind(this))
-      .on("set", this.handleSetVolume.bind(this));
-  }
+    if (this.exposeSpeakerService) {
+      this.speakerService = new Service.Speaker(this.name + " Speaker");
+
+      this.speakerService
+        .getCharacteristic(Characteristic.Volume)
+        .on("get", this.handleGetVolume.bind(this))
+        .on("set", this.handleSetVolume.bind(this));
+
+      // Optional mute placeholder, kept non functional by design
+      // Some radios support mute through FSAPI, but that endpoint differs per model
+      if (Characteristic.Mute) {
+        this.speakerService
+          .getCharacteristic(Characteristic.Mute)
+          .on("get", (cb) => cb(null, false))
+          .on("set", (_val, cb) => cb(null));
+      }
+    }
 
-  this.informationService = new Service.AccessoryInformation()
-    .setCharacteristic(Characteristic.Manufacturer, "Frontier Silicon")
-    .setCharacteristic(Characteristic.Model, "FSAPI Radio")
-    .setCharacteristic(Characteristic.SerialNumber, this.ip || "unknown");
+    if (this.exposeVolumeSlider) {
+      // Slider that works in Apple Home app
+      this.volumeSliderService = new Service.Lightbulb(this.name + " Volume");
+
+      this.volumeSliderService
+        .getCharacteristic(Characteristic.On)
+        .on("get", (cb) => cb(null, true))
+        .on("set", (_val, cb) => cb(null));
+
+      this.volumeSliderService
+        .getCharacteristic(Characteristic.Brightness)
+        .on("get", this.handleGetVolume.bind(this))
+        .on("set", this.handleSetVolume.bind(this));
+    }
+  }
 
   this.startPolling();
 }
 
 FrontierSiliconAccessory.prototype.getServices = function () {
   const services = [this.informationService, this.switchService];
-  if (this.enableVolume && this.volumeService) services.push(this.volumeService);
+
+  if (this.enableVolume && this.speakerService) services.push(this.speakerService);
+  if (this.enableVolume && this.volumeSliderService) services.push(this.volumeSliderService);
+
   return services;
 };
 
@@ -113,7 +143,6 @@ FrontierSiliconAccessory.prototype.handleGetVolume = async function (callback) {
 };
 
 FrontierSiliconAccessory.prototype.handleSetVolume = async function (value, callback) {
-  // Non linear mapping so low slider values are much softer
   const radioVol = homekitToRadioVolume(value);
 
   try {
@@ -142,15 +171,26 @@ FrontierSiliconAccessory.prototype.startPolling = function () {
       if (this.log.debug) this.log.debug("Polling power failed.", toMsg(err));
     }
 
-    if (this.enableVolume && this.volumeService) {
+    if (this.enableVolume) {
       try {
         const radioVol = await this.client.getVolume();
+
         if (this.lastKnownRadioVolume !== radioVol) {
           this.lastKnownRadioVolume = radioVol;
+
           const homekitVol = radioToHomekitVolume(radioVol);
-          this.volumeService
-            .getCharacteristic(Characteristic.Brightness)
-            .updateValue(homekitVol);
+
+          if (this.speakerService) {
+            this.speakerService
+              .getCharacteristic(Characteristic.Volume)
+              .updateValue(homekitVol);
+          }
+
+          if (this.volumeSliderService) {
+            this.volumeSliderService
+              .getCharacteristic(Characteristic.Brightness)
+              .updateValue(homekitVol);
+          }
         }
       } catch (err) {
         if (this.log.debug) this.log.debug("Polling volume failed.", toMsg(err));
@@ -179,7 +219,6 @@ FsApiClient.prototype.getPower = async function () {
 
 FsApiClient.prototype.setPower = async function (on) {
   const v = on ? 1 : 0;
-  // Important: SET must start query with ?value= so pin can be appended with &
   await this.fetchText("/fsapi/SET/netRemote.sys.power?value=" + v);
 };
 
@@ -191,18 +230,12 @@ FsApiClient.prototype.getVolume = async function () {
 
 FsApiClient.prototype.setVolume = async function (volume) {
   const v = clampInt(Number(volume), 0, 100);
-  // Important: SET must start query with ?value= so pin can be appended with &
   await this.fetchText("/fsapi/SET/netRemote.sys.audio.volume?value=" + v);
 };
 
 FsApiClient.prototype.fetchText = async function (pathAndQuery) {
   const joiner = pathAndQuery.includes("?") ? "&" : "?";
-  const url =
-    this.baseUrl +
-    pathAndQuery +
-    joiner +
-    "pin=" +
-    encodeURIComponent(this.pin);
+  const url = this.baseUrl + pathAndQuery + joiner + "pin=" + encodeURIComponent(this.pin);
 
   const controller = new AbortController();
   const t = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -260,10 +293,6 @@ function toMsg(err) {
   return String(err);
 }
 
-// Non linear volume mapping
-// HomeKit slider 0..100 is mapped to device volume 0..100
-// Low slider values become much softer, high end remains reachable
-
 function homekitToRadioVolume(homekitValue) {
   const x = clampInt(Number(homekitValue), 0, 100) / 100;
   return clampInt(Math.round(Math.pow(x, 2) * 100), 0, 100);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-frontier-silicon-plugin",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Homebridge plugin for Frontier Silicon FSAPI devices, power and volume with safe polling",
   "license": "ISC",
   "main": "index.js",