Proposal: SmartThings Context Capabilities
Extending the SmartThings API from Device State to Home Context
Executive Summary
SmartThings already has a strong device-centric model. Devices are represented through Device Profiles, Components, Capabilities, Attributes, and Commands. Capabilities are core to the SmartThings architecture because they abstract device functions and allow SmartThings to retrieve the state of a device component or control a device function.
This model works very well for describing what an individual device can do.
However, many advanced smart home experiences depend on information that does not naturally belong to one device. Examples include local weather, rain forecast, solar position, outdoor air quality, room occupancy, average room climate, energy tariffs, hub health, mesh health, privacy state, and overall safety state.
This proposal suggests introducing SmartThings Context Capabilities: a standardized, permissioned, API-accessible, and optionally hub-cached way to expose shared contextual information through the SmartThings platform.
The central idea is:
SmartThings should not only expose what each device reports. SmartThings should also expose what the home, room, location, hub, and network know.
This would make the SmartThings platform more valuable for users, automation developers, Edge Driver developers, SmartApp developers, and device manufacturers — including both Matter device manufacturers and manufacturers using SmartThings Cloud Connected Devices.
Why This Matters for the SmartThings API
The SmartThings API is already positioned as the core API for controlling devices, creating automations, managing Locations, and retrieving user and device information.
Today, however, the API is still primarily built around device state, device commands, locations, rooms, scenes, rules, and installed integrations. That is useful, but it leaves a gap: there is no first-class API object for shared home context.
For example, a manufacturer or developer may want to ask:
What is the local outdoor temperature?
Is rain expected soon?
What is the solar elevation?
Is this room probably occupied?
What is the average room temperature?
Is privacy mode active?
Is there a safety event in this Location?
Is the hub cloud-connected?
Is the Thread or Zigbee network unstable?
Is electricity expensive right now?
Today, that information must usually be inferred from individual devices, external services, virtual devices, proprietary cloud integrations, or custom automation logic.
A SmartThings Context API would make this information available in a standard way.
The Core Opportunity
SmartThings already connects many different integration types:
Cloud Connected Devices
Hub Connected Devices
Direct Connected Devices
Mobile Connected Devices
Matter devices
Edge Drivers
Rules
SmartApps
Partner cloud integrations
Cloud Connected Devices are particularly important here. SmartThings Schema allows manufacturers with an existing cloud to integrate devices into SmartThings using JSON payloads for communication between the manufacturer cloud and SmartThings, including device state events and commands.
That means Context Capabilities should not be designed only for Edge or only for Matter.
They should be part of the SmartThings API layer.
A manufacturer with a cloud-connected irrigation controller, air purifier, thermostat, camera, EV charger, appliance, window covering, robot vacuum, or energy device could benefit just as much as a Matter manufacturer.
The strategic positioning could be:
Device manufacturers bring the device. SmartThings brings the home context.
Or:
SmartThings makes connected devices context-aware, regardless of whether they connect through Matter, Edge, Schema, Direct Connected, or another supported integration path.
Problem
Many advanced automations and product experiences need shared context:
Current outdoor temperature
Rain forecast
Wind speed and gusts
Solar elevation and azimuth
Cloud cover
Outdoor air quality
Pollen level
Room occupancy
Average room temperature
Average room humidity
Window-open state per room
Electricity price
Grid carbon intensity
Hub health
Matter controller state
Thread/Zigbee/Z-Wave network health
Privacy mode
Overall safety state
Water leak state
Smoke/CO state
Today, manufacturers and developers often need to solve this individually.
Typical workarounds include:
Virtual weather devices
Manufacturer-specific weather integrations
Cloud SmartApps
External API bridges
Custom Edge Drivers
Manual virtual switches
Duplicated automations
Hardcoded driver preferences
Device-specific logic
These workarounds create duplicated effort and inconsistent user experiences.
For example:
- A cloud-connected awning manufacturer may need weather and wind data.
- A cloud-connected irrigation manufacturer may need rain forecast and soil moisture.
- A cloud-connected air purifier manufacturer may need outdoor AQI and pollen.
- A cloud-connected camera manufacturer may need privacy state and occupancy context.
- A cloud-connected thermostat manufacturer may need room-level climate aggregation and energy pricing.
- A cloud-connected EV charger manufacturer may need tariff windows, solar forecast, and whole-home load state.
Each manufacturer can build these integrations alone, but that is inefficient. It also produces fragmented behavior across the SmartThings ecosystem.
Proposal
Introduce SmartThings Context Capabilities as a new platform concept exposed through the SmartThings API.
Instead of only exposing:
Device
└── Component
└── Capability
└── Attribute
SmartThings could also expose:
Location
└── Context Capability
└── Attribute
Room
└── Context Capability
└── Attribute
Hub
└── Context Capability
└── Attribute
Network
└── Context Capability
└── Attribute
Example context paths:
location.weather.temperature
location.weather.windGust
location.weather.precipitationProbability
location.daylight.solarElevation
location.daylight.solarAzimuth
location.airQuality.aqi
location.energy.electricityPrice
location.privacy.cameraRecordingAllowed
location.safety.waterLeakState
room.livingRoom.climate.averageTemperature
room.livingRoom.occupancy.state
room.livingRoom.light.averageIlluminance
room.livingRoom.windows.anyOpen
hub.health.cloudConnected
hub.health.localExecutionAvailable
hub.health.firmwareVersion
network.thread.borderRouterCount
network.thread.lastTopologyChange
network.zigbee.lowSignalDeviceCount
network.matter.offlineDeviceCount
This would extend the SmartThings capability philosophy beyond individual devices and into the home itself.
API-First Design
The most important aspect of this proposal is that Context Capabilities should be exposed through the SmartThings API.
Possible API endpoints:
GET /locations/{locationId}/context
GET /locations/{locationId}/context/weather
GET /locations/{locationId}/context/daylight
GET /locations/{locationId}/context/energy
GET /locations/{locationId}/context/privacy
GET /locations/{locationId}/context/safety
GET /locations/{locationId}/rooms/{roomId}/context
GET /locations/{locationId}/rooms/{roomId}/context/climate
GET /locations/{locationId}/rooms/{roomId}/context/occupancy
GET /locations/{locationId}/hubs/{hubId}/context
GET /locations/{locationId}/networks/thread/context
GET /locations/{locationId}/networks/zigbee/context
Example response:
{
"locationId": "home-123",
"weather": {
"temperature": {
"value": 9.4,
"unit": "C",
"updatedAt": "2026-04-29T15:10:00Z",
"expiresAt": "2026-04-29T15:40:00Z",
"source": "SmartThings Weather",
"quality": "estimated"
},
"windGust": {
"value": 42,
"unit": "km/h",
"updatedAt": "2026-04-29T15:10:00Z",
"expiresAt": "2026-04-29T15:40:00Z",
"source": "SmartThings Weather",
"quality": "estimated"
}
},
"daylight": {
"sunrise": "2026-04-29T03:48:00Z",
"sunset": "2026-04-29T18:31:00Z",
"solarElevation": 18.2,
"solarAzimuth": 251.7,
"isDaylight": true
}
}
The important part is that this context is not tied to a specific device unless a user or the platform explicitly selects a device as the source.
Value for Cloud Connected Device Manufacturers
This is one of the strongest selling points.
SmartThings Cloud Connected Devices communicate through SmartThings Schema, where the manufacturer cloud exchanges JSON payloads with the SmartThings Cloud for device state events and commands.
A Context API would give cloud-connected manufacturers a standardized way to build richer device experiences without each manufacturer recreating the same context infrastructure.
Example: Cloud-Connected Irrigation Controller
A manufacturer may already provide:
Valve state
Zone state
Schedule state
Flow state
Fault state
Battery state
But smarter irrigation requires:
Rain forecast
Recent precipitation
Outdoor temperature
Wind speed
Soil moisture
Season
Sun exposure
Water leak state
Watering restrictions
SmartThings could expose:
location.weather.precipitationProbability
location.weather.precipitationExpected
location.weather.temperature
location.weather.windSpeed
location.daylight.dayLength
location.safety.waterLeakState
area.soil.moisture
The manufacturer could then offer a better SmartThings experience without building every environmental integration itself.
Example: Cloud-Connected Air Purifier
The device may provide:
Fan speed
Filter life
Indoor PM2.5
VOC level
Mode
SmartThings Context could provide:
location.airQuality.aqi
location.airQuality.pm25
location.airQuality.pollenIndex
room.occupancy.state
location.intent.quietHours
This would allow the manufacturer to build logic such as:
Run harder when outdoor AQI is poor and windows were recently opened.
Use quiet mode when the room is occupied at night.
Recommend ventilation only when outdoor air is cleaner than indoor air.
Example: Cloud-Connected EV Charger
The device may provide:
Charging state
Plug state
Charging current
Energy delivered
Fault state
SmartThings Context could provide:
location.energy.electricityPrice
location.energy.nextLowPriceWindow
location.energy.gridCarbonIntensity
location.energy.solarForecast
home.workload.highPowerLoadActive
This would allow the manufacturer to offer tariff-aware, carbon-aware, or solar-aware charging inside SmartThings.
Value for Hub Connected and Edge Devices
Edge Drivers currently emit device capability events and receive capability commands. The current Edge model is therefore very device-oriented. Context Capabilities would add a new read-only input layer for drivers.
Possible Lua API:
local temp = driver.context:get({
scope = "location",
group = "weather",
attribute = "temperature"
})
local wind_gust = driver.context:get({
scope = "location",
group = "weather",
attribute = "windGust"
})
Subscription example:
driver.context:subscribe({
scope = "location",
group = "weather",
attribute = "windGust"
}, function(event)
if event.value > 35 then
-- Protect awnings, blinds, skylights, or outdoor equipment.
end
end)
Room context example:
local occupied = device.context.room:get("occupancy.state")
local room_temp = device.context.room:get("climate.averageTemperature")
local window_open = device.context.room:get("windows.anyOpen")
This would benefit SmartThings stock drivers, community Edge Drivers, manufacturer Edge Drivers, LAN integrations, Zigbee, Z-Wave, Matter, and future hub-connected integrations.
Value for Rules and Routines
Context Capabilities could become new Rule operands.
Example:
{
"if": {
"greaterThan": {
"left": {
"locationContext": {
"context": "weather",
"attribute": "windGust"
}
},
"right": {
"decimal": 35
}
},
"then": [
{
"command": {
"devices": ["awning-device-id"],
"commands": [
{
"component": "main",
"capability": "windowShade",
"command": "close"
}
]
}
}
]
}
}
Room context example:
{
"if": {
"and": [
{
"equals": {
"left": {
"roomContext": {
"roomId": "living-room-id",
"context": "occupancy",
"attribute": "state"
}
},
"right": {
"string": "occupied"
}
}
},
{
"lessThan": {
"left": {
"roomContext": {
"roomId": "living-room-id",
"context": "light",
"attribute": "averageIlluminance"
}
},
"right": {
"integer": 80
}
}
}
],
"then": [
{
"command": {
"devices": ["blind-device-id"],
"commands": [
{
"component": "main",
"capability": "windowShade",
"command": "open"
}
]
}
}
]
}
}
For the SmartThings app, these same concepts could appear as Routine conditions:
If wind gust is above 35 km/h
If Living Room is occupied
If outdoor air quality is worse than indoor air quality
If electricity price is low
If privacy mode is active
If any water leak is detected in this Location
Suggested Context Areas
1. Location Weather Context
location.weather.temperature
location.weather.feelsLikeTemperature
location.weather.humidity
location.weather.dewPoint
location.weather.pressure
location.weather.windSpeed
location.weather.windGust
location.weather.windDirection
location.weather.cloudCover
location.weather.precipitationProbability
location.weather.precipitationExpected
location.weather.weatherCondition
location.weather.updatedAt
location.weather.expiresAt
Useful for irrigation, awnings, blinds, heating, cooling, ventilation, outdoor lighting, water protection, and freeze protection.
2. Daylight and Solar Context
location.daylight.sunrise
location.daylight.sunset
location.daylight.civilDawn
location.daylight.civilDusk
location.daylight.solarNoon
location.daylight.solarElevation
location.daylight.solarAzimuth
location.daylight.isDaylight
location.daylight.dayLength
Useful for blinds, shades, lighting, solar gain management, privacy automations, security lighting, and energy optimization.
3. Air Quality Context
location.airQuality.aqi
location.airQuality.pm25
location.airQuality.pm10
location.airQuality.ozone
location.airQuality.pollenIndex
location.airQuality.category
Useful for air purifiers, ventilation, window automation, HVAC, and health-aware routines.
4. Room Context
room.climate.averageTemperature
room.climate.averageHumidity
room.occupancy.state
room.occupancy.confidence
room.light.averageIlluminance
room.windows.anyOpen
room.airQuality.summary
room.comfort.score
Useful for thermostats, radiator valves, fans, air purifiers, lighting, blinds, and presence-aware automation.
5. Energy Context
location.energy.electricityPrice
location.energy.electricityPriceLevel
location.energy.nextLowPriceWindow
location.energy.nextHighPriceWindow
location.energy.gridCarbonIntensity
location.energy.solarForecast
location.energy.demandResponseActive
Useful for EV chargers, batteries, heat pumps, dishwashers, washing machines, dryers, water heaters, smart plugs, and energy dashboards.
6. Safety Context
location.safety.smokeState
location.safety.coState
location.safety.waterLeakState
location.safety.freezeState
location.safety.intrusionState
location.safety.highestSeverity
location.safety.affectedRooms
Useful for water valves, sirens, locks, lights, cameras, notifications, and insurance-related services.
7. Privacy Context
location.privacy.privacyMode
location.privacy.cameraRecordingAllowed
location.privacy.microphoneAllowed
location.privacy.presenceDetailAllowed
location.privacy.guestPrivacyMode
Useful for cameras, presence sensors, mmWave sensors, microphones, voice devices, and room-aware automations.
8. Hub and Network Context
hub.health.cloudConnected
hub.health.localExecutionAvailable
hub.health.firmwareVersion
hub.health.firmwareUpdateAvailable
hub.health.zigbeeRadioState
hub.health.zwaveRadioState
hub.health.threadRadioState
hub.health.matterControllerState
network.thread.borderRouterCount
network.thread.lastTopologyChange
network.thread.routeInstability
network.zigbee.lowSignalDeviceCount
network.zwave.routeChanges
network.matter.offlineDeviceCount
Useful for diagnostics, support, device onboarding, Matter reliability, Thread troubleshooting, Zigbee troubleshooting, advanced Edge Drivers, and manufacturer support workflows.
Hub-Cached Context
Some context can live purely in the cloud, but the most useful context should be hub-cached where possible.
Recommended model:
Cloud service fetches or calculates context
↓
SmartThings normalizes context into standard attributes
↓
Hub receives a signed context snapshot
↓
Rules and Edge Drivers use latest local snapshot where supported
↓
Cloud refreshes periodically
Each value should include freshness metadata:
{
"value": 12.7,
"unit": "C",
"updatedAt": "2026-04-29T15:10:00Z",
"expiresAt": "2026-04-29T15:40:00Z",
"source": "SmartThings Weather",
"quality": "estimated",
"confidence": 0.82
}
This allows automations, apps, and drivers to distinguish between:
fresh value
stale value
missing value
estimated value
measured value
derived value
user-selected source value
That matters for safety-relevant use cases such as awnings, water valves, heating, cooling, cameras, and security behavior.
Source Selection and Fallbacks
SmartThings could allow users to configure preferred sources for context values.
Example:
Outdoor temperature source priority:
1. Garden weather station
2. Balcony temperature sensor
3. SmartThings local weather
4. Regional weather fallback
Then automations, API clients, Rules, and drivers can simply consume:
location.outdoor.temperature
The metadata would still show the source:
{
"value": 8.6,
"unit": "C",
"source": "Garden Weather Station",
"quality": "measured"
}
or:
{
"value": 9.4,
"unit": "C",
"source": "SmartThings Weather",
"quality": "estimated"
}
This combines the simplicity of platform-provided context with the accuracy of real local sensors.
Permissions and Privacy
Context access should be permissioned through the SmartThings API authorization model.
Low-risk context could use simple read scopes:
r:locations:context:weather
r:locations:context:daylight
r:locations:context:airQuality
Sensitive context should require more explicit authorization:
r:locations:context:occupancy
r:rooms:context:occupancy
r:locations:context:privacy
r:locations:context:safety
r:locations:context:security
This is important because not every integration needs sensitive household state.
A blind controller may reasonably need daylight and weather.
A camera integration may need privacy state.
An EV charger may need energy context.
A simple light integration probably does not need detailed occupancy, security, or privacy state.
