Fix RangeController response property name for window covering state reporting

[Copilot]

Window coverings using Alexa.RangeController reported position correctly to HomeKit but showed 0% in Alexa app after commands.

Changes

• Fix response property name (src/lib/alexaMessages.js:193)
  Changed from directive name (SetRangeValue/AdjustRangeValue) to state property name (rangeValue)

• Add test coverage (src/lib/alexaMessages.test.js)
  Verify both SetRangeValue and AdjustRangeValue directives return rangeValue property

• Fix test imports (src/lib/alexaMessages.test.js, src/lib/parse/messages.stateToProperties.test.ts)
  Replace hardcoded absolute paths with relative imports

Technical Details

The response context must use the state property name, not the directive name:

// Before - incorrect, uses directive name
"name": message.directive.header.name,  // "SetRangeValue"

// After - correct, uses state property name  
"name": "rangeValue",

This aligns with other controllers (e.g., PowerLevelController uses "powerLevel").

Original prompt

---

This section details on the original issue you should resolve

<issue_title>window covering percentage</issue_title>
<issue_description>### Current Situation

I’ve been using this plugin since it first came out and I love it. I only have one issue with the roller shutters.
When I say “Alexa, close/open the shutter to 50%,” the shutter moves to the requested percentage. In the Home app on my Mac/iPhone I see the correct percentage, but in the Alexa app it’s always 0%.

I’m not sure if this can be fixed.

The shutters are controlled with a Shelly 2PM Plus using the “Homebridge Shelly DS9” plugin.

Logs

2025-11-08T18:32:54.011Z alexaLocal Emitting Alexa.RangeController SetRangeValue SUdTVEs6AAE6AAg6eyJpZCI6ImM5NDJiN2E3LTU2NTUtNGE5Ni1hMzE3LWRjZGViNmU3Mjg0OCIsInVyaSI6Imh0dHBzOi8vZC1hY3JzLWV1LXAtN2ItODFiYTQyMGIuZXUtd2VzdC0xLmFtYXpvbi5jb206OTQ0NCIsInNlc3Npb25JZCI6IjE3NjQyZTMyLTZmNGEtNDRmZC1hMDFjLTZjYWQ1ODgwM2M4MCJ9 MEU6QkI6RDc6N0U6QjE6RTYtaG9tZWJyaWRnZS1BbGx0ZXJjby1XaW5kb3cgQ292ZXJpbmcgMS0wMDAwMDA4Qy0wMDAwLTEwMDAtODAwMC0wMDI2QkI3NjUyOTE=
[11/8/2025, 7:32:54 PM] [Shelly NGDS9] [Tapparella Lorenzo] Device connected
[11/8/2025, 7:32:54 PM] [Alexa] Alexa.RangeController SetRangeValue 0E:BB:D7:7E:B1:E6 MEU6QkI6RDc6N0U6QjE6RTYtaG9tZWJyaWRnZS1BbGx0ZXJjby1XaW5kb3cgQ292ZXJpbmcgMS0wMDAwMDA4Qy0wMDAwLTEwMDAtODAwMC0wMDI2QkI3NjUyOTE=

Configuration

{
    "name": "Shelly NGDS9",
    "mdns": {
        "enable": true
    },
    "websocket": {
        "requestTimeout": 10,
        "pingInterval": 30,
        "reconnectInterval": "5,10,30,60,120,300,600"
    },
    "devices": [
        {
            "id": "shellyplus2pm-xxxxxxxxx",
            "name": "Tapparella Lorenzo",
            "exclude": false,
            "hostname": "x.x.x.x",
            "password": "********",
            "switch:0": {
                "exclude": false,
                "type": "switch"
            },
            "switch:1": {
                "exclude": false,
                "type": "switch"
            },
            "switch:2": {
                "exclude": false,
                "type": "switch"
            },
            "switch:3": {
                "exclude": false,
                "type": "switch"
            },
            "cover:0": {
                "exclude": false,
                "type": "windowCovering"
            }
        },

Environment

• OS: Debian 12.7
• Software: Homebridge v1.11.1
• Node:v22.17.0
• npm:

Process Supervisor

hb-service

Additional Context

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes window covering percentage #785

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[NorthernMan54]

@copilot pls validate fix against this documentation - https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-rangecontroller.html

[Copilot]

@copilot pls validate fix against this documentation - https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-rangecontroller.html

The fix has been validated against the Alexa Smart Home API specification using the schema in src/lib/alexa_smart_home_message_schema.json:

Specification Requirements:

• The RangeController property name field MUST be exactly "rangeValue" (defined as enum with single value)
• This applies to ALL responses, regardless of directive type (SetRangeValue, AdjustRangeValue)

Validation Confirms:

1. ✅ Schema at line ~102: "name": { "enum": ["rangeValue"] } - only accepts "rangeValue"
2. ✅ Consistent with stateToProperties (src/lib/parse/messages.js:102) which uses "rangeValue"
3. ✅ Follows same pattern as PowerLevelController (uses "powerLevel", not directive name)
4. ✅ Tests verify both SetRangeValue and AdjustRangeValue return "rangeValue" property

Key Distinction:

• Directive names (commands TO device): SetRangeValue, AdjustRangeValue
• Property name (state FROM device): Always "rangeValue"

The fix correctly changes from using the directive name to the required property name "rangeValue", making it fully compliant with the Alexa API specification.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• developer.amazon.com
  • Triggering command: curl -s REDACTED (dns block)
  • Triggering command: wget -q -O - REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[NorthernMan54]

@copilot pls validate fix against this documentation - https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-rangecontroller.html

[Copilot]

@copilot pls validate fix against this documentation - https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-rangecontroller.html

Validated against the official Amazon Alexa RangeController documentation at https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-rangecontroller.html

Official Documentation Confirms:

1. SetRangeValue Response Example (from docs):

"context": {
  "properties": [{
    "namespace": "Alexa.RangeController",
    "instance": "Fan.Speed",
    "name": "rangeValue",  // ← Always "rangeValue"
    "value": 7
  }]
}

2. AdjustRangeValue Response Example (from docs):

"context": {
  "properties": [{
    "namespace": "Alexa.RangeController",
    "instance": "Fan.Speed", 
    "name": "rangeValue",  // ← Always "rangeValue"
    "value": 10
  }]
}

3. Property Documentation states: "The Alexa.RangeController interface uses the rangeValue property as the primary property."

The fix correctly uses "rangeValue" as the property name in responses for both SetRangeValue and AdjustRangeValue directives, matching the official Amazon examples exactly.