Home /Modules/telephony-skya/DRIVER.SCHEDULE.md

DRIVER.SCHEDULE.md

telephony-skya/drivers/DRIVER.SCHEDULE.md · 288 line(s) · markdown

Skya Telephony Driver Schedule

Scope: Linux, Windows 10+, and macOS Location: telephony-skya/drivers/

This schedule defines the implementation order for Skya's physical telephony and audio-device drivers. It is deliberately staged so that standard operating-system class support is used before vendor-specific code.

1. Driver architecture

The common C/C++ layer is authoritative:

Skya / SLeeLa / Guia™
        |
        v
Skya Driver Registry
        |
        +-- Device Discovery
        +-- Device Identity
        +-- Capability Probe
        +-- Audio Endpoint
        +-- HID Call Control
        +-- Vendor Adapter
        |
        +-- Linux
        +-- Windows 10+
        +-- macOS

Vendor adapters must not alter the Guia™ protocol or the SLeeLa application contract.

2. Platform strategy

Linux

Primary path

  1. USB/Bluetooth discovery through the Linux device stack.
  2. Audio discovery through ALSA.
  3. Prefer the installed PipeWire/PulseAudio environment for application-level routing when present.
  4. HID discovery for headset buttons, hooks, mute, volume, and call-control functions.
  5. SIP/network discovery for IP phones.
  6. Vendor-specific interfaces only when standard class interfaces are insufficient.
  7. Hot-plug and removal notifications.
  8. Device recovery after disconnect/reconnect.

ALSA is the kernel's established sound subsystem, including USB sound support. The Skya driver should therefore integrate with the existing Linux audio stack rather than replacing it. citeturn0search23turn0search17

Linux implementation phases

PhaseWorkOutput
L1USB/audio discoveryDevice inventory
L2ALSA input/outputWorking microphone/speaker
L3PipeWire/PulseAudio routingApplication endpoint selection
L4HID call controlsAnswer/end/mute/volume
L5SIP phone discoveryNetwork-phone inventory
L6Vendor adaptersModel-specific controls
L7Hot-plug/recoveryStable runtime behavior
L8Packaging/testsLinux driver test suite

Windows 10+

Primary path

  1. Enumerate audio endpoints using Windows audio/device APIs.
  2. Use WASAPI for audio streaming.
  3. Use Windows' USB Audio class support for compliant USB audio devices.
  4. Use Windows HID APIs for headset buttons and vendor HID interfaces.
  5. Identify VID/PID, manufacturer, product and serial information where available.
  6. Implement vendor-specific controls only when standard HID/class mechanisms are insufficient.
  7. Handle device invalidation and re-enumeration.
  8. Test Windows 10 and newer Windows releases separately.

Windows provides an in-box USB Audio class driver for compliant USB audio devices, while WASAPI provides application access to audio endpoint streams. citeturn0search8turn0search1

Windows HID APIs provide device discovery, attributes, strings and data movement; USB and Bluetooth HID transports are supported by the Windows HID stack. citeturn0search2turn0search3

Windows implementation phases

PhaseWorkOutput
W1PnP/audio enumerationDevice inventory
W2WASAPI render/captureWorking microphone/speaker
W3USB Audio validationClass-compliant device support
W4HID discoveryButton/control inventory
W5HID call controlsAnswer/end/mute/volume
W6Vendor adaptersModel-specific controls
W7Device invalidation/recoveryStable reconnect behavior
W8Installer/signing/testsWindows driver package/test suite

The initial Skya implementation should remain user-mode wherever the Windows class drivers expose the required functionality. A custom kernel driver should be considered only when a device requires behavior that cannot be provided through the supported user-mode/class interfaces.

macOS

Primary path

  1. Discover standard audio devices through Core Audio.
  2. Use Core Audio for application-level audio input/output.
  3. Discover USB/HID devices through the supported macOS device interfaces.
  4. Use vendor control interfaces only when standard mechanisms do not provide the required capability.
  5. Use DriverKit/AudioDriverKit for a genuine custom system driver when required.
  6. Handle device arrival/removal and endpoint changes.
  7. Test Intel and Apple Silicon separately.

Core Audio is Apple's framework for interacting with audio hardware. Apple also provides AudioDriverKit for user-space audio drivers. citeturn0search6turn0search0

Apple's DriverKit supports many USB and HID devices, while audio-specific and wireless device cases have distinct framework requirements. The Skya implementation should therefore avoid assuming that a generic USB DriverKit extension is the correct solution for every headset or phone. citeturn0search10turn0search11

macOS implementation phases

PhaseWorkOutput
M1Core Audio enumerationDevice inventory
M2Core Audio input/outputWorking microphone/speaker
M3USB/HID discoveryDevice/control inventory
M4Call-control HIDAnswer/end/mute/volume
M5Vendor adaptersModel-specific controls
M6DriverKit/AudioDriverKit where necessaryCustom-driver support
M7Hot-plug/recoveryStable reconnect behavior
M8Signing/install/testmacOS driver package/test suite

3. Cross-platform schedule

Stage A — Common foundation

Stage B — Standard audio devices

Implement class-compliant audio first.

Stage C — Call-control HID

HID behavior must be discovered from the actual device rather than inferred from its brand or model name.

Stage D — Vendor drivers

Implement in this order as hardware becomes available for testing:

  1. Yealink
  2. Poly
  3. Jabra
  4. Grandstream
  5. EPOS / Sennheiser
  6. Logitech
  7. Fanvil
  8. Snom
  9. Cisco

The order is an implementation sequence, not a ranking of manufacturers.

Stage E — VoIP desk phones

VoIP phones are different from USB audio peripherals.

The driver layer should separately support:

The network/SIP implementation must remain separate from the USB/HID audio driver implementation.

4. Driver versioning

Each hardware record should ultimately contain:

vendor
model
hardware revision
firmware family
transport
OS
driver version
capabilities
known limitations
test status

Firmware-specific behavior must never be silently generalized to every revision of a product family.

Recommended status values:

CERTIFIED should only be assigned after an actual reproducible test procedure has been completed.

5. Test matrix

Every driver test should record:

FieldRequired
OSYes
OS version/buildYes
CPU architectureYes
ManufacturerYes
ModelYes
Hardware revisionIf available
FirmwareIf available
USB VID/PIDIf applicable
Bluetooth identityIf applicable
TransportYes
Input deviceYes
Output deviceYes
Call controlsYes
Hot-plugYes
ReconnectYes
Failure behaviorYes
Driver versionYes

6. Safety and installation policy

Skya should prefer existing operating-system class drivers whenever they provide the required functionality.

The Skya driver program should not:

Custom drivers, DriverKit extensions, kernel components, or privileged services require explicit installation, appropriate signing, and a documented rollback/uninstall procedure.

7. Milestone definition

A platform driver milestone is complete only when:

  1. The device can be discovered.
  2. Identity is stable.
  3. Input and output can be selected.
  4. Supported call controls work.
  5. Disconnect/reconnect is handled.
  6. Unsupported features are reported.
  7. Logs identify the device and driver version.
  8. The test matrix has been recorded.
  9. Installation and removal are documented.

This schedule intentionally separates catalogued hardware, implemented drivers, and tested/certified hardware so the Skya project does not confuse a listed model with verified functionality.