A capability to read and set the headset's hardware volume

[Mihuy1]

Hi! I have an ASTRO A50 Gen 5 and would like to propose a core capability for the headset's own volume. This is the level the volume wheel changes, separate from the OS mixer.

The wheel has no end stops, so you can't feel when it reaches 0% or 100%. It also turns easily when I lift the headset off the base station, so I often change the volume by accident. On Windows I can check the level in Logitech G HUB, but on Linux there is no way to see it.

The commands are already known. #531 documents the set command, 02 0c 05 00 08 1b ff <0..21>, and the companion GUI reads the level with 02 0c 03 00 08 0c.

My plan would be two capabilities, like sidetone and sidetone status. --volume LEVEL would set the level and --volume with no value would read it.

Questions:

1. Do you want this at all, or does it overlap too much with OS volume control?
2. Should it use 0 to 128 like sidetone and chatmix, or 0 to 100?
3. Two capabilities, or one that does both?

[Sapd]

1. Yes. CAP_MICROPHONE_VOLUME is precedent

I guess for your headset the OS-Volume and the volume of the A50 base station is completely separate?

2. 0-128 same as sidetone and microphone-volume. (bt-call-volume is the odd one out)

device_utils.hpp already has mapSidetoneToDiscrete<N>() and
mapDiscreteToSidetone<N>() which round-trip exactly; your device has 22 steps, so
N = 22. They're named for sidetone but they're generic.

3. One. A read-only fact gets its own capability - Add Sony InZone H9 II  #569 has
   CAP_MICROPHONE_ATTACHMENT_STATUS and CAP_MICROPHONE_MUTE_STATUS and that's fine,
   there's no setter to pair them with. What I don't want is a *_STATUS twin for
   something that already has a setter. Add Sony InZone H9 II  #569 first did that for every readable setting -
   11 new capabilities and the README table from 20 to 31 columns - each one encoding one
   bit, "this can be read back". Readability is a property of a capability, not a
   capability of its own; the shape I want is a second bitmask over the same enum,
   getCapabilities() / getReadableCapabilities(). CAP_SIDETONE_STATUS only exists
   because it shipped in 4.1.0 at value 17 and can't be removed - don't copy it.

CLI shape (--volume LEVEL and --volume) is right, -s already works that way

Name it CAP_HEADSET_VOLUME rather than CAP_VOLUME, so it doesn't read as the OS
volume in --help.

The catch is that the readable bitmask doesn't exist yet and nothing open is building
it - #569 dropped its read-backs when it was split. So if read-back is the part you
care about, that's groundwork you'd be taking on. Otherwise land the setter and the
read-back follows when the mechanism does.

[Mihuy1]

Yeah, the base station volume is completely separate from the OS volume. Changing one doesn't affect the other.

I've reworked it based on your feedback, so:

