====== Genelec Smart IP Drivers for PIXILAB Blocks ======

Two drivers are available for the Genelec Smart IP API v1 (revision 0.8.4). They can be used independently or together, depending on the required functionality.

^ Driver ^ Controls ^ Transport ^ Feedback ^
| ''GenelecSmartIPUnicast'' (2.0.0) | Individual speakers | TCP/HTTP, port 9000 (Network Device type: TCP) | Yes. Reads and polls speaker status. |
| ''GenelecSmartIPMulticast'' | Entire multicast groups | UDP datagrams, default port 49152 (Network Device type: UDP) | None. One-way communication. |

The legacy single-speaker driver, ''driver-archive/GenelecSmartIP'' (1.01), was renamed to ''GenelecSmartIPUnicast'' in version 2.0.0. **Do not run both versions simultaneously.**

Multicast requires speaker firmware 1.3.25 or later. Testing has been performed on a Genelec 4420 running firmware 1.4.9.

**Source files**

  * ''script/driver/GenelecSmartIPUnicast.ts''
  * ''script/driver/GenelecSmartIPMulticast.ts''

If this document conflicts with the source code, the header comments in the respective driver files take precedence.

===== 1. Which Driver Should You Use? =====

  * **Unicast:** Use for individual speaker control and whenever you need feedback about a speaker's state, including power, level, mute, profile, inputs and zone.
  * **Multicast:** Use to control an entire group with a single datagram per command. For example, a single volume slider can control every speaker in a room. Multicast does not provide feedback.
  * **Both together:** Configure one Unicast device per speaker and one Multicast device per group. Each Unicast device reads its speaker's multicast group address and can follow Multicast devices addressing that group. Group commands for volume, mute and profiles are reflected immediately in the corresponding Unicast properties and then confirmed by reading the speaker.

===== 2. GenelecSmartIPUnicast =====

==== Device setup ====

Create a **TCP Network Device** with the following settings:

  * **Address:** Speaker IP address
  * **Port:** ''9000''

==== Driver options ====

The driver accepts authentication credentials and additional settings through the driver options.

The simplest configuration is the username and password:

<code>
admin:admin
</code>

Alternatively, use JSON:

<code json>
{
  "auth": "admin:admin",
  "pollSec": 30,
  "followMulticast": true
}
</code>

Available options:

^ Option ^ Default ^ Description ^
| ''auth'' | ''admin:admin'' | Speaker HTTP API credentials in ''user:password'' format. |
| ''pollSec'' | ''10'' | Polling interval in seconds for power, level, mute and profile. Setting this to ''0'' disables routine polling. While contact is lost or the speaker has not yet been fully read, the driver still checks every 30 seconds. |
| ''followMulticast'' | ''false'' | Enables following of ''GenelecSmartIPMulticast'' devices addressing the speaker's group. The speaker's group is read regardless of this setting, so ''group'' is populated and ''recallProfile(..., alsoStartup)'' can still locate the speaker. |

**Important:** Set the speaker's **sleep delay to 0** in Smart IP Manager. ISS (Intelligent Signal Sensing) auto-sleep is not supported.

==== Properties ====

^ Property ^ Type ^ Description ^
| ''connected'' | Boolean, read-only | Indicates whether communication with the speaker is available. |
| ''active'' | Boolean | ''true'' wakes the speaker; ''false'' puts it into standby. Becomes ''true'' when the speaker reports ''ACTIVE'', after which all properties are re-read. Does not change mute. |
| ''boot'' | Boolean, momentary | Restarts the speaker. Returns to ''false'' after 5 seconds. The speaker may be unavailable for up to one minute. |
| ''level'' | Number, dB, -130 to 0 | Exact volume value with 0.1 dB resolution. Use for text readouts and tasks. |
| ''volumeFader'' | Number, 0-1 | Normalized fader representation of the volume setting. **Bind sliders to this property.** See the volume curve below. |
| ''mute'' | Boolean | Controls mute. The setting is retained in standby. |
| ''profile'' | Number, 0-5 | Recalls a profile immediately without changing the startup profile. |
| ''startupProfile'' | Number, 0-5 | Sets the profile used after reboot. Setting it also recalls the profile immediately because the API has no separate command for changing only the startup profile. |
| ''enableAoIP01'' | Boolean | Enables or disables the AoIP 01 input. |
| ''enableAoIP02'' | Boolean | Enables or disables the AoIP 02 input. |
| ''enableAnalog'' | Boolean | Enables or disables the analog input. Speakers without an analog input reject this setting. |
| ''group'' | String, read-only | Multicast group in ''ip:port'' format. Empty if the speaker is not in a group. |
| ''zone'' | String, read-only | Speaker zone, read once at startup. |
| ''aoipName'' | String, read-only | Speaker AoIP name, read once at startup. |

==== Volume curve ====

The driver exposes two volume properties for different use cases:

  * ''level'': Exact volume in dB, suitable for text readouts and tasks.
  * ''volumeFader'': Normalized value from 0 to 1, suitable for sliders and other graphical controls.

The fader follows this logarithmic curve:

<code>
dB = 60 * log10(volumeFader)
</code>

^ ''volumeFader'' ^ Approximate volume ^
| 1.0 | 0 dB |
| 0.5 | -18 dB |
| 0.1 | -60 dB |
| 0 | -130 dB |

