Smartthings

SmartThings

Purpose

Read device status and issue capability commands across a Samsung SmartThings account: locations, devices, switches, dimmers, locks, thermostats, sirens, garage door controllers, and window shades. Use it when the user asks about or wants to change the state of anything paired to their SmartThings hub or cloud account. This connector drives real physical hardware, so every write is confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/smartthings.py:

bin/smartthings.py auth                                    # status check: verify token, list locations
bin/smartthings.py locations                               # list locations
bin/smartthings.py devices --limit 50                      # list devices with capabilities
bin/smartthings.py status --id <deviceId>                  # read full device status

# Writes. HIGH actuations (lock unlock, garage open/close) REQUIRE
# --confirm naming the exact physical effect, on every run:
bin/smartthings.py command --id <deviceId> --capability lock --command unlock \
    --confirm "unlock front door deadbolt"
bin/smartthings.py command --id <deviceId> --capability garageDoorControl --command open \
    --confirm "open the garage door"

# MEDIUM actuations (switches, dimmers, thermostats, sirens) need --confirm on
# first use per device; later runs proceed without it:
bin/smartthings.py command --id <deviceId> --capability switch --command on \
    --confirm "turn on the living room lamp"
bin/smartthings.py command --id <deviceId> --capability switchLevel --command setLevel \
    --arg 50 --confirm "dim bedroom light to 50 percent"
bin/smartthings.py command --id <deviceId> --capability thermostatMode \
    --command setThermostatMode --arg '"heat"' --confirm "set hallway thermostat to heat"
bin/smartthings.py command --id <deviceId> --capability alarm --command both \
    --confirm "sound the hallway siren"

# LOW actuations (window shades / curtains) proceed with a logged notice:
bin/smartthings.py command --id <deviceId> --capability windowShadeLevel \
    --command setShadeLevel --arg 100

--arg values are JSON-parsed, so pass numbers bare (--arg 50) and strings as quoted JSON (--arg '"heat"') or plain text (falls back to a string). --component defaults to main; set it when the device exposes other components.

Auth

• Provider id: smartthings (credential is collected as custom.smartthings)
• Collection: OAuth 2.0 authorization-code flow via the secure credential flow (credentials.request_api_access). Set up: create an app at developer.smartthings.com with the scopes the user needs (devices read, device commands), complete the authorization-code grant, and store the resulting access token. Personal Access Tokens now expire after about 24 hours, so a persistent connector must use the OAuth flow.
• Required scopes: r:devices:* at minimum for reads; add x:devices:* (commands) only for the devices the user wants Muse to actuate.
• Allowed hosts: api.smartthings.com
• Status check: bin/smartthings.py auth

Operating Rules

1. HIGH actuations are blocked without explicit confirmation. Unlocking a lock and opening or closing a garage door require --confirm "<exact physical effect>" on every single run, e.g. --confirm "unlock front door deadbolt". A bare --confirm or a vague value is rejected by the CLI. Never pre-fill the confirmation on the user's behalf: the exact effect must come from the user's own words.
2. MEDIUM actuations confirm on first use per device. Switches, dimmers, thermostat modes and setpoints, and siren on/off need --confirm the first time a device is actuated; the CLI records that confirmation locally (~/.config/muse-connectors/smartthings/confirmed.json) and later runs proceed. A thermostat change starts or stops real heating/cooling; treat every MEDIUM run as if the user is watching.
3. LOW actuations (window shades, curtains) proceed with a notice printed to stderr. No confirmation needed.
4. Never lock someone out or in. Do not lock a door unless the user explicitly asked for that lock to be locked; locking is a write and follows the same grading as unlock (MEDIUM, first-use confirmed) but verify intent twice in conversation first.
5. Read commands (auth, locations, devices, status) never need confirmation.
6. Rate limit: roughly 120 requests/min on the commands endpoint per device/principal. Space out bulk actuations.
7. Cost warning: Samsung announced paid SmartThings tiers starting October 2026 (about $4.99/month for the personal tier). Heavy or always-on use may fall under a paid tier.
8. Zigbee/Z-Wave devices need a SmartThings hub online; cloud-only devices work without one.
9. Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the token value.