• One capability, CAP_HEADSET_VOLUME, with no _STATUS
• --volume LEVEL on a 0-128 scale, mapped to the already existing mapSidetoneToDiscrete<22> (A50's 22 steps)

I'll open a PR with just the setter first. After that I'd like to look into the readable mask as a separate PR, since the read back is the part I care about. Do you have any design preferences on how it should be implemented too?

[Sapd]

The idea is that set and read are two directions on one capability, not two
capabilities. The request table already carries capabilitytype, so
{CAP_X, ACTION, …} and {CAP_X, INFO, …} are both expressible today - what's
missing is a per-device advertisement and a second slot in the handler table.

Shape:

// result_types.hpp
struct HeadsetVolumeResult {
    uint8_t volume;       // normalised 0-128
    uint8_t device_level; // 0-21 as the headset stores it
};

// devices/hid_device.hpp
virtual Result<HeadsetVolumeResult> setHeadsetVolume(hid_device*, uint8_t /*volume*/)
{
    return DeviceError::notSupported("Device does not support headset volume");
}
virtual Result<HeadsetVolumeResult> getHeadsetVolume(hid_device*)
{
    return DeviceError::notSupported("Device cannot read headset volume");
}

// NEW - the whole mechanism. Advertisement only, no new enum entries.
virtual constexpr int getReadableCapabilities() const { return 0; }

// devices/logitech_astro_a50.hpp
constexpr int getCapabilities() const override
{
    return B(CAP_BATTERY_STATUS) | B(CAP_SIDETONE) | B(CAP_HEADSET_VOLUME) /* ... */;
}
constexpr int getReadableCapabilities() const override
{
    return B(CAP_HEADSET_VOLUME);   // settable *and* readable
}

Result<HeadsetVolumeResult> setHeadsetVolume(hid_device* h, uint8_t volume) override
{
    const uint8_t level = mapSidetoneToDiscrete<22>(volume);
    // 02 0c 05 00 08 1b ff <level>
    ...
    return HeadsetVolumeResult { .volume = volume, .device_level = level };
}

Result<HeadsetVolumeResult> getHeadsetVolume(hid_device* h) override
{
    // 02 0c 03 00 08 0c, reply carries the level
    ...
    return HeadsetVolumeResult {
        .volume = mapDiscreteToSidetone<22>(level), .device_level = level };
}

The registry is the part that changes. Today it is one flat slot per capability:

// feature_handlers.hpp, as it is now
void registerHandler(capabilities cap, FeatureHandler handler)
{
    handlers_[static_cast<size_t>(cap)] = std::move(handler);
}
Result<FeatureOutput> execute(capabilities cap, HIDDevice*, hid_device*,
                              const FeatureParam&) const;

std::array<FeatureHandler, NUM_CAPABILITIES> handlers_ {};

Key it on the direction as well:

// NEW
void registerHandler(capabilities cap, capabilitytype type, FeatureHandler handler)
{
    handlers_[static_cast<size_t>(cap)][static_cast<size_t>(type)] = std::move(handler);
}
Result<FeatureOutput> execute(capabilities cap, capabilitytype type, HIDDevice*,
                              hid_device*, const FeatureParam&) const;

std::array<std::array<FeatureHandler, 2>, NUM_CAPABILITIES> handlers_ {};

That touches the 24 existing registerHandler calls (add
CAPABILITYTYPE_ACTION) and the single execute() call site in main.cpp:693,
which already has req.type to hand. Mechanical, and then dispatch needs no
branching:

registerHandler(CAP_HEADSET_VOLUME, CAPABILITYTYPE_ACTION,
    [](HIDDevice* dev, hid_device* h, const FeatureParam& p) -> Result<FeatureOutput> {
        auto r = dev->setHeadsetVolume(h, getUint8(p));
        if (r.hasError())
            return r.error();
        return FeatureOutput::fromHeadsetVolume(r.value());
    });

registerHandler(CAP_HEADSET_VOLUME, CAPABILITYTYPE_INFO,
    [](HIDDevice* dev, hid_device* h, const FeatureParam&) -> Result<FeatureOutput> {
        auto r = dev->getHeadsetVolume(h);
        if (r.hasError())
            return r.error();
        return FeatureOutput::fromHeadsetVolume(r.value());
    });

CLI is already this shape - -s is ArgRequirement::Optional and bare -s sets
request_sidetone. Same for --volume, except both entries name the same
capability:

{ CAP_HEADSET_VOLUME, CAPABILITYTYPE_ACTION, g_feature_params.headset_volume_val,
  opts.headset_volume.has_value(), {} },
{ CAP_HEADSET_VOLUME, CAPABILITYTYPE_INFO, std::monostate {},
  opts.request_headset_volume, {} },

Getters stay typed per capability - no generic read returning a variant.
C API gets int hsc_get_readable_capabilities(hsc_headset_t) appended, enum
untouched.

Two things the code can't show:

CAP_SIDETONE_STATUS shipped at value 17 and five devices advertise it (both
Maxwells, A50 Gen 4, G522, test device), so it can't go. Synthesise it - a device
with CAP_SIDETONE in the readable mask still reports CAP_SIDETONE_STATUS from
getCapabilities(), so --capabilities and the README don't change for existing
devices. New devices only set the mask.

README is generated and needs a marker; x* is already "variant-only", so
readable wants its own. I'd take r.

Best to build it against the test device only, no hardware, so the mechanism is
reviewable on its own. The A50 read-back is a couple of lines on top.