home-assistant.io/source/_components/smartthings.markdown

layout, title, description, date, sidebar, comments, sharing, footer, featured, logo, ha_category, ha_release, ha_iot_class, redirect_from

layout	title	description	date	sidebar	comments	sharing	footer	featured	logo	ha_category	ha_release	ha_iot_class	redirect_from
page	SmartThings	Instructions on setting up Samsung SmartThings within Home Assistant.	2018-01-14 00:00	true	false	true	true	true	samsung_smartthings.png	Hub Binary Sensor Climate Fan Light Lock Sensor Switch	0.87	Cloud Push	/components/smartthings.binary_sensor/ /components/binary_sensor.smartthings/ /components/smartthings.climate/ /components/climate.smartthings/ /components/smartthings.fan/ /components/fan.smartthings/ /components/smartthings.light/ /components/light.smartthings/ /components/smartthings.lock/ /components/lock.smartthings/ /components/smartthings.sensor/ /components/sensor.smartthings/ /components/smartthings.switch/ /components/switch.smartthings/

Samsung SmartThings is integrated into Home Assistant through the SmartThings Cloud API. The SmartThings component is the main component to integrate all SmartThings related platforms. The basic features of this integration include:

1. Controlling SmartThings devices with pushed state updates from SmartThings.
2. Entities automatically added, removed, or updated when changed in SmartThings (upon Home Assistant restart).
3. Support for multiple SmartThings accounts and locations, each represented as a unique integration in the front-end configuration.
4. No brokers, bridges, or additional dependencies.

{% linkable_title Basic requirements %}

1. A personal access token tied to a Samsung or SmartThings account (see below for instructions).
2. Home Assistant setup for remote access via a domain name secured with SSL. Self-signed SSL certificates are not supported by the SmartThings Cloud API.
3. base_url of the http component set the URL that Home Assistant is available on the internet.

{% linkable_title Setup instructions %}

{% linkable_title Create personal access token %}

1. Log into the personal access tokens page and click 'Generate new token'
2. Enter a token name (can be whatever you want), for example, 'Home Assistant' and select the following authorized scopes:
   • Devices (all)
   • Installed Apps (all)
   • Locations (all)
   • Apps (all)
   • Schedules (all)
   • Scenes (all)
3. Click 'Generate token'. When the token is displayed, copy and save it somewhere safe (such as your keystore) as you will not be able to retrieve it again.

{% linkable_title Configure Home Assistant %}

The SmartThings component is configured exclusively through the front-end. Manual setup through `configuration.yaml` is not available at this time.

1. From the Home Assistant front-end, navigate to 'Configuration' then 'Integrations'. Under 'Set up a new integration' locate 'SmartThings' and click 'Configure'.
2. Enter the personal access token created above and click 'Submit'
3. When prompted, install the SmartApp:
   1. Open the SmartThings Classic mobile app. Navigate to 'Automation' and select the 'SmartApps' tab.
   2. Click 'Add a SmartApp', scroll to the bottom, and select 'My Apps', then choose 'Home Assistant'.
   3. Optionally change the display name and press 'Done'
   4. Authorize the app by pressing 'Allow'
4. Return to Home Assistant and click 'Submit'.

Advanced: If you have multiple locations in SmartThings, each can be integrated into Home Assistant. Follow the steps above, then for each subsequent location, install the SmartApp and it will automatically add to Home Assistant. This can be completed during step 3 (install SmartApp) above or at any time after that.

{% linkable_title Events %}

The SmartThings component triggers events for select device capabilities.

{% linkable_title smartthings.button %}

The component will trigger an event when a device with the button capability is actuated and can be used to trigger automations within Home Assistant. Below is an example of the data payload:

{
  "component_id": "main",
  "device_id": "42a16cf2-fef7-4ee8-b4a6-d32cb65474b7",
  "location_id": "2a54b9fa-f66c-42d9-8488-d8f036b980c8",
  "value": "pushed",
  "name": "Scene Button"
}

Attribute	Description
component_id	Describes which component of the device triggered the event. main represents the parent device. For devices with child-devices, this attribute identifies the child that raised the event.
device_id	The unique id of the device in SmartThings. This can be located in the HASS device registry or in the SmartThings Groovy IDE.
location_id	The unique id of the location the device is part of. This can be found in the config entry registry or in the SmartThings Groovy IDE.
value	Describes the action taken on the button. See the button capability reference for a list of possible values (not all are supported by every device).
name	The name given to the device in SmartThings.

{% linkable_title Platforms %}

SmartThings represents devices as a set of capabilities and the SmartThings component maps those to entity platforms in Home Assistant. A single device may be represented by one or more platforms.

