---
name: "SmartLampAdvancedAbility"
mode: "api"
versionRequirements:
  - { name: "", version: "1.15.0" }
title: "SDM lamp advanced ability — color temperature & thousandth brightness"
summary: "Guide to SDM lamp advanced abilities: color temperature conversion and thousandth-brightness. The SDK standardizes: checking whether advanced mode is on, converting temperature/brightness with units, and reading VAS keypoint info."
questions:
  - "What does getAdvanceHighEnabled check when you pass 'bright_value' vs 'temp_value'?"
  - "What fields does convertTemperature return in result (e.g. display like 2700K)?"
  - "What are convertBrightness return value and unit?"
  - "What do SmartLampAdvancedAbility options debug and waitForInit control at init?"
  - "From which @ray-js/panel-sdk version is SmartLampAdvancedAbility available (1.15.0)?"
  - "How can a panel show raw vs converted values based on getAdvanceHighEnabled?"
  - "What do getAdvancedTemperatureVas and getAdvancedBrightnessVas return (ranges, units)?"
  - "How do you get lampAdv via useInstance() and call convertTemperature in React?"
  - "How do you register SmartLampAdvancedAbility on SmartDeviceModel abilities in devices/index.ts under SDM?"
  - "How can a color-temp slider combine getAdvanceHighEnabled and convertTemperature for display?"
---

# Usage

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Single device</span>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group support</span>
</div>

<Callout type="info" emoji="ℹ️">
The lamp advanced capability SDK standardizes:
- Whether advanced capabilities are enabled
- Color temperature value and unit conversion
- Brightness value and unit conversion
- VAS keypoint information
</Callout>

## Get started

SmartLampAdvancedAbility has been available since @ray-js/panel-sdk@1.15.0.

## SmartLampAdvancedAbility

> [VERSION] v1.15.0+

> 💡 Use after mounting through the SmartDeviceModel abilities configuration. Supports both single devices and group devices.

### Description

Advanced lighting capability that provides advanced conversion for color temperature/brightness and VAS information queries

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `props` | `SmartLampAdvancedAbilityOptions` | Yes | Initialization configuration for advanced lighting capability |

### Return Value

Type: `SmartLampAdvancedAbility`

SmartLampAdvancedAbility instance

#### Methods

| Method | Description |
| --- | --- |
| `convertTemperature` | Convert color temperature value: if the device has the advanced color temperature capability enabled, return a display value with unit (e.g., 2700K); otherwise return the raw value and an empty unit. |
| `convertBrightness` | Convert brightness value: if the device has the thousandth-level brightness capability enabled, return a display value with unit; otherwise return the raw value and an empty unit. |
| `getAdvancedTemperatureVas` | Get advanced color temperature VAS (value-added service) info, including keypoints (display value, raw value, unit) for color-temperature range and display. |
| `getAdvancedBrightnessVas` | Get advanced brightness (thousandth-level) VAS info, including keypoints, for brightness range and unit display. |
| `getAdvanceHighEnabled` | Check whether the specified DP’s advanced capability is enabled: supports bright_value (thousandth-level brightness), temp_value (standard color temperature), color_temp_control (Matter color temperature). |
| `convertDp` | Convert a raw DP value to a display value with unit by DP; supports bright_value, temp_value, color_temp_control. |

### Referenced Types

##### `interface` SmartLampAdvancedAbilityOptions

| Property | Type | Description |
| --- | --- | --- |
| `deviceId` | `string` | Device ID. If not provided, getLaunchOptions is used to obtain the device ID in the current environment. |
| `groupId` | `string` | Group ID. If not provided, getLaunchOptions is used to obtain the group ID in the current environment. |
| `debug` | `boolean` | Whether to enable debug mode |
| `waitForInit` | `boolean` | Whether to preload data |


### Examples

#### Example

```typescript
import { SmartDeviceModel, SmartLampAdvancedAbility } from '@ray-js/panel-sdk';

const sdm = new SmartDeviceModel({ abilities: [new SmartLampAdvancedAbility({})] });
```