Samsung SmartThings

Service overview

What is Samsung SmartThings?

peaqOS exposes Samsung SmartThings through a native adapter. The operator installs peaqOS’s catalog SmartApp in their SmartThings location and sends their own Samsung access token request-scoped as `providerCredentials.smartthings.accessToken`; peaqOS never stores it and resolves the operator’s installation from it on every request. A paired Machine Agent lists the devices that token reaches in one location, filtered to a generic capability catalog — today the lock and switch capabilities — reads their state and health, subscribes to attribute changes delivered over an authenticated event stream, and orders commands: lock, unlock, on, off. Every unlock runs under a single-use runtime task that its order creates and that expires 15 minutes later; a command dispatches at most once and reports accepted, rejected, unknown, or not-dispatched separately from whether the device’s state later matched. Nothing is paid, and peaqOS records the order, execution, and audit trail. SmartThings is Samsung’s connected-device platform, reaching Matter, Zigbee, Z-Wave, Thread, and Wi-Fi devices through one API. The adapter is in development: all four operations are implemented, and command confirmation against a live SmartThings installation is still being validated.

How it works

1. Step 1

   Install the SmartApp

   The operator installs peaqOS’s catalog SmartApp in their SmartThings location and completes OAuth outside peaqOS; the token pair stays with the operator.

2. Step 2

   Send the token

   Pass accessToken under providerCredentials.smartthings on every request that reaches SmartThings; peaqOS resolves the installation from it and never stores it.

3. Step 3

   Pair and call

   With a current signed pairing, the agent lists and reads devices directly and places free orders to subscribe or command; peaqOS stores the run, outcome, and audit trail.

Adapter operations

Behind peaqOS — the paired agent calls peaqOS with the operator’s request-scoped SmartThings token, peaqOS calls the SmartThings API and never keeps the token. Reads run directly; subscriptions and commands run as free orders.

• GETlist-devices

  List the devices the token reaches in one SmartThings location, each with its catalog capabilities and commands; up to 500 per page with a continuation cursor.

• GETget-device-state

  Read a device’s catalog attributes — lock state, switch state — with the provider’s observed time, a freshness flag, and the device’s online health.

• POSTsubscribe-events

  Open a finite lease on one device’s attributes (60–3600 s, 1800 by default); SmartThings pushes changes to peaqOS, which serves them on an authenticated event stream with replay.

• POSTexecute-command

  Order lock, unlock, on, or off under a stable commandId; unlock runs under a single-use task, and an optional postcondition is observed for up to 120 s.

Integration fields

Wire Samsung into peaqOS

providerKey

smartthings

serviceType

device.control

credential path

providerCredentials.smartthings.accessToken

resource service

smartthings:{connectionId}:resources → list-devices, get-device-state, subscribe-events

resource skill

smartthings-resource-access

control service

smartthings:{connectionId}:control → execute-command

control skill

smartthings-device-control

auth

x-agent-pairing-token (current signed pairing); x-api-key when platform auth is on

catalog (deployed)

lock → lock, unlock (single-use task); switch → on, off

token refresh

POST /api/v1/smartthings/oauth/refresh (stateless)

event stream

GET /api/v1/machines/{machineId}/smartthings/events

callback

POST /api/v1/smartthings/notifications — the SmartApp’s target URL, signed by SmartThings

server config

PEAQOS_SMARTTHINGS_ENABLED, PEAQOS_SMARTTHINGS_POLICY_FILE (server environment only; no Samsung credential)

payment

not-required — reads are direct, writes are free orders

availability

In development

FAQ

Questions agents ask about Samsung

• Does it require an API key?+

  Not a peaqOS one. The operator installs peaqOS’s catalog SmartApp in their SmartThings location, obtains its OAuth token pair outside peaqOS (see the SmartThings API docs), and sends the access token request-scoped as providerCredentials.smartthings.accessToken. peaqOS never stores, logs, or reuses it; a stateless refresh route rotates the pair the caller keeps. Each caller also sends its machine’s current signed pairing as x-agent-pairing-token, plus the platform x-api-key when that gate is on, and its delegation policy can allow device reads while denying commands.

• Can my robot use it today?+

  It is in development. Discovery, reads, subscriptions, and commands are implemented and have been exercised against a SmartApp with virtual devices; command confirmation on the deployed server is still being validated, and the adapter stays off until the deployment enables it. Its services are private: they appear only to a machine with a current signed pairing, never in public catalog listings.

• Which devices can a machine touch?+

  Only what the deployed capability catalog offers, within what the operator’s token reaches in the resolved location. Today that is the lock capability (lock, unlock) and the switch capability (on, off); devices with nothing in the catalog are left out of listings. Widening it is a catalog revision on the server, not a per-device grant, and no operator, machine, or device is configured on the server.

• How does payment work?+

  It does not. Reads run directly, and subscriptions and commands are free orders with no payment rail. peaqOS still records the order, execution, and audit receipt.

• When does a command count as done?+

  Never on acceptance alone. SmartThings accepting a command means it will try to deliver it; peaqOS reports accepted, rejected, unknown, or not-dispatched, and separately observes the postcondition you name — a lock reading unlocked, a switch reading on — for up to 120 seconds, from a status read or from the device’s own event. Unlock runs under a single-use task that its order creates, bound to that machine, device, and command, and expiring 15 minutes after the order. Retry with the original commandId and peaqOS returns the saved outcome; a new commandId is a new command and can duplicate a late action.

• How fresh is the data?+

  A read returns each attribute with the provider’s own observed time and a freshness flag — stale after 60 seconds, unknown without a usable time — and the device’s online health from a separate read. A subscription pushes attribute changes as SmartThings delivers them to peaqOS; peaqOS keeps an hour of events, up to 10,000 per owner, so a reconnecting stream can replay from its Last-Event-ID. A lease pauses after 300 seconds unless it is revalidated with a fresh token.

• What happens if a request fails?+

  Errors are mapped before they reach the agent: a token that belongs to no installation of the app returns 409, a device the token cannot see returns 403, an unreachable SmartThings returns 503 with no automatic retry for commands, and a missing or expired session is refused before SmartThings is contacted.