• Binary Sensor
• Climate
• Fan
• Light
• Lock
• Sensor
• Switch

Support for additional platforms will be added in the future.

{% linkable_title Binary Sensor %}

The SmartThings Binary Sensor platform lets you view devices that have binary sensor-related capabilities. A Binary Sensor entity will be created for each attribute (below) supported by the device.

Capability	Attribute	On-Value
accelerationSensor	acceleration	active
contactSensor	contact	open
filterStatus	filterStatus	replace
motionSensor	motion	active
presenceSensor	presence	present
tamperAlert	tamper	detected
valve	valve	open
waterSensor	water	wet

{% linkable_title Climate %}

The SmartThings Climate platform lets you control devices that have thermostat-related capabilities. For a SmartThings device to be represented by the climate platform, it must have all the capabilities from either "set a" or "set b":

Capability	Climate Features
thermostat (set a)	operation mode, operating state (state attribute), target temp high, target temp low and fan mode
thermostatMode (set b)	operation mode
thermostatCoolingSetpoint (seb b)	target temp low
thermostatHeatingSetpoint (set b)	target temp high
temperatureMeasurement (set b)
thermostatOperatingState	operating state (state attribute)
thermostatFanMode	fan mode
relativeHumidityMeasurement	humidity (state attribute)

{% linkable_title Fan %}

The SmartThings Fan platform lets you control devices that have fan-related capabilities. For a SmartThings device to be represented by the fan platform, it must have one or more of the capabilities below in addition to the switch capability.

Capability	Fan Features
fanSpeed	speed (off, low, medium, and high)

{% linkable_title Light %}

The SmartThings Light platform lets you control devices that have light-related capabilities. For a SmartThings device to be represented by the light platform, it must have one or more of the capabilities below in addition to the switch capability.

Capability	Light Features
switchLevel	brightness and transition
colorControl	color
colorTemperature	color_temp

{% linkable_title Lock %}

The SmartThings Lock platform lets you control devices that have the lock capability, showing current lock status and supporting lock and unlock commands.

{% linkable_title Sensor %}

The SmartThings Sensor platform lets your view devices that have sensor-related capabilities. A Sensor entity is created for each attribute (below) supported by the device.

Capability	Attributes
activityLightingMode	lightingMode
airConditionerMode	airConditionerMode
airQualitySensor	airQuality
alarm	alarm
audioVolume	volume
battery	battery
bodyMassIndexMeasurement	bmiMeasurement
bodyWeightMeasurement	bodyWeightMeasurement
carbonDioxideMeasurement	carbonDioxide
carbonMonoxideDetector	carbonMonoxide
carbonMonoxideMeasurement	carbonMonoxideLevel
dishwasherOperatingState	machineState, dishwasherJobState and completionTime
doorControl	door
dryerMode	dryerMode
dryerOperatingState	machineState, dryerJobState and completionTime
dustSensor	fineDustLevel and dustLevel
energyMeter	energy
equivalentCarbonDioxideMeasurement	equivalentCarbonDioxideMeasurement
formaldehydeMeasurement	formaldehydeLevel
garageDoorControl	door
illuminanceMeasurement	illuminance
infraredLevel	infraredLevel
lock	lock
mediaInputSource	inputSource
mediaPlaybackRepeat	playbackRepeatMode
mediaPlaybackShuffle	playbackShuffle
mediaPlayback	playbackStatus
odorSensor	odorLevel
ovenMode	ovenMode
ovenOperatingState	machineState, ovenJobState and completionTime
ovenSetpoint	ovenSetpoint
powerMeter	power
powerSource	powerSource
refrigerationSetpoint	refrigerationSetpoint
relativeHumidityMeasurement	humidity
robotCleanerCleaningMode	robotCleanerCleaningMode
robotCleanerMovement	robotCleanerMovement
robotCleanerTurboMode	robotCleanerTurboMode
signalStrength	lqi and rssi
smokeDetector	smoke
temperatureMeasurement	temperature
thermostatCoolingSetpoint	coolingSetpoint
thermostatFanMode	thermostatFanMode
thermostatHeatingSetpoint	heatingSetpoint
thermostatMode	thermostatMode
thermostatOperatingState	thermostatOperatingState
thermostatSetpoint	thermostatSetpoint
tvChannel	tvChannel
tvocMeasurement	tvocLevel
ultravioletIndex	ultravioletIndex
voltageMeasurement	voltage
washerMode	washerMode
washerOperatingState	machineState, washerJobState and completionTime
windowShade	windowShade

{% linkable_title Switch %}

The SmartThings Switch platform lets you control devices that have the switch capability that are not already represented by a more specific platform.