homebridge-frontier-silicon-plugin 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+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
+
+### Changed
+- Replaced the Lightbulb Brightness based volume control with a native HomeKit **Speaker** service.
+- Volume is now exposed using the official `Volume` characteristic.
+- Power and volume are logically separated, matching HomeKit audio device expectations.
+
+### Improved
+- More natural HomeKit UI for audio devices.
+- Better compatibility with HomeKit audio controls and third-party Home apps.
+- Non-linear volume mapping retained for precise low-volume control.
+
+## [1.0.2] – 2025-12-28
+
+### Changed
+- Improved volume handling using a non-linear volume curve.
+- Low volume levels are now significantly softer, allowing precise control at the bottom of the HomeKit slider.
+- Higher volume levels ramp up faster to maintain full output range.
+
+### Improved
+- Volume control now feels more natural and audio-appropriate.
+- Better alignment between HomeKit slider behaviour and perceived loudness on Frontier Silicon radios.
+- Overall usability of volume control in daily use.
+
+## [1.0.1] – 2025-12-28
+
+### Fixed
+- Fixed FSAPI SET request formatting so power and volume changes are correctly applied to the radio.
+- Resolved issue where HomeKit could read state changes but not write them back to the device.
+- Improved reliability of write operations across Frontier Silicon devices.
+
+## [1.0.0] – 2025-12-28
+
+### Added
+- Initial stable release of the Homebridge Frontier Silicon plugin.
+- Power control via HomeKit using native FSAPI communication.
+- Volume control with safe polling and automatic recovery when the device is unreachable.
+- Configurable polling interval.
+- Direct HTTP communication without external or native dependencies.
+
+### Fixed
+- Eliminated crashes when the radio becomes temporarily unreachable.
+- Removed dependency on legacy wifiradio and request modules.
+- Replaced legacy polling mechanisms with safe async polling.

package/index.js

@@ -21,10 +21,14 @@ function FrontierSiliconAccessory(log, config) {
   this.ip = config.ip;
   this.pin = String(config.pin ?? "1234");
   this.pollIntervalSeconds = Number(config.pollIntervalSeconds ?? 5);
+
+  // Keep volume enabled by default. This now uses a Speaker service.
   this.enableVolume = config.enableVolume !== false;
 
   this.lastKnownPower = null;
-  this.lastKnownVolume = null;
+
+  // Store last known RADIO volume in device scale 0..100
+  this.lastKnownRadioVolume = null;
 
   if (!this.ip) {
     this.log.warn("No ip configured, accessory will not work.");
@@ -36,37 +40,45 @@ 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 (kept as-is for maximum Home app compatibility)
+  this.switchService = new Service.Switch(this.name);
   this.switchService
     .getCharacteristic(Characteristic.On)
     .on("get", this.handleGetPower.bind(this))
     .on("set", this.handleSetPower.bind(this));
 
+  // Speaker service for volume (and optional mute)
   if (this.enableVolume) {
-    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)
+    this.speakerService = new Service.Speaker(this.name + " Speaker");
+
+    // Volume characteristic uses HomeKit scale 0..100
+    this.speakerService
+      .getCharacteristic(Characteristic.Volume)
       .on("get", this.handleGetVolume.bind(this))
       .on("set", this.handleSetVolume.bind(this));
-  }
 
-  this.informationService = new Service.AccessoryInformation()
-    .setCharacteristic(Characteristic.Manufacturer, "Frontier Silicon")
-    .setCharacteristic(Characteristic.Model, "FSAPI Radio")
-    .setCharacteristic(Characteristic.SerialNumber, this.ip || "unknown");
+    // Optional mute support placeholder:
+    // If you want real mute later, we can map this to an FSAPI endpoint if available.
+    // For now, we expose mute but keep it non-functional (always false) to avoid confusion.
+    if (Characteristic.Mute) {
+      this.speakerService
+        .getCharacteristic(Characteristic.Mute)
+        .on("get", (cb) => cb(null, false))
+        .on("set", (_val, cb) => cb(null));
+    }
+  }
 
   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);
   return services;
 };
 
@@ -96,21 +108,25 @@ FrontierSiliconAccessory.prototype.handleSetPower = async function (value, callb
 
 FrontierSiliconAccessory.prototype.handleGetVolume = async function (callback) {
   try {
-    const vol = await this.client.getVolume();
-    this.lastKnownVolume = vol;
-    callback(null, vol);
+    const radioVol = await this.client.getVolume();
+    this.lastKnownRadioVolume = radioVol;
+
+    const homekitVol = radioToHomekitVolume(radioVol);
+    callback(null, homekitVol);
   } catch (err) {
     this.log.warn("Volume get failed, returning last known level.", toMsg(err));
-    callback(null, this.lastKnownVolume ?? 0);
+    const fallbackRadio = this.lastKnownRadioVolume ?? 0;
+    callback(null, radioToHomekitVolume(fallbackRadio));
   }
 };
 
 FrontierSiliconAccessory.prototype.handleSetVolume = async function (value, callback) {
-  const vol = clampInt(Number(value), 0, 100);
+  // Non linear mapping so low slider values are much softer
+  const radioVol = homekitToRadioVolume(value);
 
   try {
-    await this.client.setVolume(vol);
-    this.lastKnownVolume = vol;
+    await this.client.setVolume(radioVol);
+    this.lastKnownRadioVolume = radioVol;
     callback(null);
   } catch (err) {
     this.log.warn("Volume set failed, keeping last known level.", toMsg(err));
@@ -131,24 +147,26 @@ FrontierSiliconAccessory.prototype.startPolling = function () {
         this.switchService.getCharacteristic(Characteristic.On).updateValue(power);
       }
     } catch (err) {
-      this.log.debug ? this.log.debug("Polling power failed.", toMsg(err)) : this.log("Polling power failed.");
+      if (this.log.debug) this.log.debug("Polling power failed.", toMsg(err));
     }
 
-    if (this.enableVolume && this.volumeService) {
+    if (this.enableVolume && this.speakerService) {
       try {
-        const vol = await this.client.getVolume();
-        if (this.lastKnownVolume !== vol) {
-          this.lastKnownVolume = vol;
-          this.volumeService.getCharacteristic(Characteristic.Brightness).updateValue(vol);
+        const radioVol = await this.client.getVolume();
+        if (this.lastKnownRadioVolume !== radioVol) {
+          this.lastKnownRadioVolume = radioVol;
+          const homekitVol = radioToHomekitVolume(radioVol);
+          this.speakerService
+            .getCharacteristic(Characteristic.Volume)
+            .updateValue(homekitVol);
         }
       } catch (err) {
-        this.log.debug ? this.log.debug("Polling volume failed.", toMsg(err)) : this.log("Polling volume failed.");
+        if (this.log.debug) this.log.debug("Polling volume failed.", toMsg(err));
       }
     }
   };
 
   tick();
-
   this.pollTimer = setInterval(tick, intervalMs);
 };
 
@@ -185,7 +203,12 @@ FsApiClient.prototype.setVolume = async function (volume) {
 
 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);
@@ -242,3 +265,17 @@ function toMsg(err) {
   if (err instanceof Error) return err.message;
   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);
+}
+
+function radioToHomekitVolume(radioValue) {
+  const x = clampInt(Number(radioValue), 0, 100) / 100;
+  return clampInt(Math.round(Math.sqrt(x) * 100), 0, 100);
+}

package/package.json

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