==== Behaviour ====

  * **The speaker is authoritative.** Settings are read at startup and polled periodically. Changes made elsewhere, including in Smart IP Manager or through multicast, become visible within one polling interval.
  * **Commands are rate-limited.** Commands are sent one at a time, with a minimum interval of 100 ms. If a newer value arrives before a pending command is sent, it replaces the pending value. This prevents a dragged slider from flooding the speaker, which has a limit of four connections.
  * **Properties update immediately.** When a property is changed, its value updates immediately. If the speaker rejects the command, the property reverts to its last known value.
  * **Sleeping speakers.** When the speaker is in standby or ISS sleep, audio-related requests return HTTP 503. The driver marks the speaker as inactive rather than disconnected. Commands sent while the speaker is in standby are lost and are not automatically applied when it wakes.
  * **Following multicast.** Volume, mute and profile commands sent through a group device are reflected immediately in the Unicast properties. After the group has been quiet for 0.5 seconds, the driver performs one read to confirm the resulting state. Power commands are not mirrored because ''BOOT'' restarts the speaker; power state is read instead. Newly discovered group devices are found during the next read.

===== 3. GenelecSmartIPMulticast =====

==== Device setup ====

Create a **UDP Network Device** with the following settings:

  * **Address:** The group's multicast IP address, in the range ''224.0.0.0'' to ''239.255.255.255''.
  * **Port:** The group's multicast port.
  * **Configuration:** Use one device per multicast group.

The multicast IP and port are configured in Smart IP Manager.

They can be retrieved from the following sources:

  * ''volIp'' and ''volPort'' in ''GET /public/v1/network/ipv4'' on any speaker in the group.
  * ''mcastport'' in the speaker's mDNS record (''_smart_ip._tcp'').

The default port is ''49152'', as used in the protocol specification's example. However, the specification's mDNS example uses ''49153'' as the zone ID, so **verify the actual multicast port rather than assuming the default**.

A speaker configured with ''volIp'' set to ''0.0.0.0'' ignores multicast commands.

==== Properties and callables ====

^ Item ^ Type ^ Description ^
| ''connected'' | Boolean, read-only | ''true'' while the device is enabled, meaning it is available to send commands. Multicast cannot confirm receipt. |
| ''groupAddress'' | String, read-only | Multicast group IP address. Used by Unicast devices to identify the group. |
| ''groupPort'' | Number, read-only | Multicast group port. Used by Unicast devices to identify the group. |
| ''level'' | Number, dB, -130 to 0 | Last volume value sent, rounded to 0.1 dB. |
| ''volumeFader'' | Number, 0-1 | Normalized fader representation of the volume setting. Bind sliders to this property. |
| ''mute'' | Boolean | Last mute value sent. |
| ''profile'' | Number, 0-5, read-only | Last profile value sent. |
| ''recallProfile(profile, alsoStartup)'' | Callable | Recalls a profile across the entire group. When ''alsoStartup'' is enabled, the Unicast devices in the group also set the startup profile, since multicast has no startup-profile command. |
| ''standby'' | Boolean, momentary | Sends ''STANDBY'' to the group. Remains ''true'' for 5 seconds. |
| ''boot'' | Boolean, momentary | Sends ''BOOT'', **restarting every speaker in the group**. Audio may be interrupted for up to one minute. Remains ''true'' for 5 seconds. |
| ''lastPowerSent'' | String, read-only | ''STANDBY'' or ''BOOT''. Indicates the last requested power command, not the actual state of any speaker. |

==== Behaviour and limitations ====

  * **No feedback.** Properties reflect the last values sent, not confirmed speaker states. A speaker that is offline or rebooting when a command is sent may miss it. Set the property again to resend the command. Every property set sends a command, even if the value has not changed.
  * **Command pacing.** Each command is sent as one UDP datagram in the format <code>{"mcast":{"ver":1,<name>:<value>}}</code>. There is a minimum interval of 100 ms between datagrams. Updates to the same command received during this interval are merged, retaining the latest value. The constructor does not send any commands.
  * **Disabled devices.** No commands are sent, and property sets are ignored while the device is disabled.
  * **Power control.** ''STANDBY'' is the only power state that multicast can set reliably. The ''state: ACTIVE'' command is ignored, as observed on a Genelec 4420 running firmware 1.4.9. Waking a group without rebooting therefore requires Unicast commands, sent to each speaker individually. Power commands do not change mute.
  * **Startup profiles.** Speakers without a corresponding Unicast device in the group can still recall the selected profile, but their startup profile remains unchanged.
  * **Profile contents.** Profiles contain acoustic and input settings, not volume. Profiles are stored and managed through Smart IP Manager.

===== 4. Changes from the Legacy GenelecSmartIP 1.01 Driver =====

The following changes apply when migrating from the old ''GenelecSmartIP'' driver to ''GenelecSmartIPUnicast'' 2.0.0.

  * The old 0-1 ''volume'' property, which used a linear mapping over -200 to 0 dB, has been replaced by ''level'' and ''volumeFader''. **Rebind all volume sliders to ''volumeFader''.**
  * ''profile'' no longer automatically changes the startup profile. Use ''startupProfile'' when that is the intended behaviour.
  * Setting ''active = true'' no longer unmutes the speaker.
  * Fixed issues involving speakers offline at startup, stale values dropping matching commands, AoIP 01/02 input states not being read back, overlapping requests, rejected values still being displayed, and profile values above 5 incorrectly recalling profile 5.
  * Added ''boot'', ''startupProfile'', ''group'', polling and multicast following.