Home API Reference
Commissioner APIs
Overview
The Commissioner API allows you to control devices and allows these devices to communicate with each other. Device commissioning is the process of joining a device to SmartThings.
To commission a device, you need to use the CommissioningClient API.
API Reference
Device Commissioning
Required packages
import com.samsung.android.matter.home.api.Matter
import com.samsung.android.matter.home.api.CommissioningResult
Create a CommissioningClient instance through the following API. This is the entry point for the Commissioning features.
| API | Return | Description |
|---|---|---|
| Matter.getCommissioningClient() | CommissioningClient | Creates an instance of the Commissioning Client. |
Once you have a CommissioningClient instance, you can use the following APIs to commission a device to SmartThings fabric.
This API returns an IntentSender, which launches the onboarding activity in Home Service.
| API | Return | Description |
|---|---|---|
| commissionDevice(context: Context) | IntentSender | Commission a device into SmartThings fabric. |
Device Sharing
Required packages
import com.samsung.android.matter.home.api.Matter
import com.samsung.android.matter.home.api.SharingResult
Create a CommissioningClient instance through the following API. This is the entry point for the Commissioning features.
| API | Return | Description |
|---|---|---|
| Matter.getCommissioningClient() | CommissioningClient | Creates an instance of the Commissioning Client. |
Once you have a CommissioningClient instance, you can use the following APIs to share the device to other platforms. This API returns an IntentSender, which launches the device sharing activity in Home Service.
| API | Return | Description |
|---|---|---|
| shareDevice(context: Context, shareDeviceRequest: ShareDeviceRequest | IntentSender | Share a device to other platforms. shareDeviceRequest : set the device id as ShareDeviceRequest(deviceId) |
Controller APIs
Overview
Capabilities are core to the SmartThings architecture. They abstract specific devices into their underlying functions, allowing us to retrieve the state of a Device component or control a function of the Device. And the capabilities of each device are dependent on the manufacturer and the device itself. So the Home API also works based on capabilities.
Supported Device Type and available capability
| Device Type | Available Capabilities |
|---|---|
| Switch | Switch SwitchLevel ColorControl ColorTemperature |
| Light Switch | SwitchLevel ColorControl ColorTemperature |
| Door Lock (Smart Lock) | Lock LockCodes TamperAlert Battery |
| Contact Sensor | ContactSensor Battery |
| Motion Sensor | MotionSensor Battery |
| Thermostat | TemperatureMeasurement ThermostatMode ThermostatFanMode ThermostatHeatingSetpoint ThermostatCoolingSetpoint ThermostatOperatingState RelativeHumidityMeasurement Battery |
| Window Covering (Blind) | WindowShade WindowShadePreset WindowShadeLevel Battery |
| Media (Television) | MediaPlayback MediaTrackControl KeypadInput Switch |
API Reference
Required packages
import com.samsung.android.matter.home.api.Matter
import com.samsung.android.matter.home.api.capability.*
Create a MatterClient instance through the following API. This is the entry point for the Controller features.
| API | Return | Description |
|---|---|---|
| Matter.getClient(context: Context) | HomeClient Creates an instance of the Matter Client. |
Once you have a MatterClient instance, you can get a device by the device id.
| API | Return | Description |
|---|---|---|
| getDevice(deviceId: String) | Device? | Get a device that has capabilities by the device id |
Once you have a Device , you can get a Capability per each device type. Then you can control the device and can get the device state.
| API | Return | Description |
|---|---|---|
| readCapability(capability: CapabilityFactory T) | T? | Get a capability that has control command and device attribute |
Once you have a Capability , you can use the following control APIs per each device type.
All commands are suspend functions and completed only when a response is received from the API. When command is completed, the API will return either 1) completed, or 2) error.
Battery capability
Attributes
| Name | Type | Description |
|---|---|---|
| battery | Int [0..100] | An indication of the status of the battery |
ColorControl capability
Commands
| API | Return | Description |
|---|---|---|
| setColor(hue: Double, saturation: Double) | DeviceCommandResult | Send a command to set the hue and saturation value of the color (hue, saturation - refer to the following APIs) |
| setHue(hue: Double) | DeviceCommandResult | Send a command to set the hue value of the color (hue - a number in the range ‘0-100’ representing the hue as a value of percent) |
| setSaturation(saturation: Double) | DeviceCommandResult | Send a command to set the saturation value of the color (saturation - a number in the range ‘0-100’ representing the saturation as a value of percent) |
Attributes
| Name | Type | Description |
|---|---|---|
| color | String | NOT SUPPORTED YET |
| hue | Double [0..100] | A number in the range ‘0-100’ representing as a value of percent |
| saturation | Double [0..100] | A number in the range ‘0-100’ representing as a value of percent |
ColorTemperature capability
Commands
| API | Return | Description |
|---|---|---|
| setColorTemperature(temperature: Int) | DeviceCommandResult | Send a command to set the color temperature - the value to set the color temperature attribute to, in Kelvin [1 - 30000] |
Attributes
| Name | Type | Description |
|---|---|---|
| colorTemperature | Int [1 - 30000] | A number that represents the color temperature, measured in degrees Kelvin |
ContactSensor capability
Attributes
| Name | Type | Description |
|---|---|---|
| contact | Enum | The current state of the contact sensor (open, closed) |
KeypadInput capability
Commands
| API | Return | Description |
|---|---|---|
| sendKey(key: KeyCode) | DeviceCommandResult | Send keypad input to process a keycode as input to the media device. (key - the key code to process [enum]) |
Lock capability
Commands
| API | Return | Description |
|---|---|---|
| lock() | DeviceCommandResult | Send a command to lock the lock |
| unlock() | DeviceCommandResult | Send a command to unlock the lock |
Attributes
| Name | Type | Description |
|---|---|---|
| lock | Enum | The current state of the contact sensor (locked, unlocked) |
LockCodes capability
Commands
| API | Return | Description |
|---|---|---|
| deleteCode(codeSlot: Int) | DeviceCommandResult | Send a command to delete the code |
| lock() | DeviceCommandResult | Send a command to lock the lock |
| reloadAllCodes() | DeviceCommandResult | Send a command to reload all the codes |
| requestCode(codeSlot: Int) | DeviceCommandResult | Send a command to request a code |
| setCode(codeSlot: Int, codePin: String, codeName: String) | DeviceCommandResult | Send a command to set a code (codeSlot - a number of code slot to delete [0..∞]; codePin - a pin string for the code [string]; codeName - a code name for the code [string] |
| setCodeLength(length: Int) | DeviceCommandResult | Send a command to set the code length for the code |
| unlock() | DeviceCommandResult | Send a command to unlock the lock |
| updateCodes(codes: Any) | DeviceCommandResult | Send a command to update the codes |
Attributes
| Name | Type | Description |
|---|---|---|
| codeChanged | String | NOT SUPPORTED YET |
| codeLength | Int | NOT SUPPORTED YET |
| codeReport | Int | NOT SUPPORTED YET |
| lock | Boolean | NOT SUPPORTED YET |
| lockCodes | String | NOT SUPPORTED YET |
| maxCodeLength | Int | NOT SUPPORTED YET |
| maxCodes | Int | NOT SUPPORTED YET |
| minCodeLength | Int | NOT SUPPORTED YET |
| scanCodes | String | NOT SUPPORTED YET |
MediaPlayback capability
Commands
| API | Return | Description |
|---|---|---|
| fastForward() | DeviceCommandResult | Send a command to fast forward the media playback |
| pause() | DeviceCommandResult | Send a command to pause the media playback |
| stop() | DeviceCommandResult | Send a command to stop the media playback |
Attributes
| Name | Type | Description |
|---|---|---|
| playbackStatus | Enum | Status of the media playback (paused - Media playback is in a "paused" state, playing - Media playback is in a "playing" state, stopped - Media playback is in a "stopped" state, fast forwarding - Media playback is in a "fast forwarding" state, rewinding - Media playback is in a "rewinding" state, buffering - Media playback is in a "buffering" state |
| supportedPlaybackCommands | Array of Enum | NOT SUPPORTED YET |
MediaTrackControl capability
Commands
| API | Return | Description |
|---|---|---|
| nextTrack() | DeviceCommandResult | Send a command to go to the next track |
| previousTrack() | DeviceCommandResult | Send a command to go to the previous track |
MotionSensor capability
Attributes
| Name | Type | Description |
|---|---|---|
| motion | Enum | The current state of the motion sensor (active - The value when motion is detected, inactive - The value when no motion is detected) |
Switch capability
Commands
| API | Return | Description |
|---|---|---|
| on() | DeviceCommandResult | Send an on command to the device |
| off() | DeviceCommandResult | Send an off command to the device |
Attributes
| Name | Type | Description |
|---|---|---|
| switch | Enum | The state of whether the the switch (on, off) |
SwitchLevel capability
Commands
| API | Return | Description |
|---|---|---|
| setLevel(level: Int) | DeviceCommandResult | Send a command to set the level of a device like a light or a dimmer switch. level - a number that represents the current level, usually ‘0-100’ in percent |
Attributes
| Name | Type | Description |
|---|---|---|
| level | Int [0..100] | A number in the range ‘0-100’ representing as a value of percent |
TamperAlert capability
Attributes
| Name | Type | Description |
|---|---|---|
| tamper | Enum | A number that represents the current level (clear - not tampered detected - tampered) |
TemperatureMeasurement capability
Attributes
| Name | Type | Description |
|---|---|---|
| temperature | Double [-460..10000] | A number that usually represents the current temperature in Fahrenheit |
ThermostatCoolingSetpoint capability
Commands
| API | Return | Description |
|---|---|---|
| setCoolingSetpoint(setpoint: Double) | DeviceCommandResult | Send a command to set the cooling setpoint (a value that the cooling setpoint should be set to number [-460..10000]) |
Attributes
| Name | Type | Description |
|---|---|---|
| coolingSetpoint | Double [-460..10000] | The current cooling setpoint |
ThermostatFanMode capability
Commands
| API | Return | Description |
|---|---|---|
| fanAuto() | DeviceCommandResult | Send a command to set the fan mode to auto |
| fanCirculate() | DeviceCommandResult | Send a command to set the fan mode to circulate |
| fanOn() | DeviceCommandResult | Send a command to set the fan mode to on |
| setThermostatFanMode(mode: String) | DeviceCommandResult | Send a command to set the thermostat fan mode (auto , circulate , followschedule , on) |
Attributes
| Name | Type | Description |
|---|---|---|
| thermostatFanMode | Enum | The current mode of the fan on a thermostat (auto - The fan is on auto; circulate - The fan is circulating; followschedule - The fan is set to follow predefined schedule; on - The fan is on) |
ThermostatHeatingSetpoint capability
Commands
| API | Return | Description |
|---|---|---|
| setHeatingSetpoint(setpoint: Double) | DeviceCommandResult | Send a command to set the heating setpoint (setpoint: a value that the heating setpoint should be set to number [-460..10000]) |
Attributes
| Name | Type | Description |
|---|---|---|
| heatingSetpoint | Double [-460..10000] | The current heating setpoint |
ThermostatMode capability
Commands
| API | Return | Description |
|---|---|---|
| auto() | DeviceCommandResult | Send a command to set the mode to 'auto' |
| cool() | DeviceCommandResult | Send a command to set the mode to 'cool' |
| emergencyHeat() | DeviceCommandResult | Send a command to set the mode to 'emergency heat' |
| heat() | DeviceCommandResult | Send a command to set the mode to 'heat' |
| off() | DeviceCommandResult | Send a command to set the mode to 'off' |
Attributes
| Name | Type | Description |
|---|---|---|
| thermostatMode | Enum | The current mode of a thermostat (auto, cool, heat, off) |
ThermostatOperatingState capability
Attributes
| Name | Type | Description |
|---|---|---|
| thermostatOperatingState | Enum | The current state that the thermostat is operating in (cooling, fan only, heating, idle, pending cool, pending heat, vent economizer) |
WindowShade capability
Commands
| API | Return | Description |
|---|---|---|
| close() | DeviceCommandResult | Send a command to close the window shade |
| open() | DeviceCommandResult | Send a command to open the window shade |
| pause() | DeviceCommandResult | Send a command to pause opening or closing the window shade |
Attributes
| Name | Type | Description |
|---|---|---|
| windowShade | Enum | An indication of the status of the window shade (closed, closing, open, opening, partially open, unknown) |
WindowShadeLevel capability
Commands
| API | Return | Description |
|---|---|---|
| setShadeLevel(shadeLevel: Int) | DeviceCommandResult | Send a command to set the shade level to the given value (integer [0..100]) |
Attributes
| Name | Type | Description |
|---|---|---|
| shadeLevel | Int [0..100] | A number that represents the current level as a function of being open, ‘0-100’ in percent (0: closed; 100: open). |
WindowShadePreset capability
Commands
| API | Return | Description |
|---|---|---|
| presetPosition() | DeviceCommandResult | Send a command to open window shade to a preset position |
Location APIs
Overview
Location in SmartThings is the main entity for your connected Devices.
Room is the best way to group devices in SmartThings. You can use Rooms to separate your devices into distinct areas and more easily organize large lists of connected devices.
So you need to get the Locations and Rooms then you can get the Devices.
API Reference
Required packages
import com.samsung.android.matter.home.api.Matter
Create a MatterClient instance through the following API. This is the entry point for the location features.
| API | Return | Description |
|---|---|---|
| Matter.getClient(context: Context) | HomeClient | Creates an instance of the Matter Client. |
Once you have a MatterClient instance, you can get location information.
All commands are suspend functions and complete only when received a response from the API. It means the state of device has changed if there is no error.
| API | Return | Description |
|---|---|---|
| getLocations() | Flow: List > Location | Get a list of locations that belong to your account. |
| getRooms() | Flow: List > Room | Get a list of rooms in location that belong to your account. |
| getDevices() | Flow: List > Device | Get a list of devices in room that belong to your account. |