Port OS Smart Home

Control devices/services and retrieve results or camera snapshots. Target exactly one id (endpoint/group) or field-first query as in endpoint_query. Queries freeze all authorized matches across every page in one request; zero or over 100 fails before delivery. Report any narrowing or splitting of requested whole-house coverage. For all lights off, discover all pages, select physical lights/known lamp switches and deduplicate provider representations. Use {"idempotencyKey":"<action key>","query":{"id":{"in":["<full light ID>","<full lamp-switch ID>"]}},"message":"port1/systems/zero/capability-interfaces/power/messages/[email protected]","payload":{},"waitForResult":true}. Use type-only filters only if inventory proves their physical scope; query adds no provider/SELF/simulator exclusions. A separate turn-on action needs a new key. Check all outcomes and fresh state before claiming whole-house success. Copy full logical target IDs/messages from endpoint_query or group_query, preserving the account and declared payload ({} if fieldless). Clarify ambiguous scope. Port OS selects compatible provider routes and native or equivalent member delivery for the complete target. Native capabilities/membershipComplete do not prove aggregate coverage. Provider ambiguity is a target-resolution error; resolve the intended device, group or media item before another control. waitForResult=true waits for validated correlated replies or provider acknowledgment for response-less commands. QUEUED/IN_PROGRESS remain pending even with empty lists. Snapshots return pixels/timeOfSample; events need not reply. Verify physical state with endpoint_query/group_query, declared expand and forceDeviceAttributeQuery=true. Live music queue recipe: "set up a playlist and play it on my Sonos" means an active queue, not a saved library playlist unless requested. 1. Discover the Spotify library and target speaker/native group. Search via declared media-search/search-media with {"query":"<artist or mood>"

Manage the names, types and registry entries of your devices and connected services. Send the complete name, type and enablement document for every metadata replacement, with etag from the read and a stable idempotencyKey. Choose one operation: RENAME, SET_TYPE, SET_ENABLEMENT, MERGE_INTO, or DELETE. Use endpoint_query first and copy the full endpoint ID. Rename and type changes are durable across provider rediscovery. Disabled endpoints stay available for explicit metadata reads, but cannot receive messages; rediscovery preserves the disabled state. DELETE removes the registry entry, though a provider may rediscover it later. MERGE_INTO retains the source endpoint as disabled and moves supported references to the target; it does not create a source-ID alias, a simulator endpoint can merge only into a target without a simulator route (two simulator endpoints return 409 CONFLICT; disable or delete the duplicate instead), and the target's enablement remains in effect. Before MERGE_INTO or DELETE, identify the actual endpoint and explain the effect to the user; never assume two endpoints are duplicates because their names match. This tool changes registry metadata only and never performs physical control.

Find connected devices and services, discover their controls, and read their state. Start with a focused name, room or category query; follow paginationContext.nextToken. Results include full IDs, device types, provider routes, capabilities and accepted message IDs. An endpoint is a device or connected service, including a filesystem or media library. Copy IDs verbatim into control. For a known device, use endpointId; inspect its declared capabilities, commands and outbound message IDs. Use group_query for rooms and endpoint_manage for requested inventory cleanup. To read state, set expand to the declared capabilities you need, for example ["power","connectivity"] or ["battery"]. expand adds observations; it does not discover more devices or send controls. Add forceDeviceAttributeQuery=true to refresh selected attributes from the provider; otherwise readings may come from cache. Only FRESH observations establish the current state. A FRESH value is the current state; a STALE value is the last known state, reported with its sampledAt and never as live or unknown (a forced read may refresh it). Errored, missing or invalid values are unknown, not OFF or a dead battery, and a STALE value alone must not support a safety claim such as locked or off. An attribute with error.code PROVIDER_NO_STATE (forced reads only) means the provider answered but has no value for it: state is unknown and retrying will not help until the provider reports one. FRESH UNREACHABLE means offline even if a power value is present; STALE UNREACHABLE is the last known connectivity. An ID-only lookup retrieves metadata without requesting fresh state. Supported discovery includes: - Lights, switches and plugs: select by name and power/brightness capabilities as well as type; a light may be typed SWITCH or PLUG. - Thermostats and sensors: read temperature-sensor for ambient temperature; a setpoint is not room temperature. Clarify indoor versus outdoor temperature when ambiguous. - Cameras, locks, a

Show Port OS devices with their supported controls. To show a device, always call this tool: the widget it opens is the device's UI, so never render a second card, map or controls for it; answer in a sentence or two. Uses the same selection, expansion and pagination arguments as endpoint_query. A single matching device opens its full view with now playing, transport, volume and other controls; several matches open only a list of names to choose from, so pass one full endpoint ID (or a query matching one device) to control a device. Showing a device does not start live video or send a control command. Pass primary to choose which card leads, one of the device's card ids (every result lists them as cardIds; an unknown id is rejected with the available ones). The device's usual card and every other card stay behind the details toggle. Examples: "what's the battery on the vacuum" -> primary battery; "turn the thermostat fan on" -> primary fan; "how open are the blinds" -> primary closure; "show me the camera on the roborock" -> primary camera. "where is my phone" or "show its location" -> primary location; "show the roborock's map" or "pick a room to clean" -> primary house-map. Every result already includes the cached readings of the cards it lists (cardIds), so you can answer without a second call; pass expand to choose different capabilities. primary refreshes that card's readings from the device, so the answer is current. Always state the value in words: a FRESH reading is current; a STALE reading is the last known value, so say it is last known and give its age.

Organize rooms and device groups: create, rename, change members, enable, disable, merge or delete them. Create, delete, add/remove members, MOVE_MEMBER and rename default to providerSync BEST_EFFORT: send supported native group changes first, verify provider readback, then save Port OS intent. A provider failure falls back locally and is PARTIALLY_APPLIED. PORTOS_ONLY sends nothing; FAIL_ON_PROVIDER_ERROR fails customer intent if a required provider change fails, while retaining received provider facts. Native effects cannot be rolled back. Undeclared support is NOT_SUPPORTED with reason NOT_DECLARED and does not by itself make the result partial. OUTSIDE_PRINCIPAL means native changes are not attempted through another principal's account; the authorized Port OS change can still apply. Read group IDs and etags with group_query first. Every reference to one group in a batch uses the same starting etag. MOVE_MEMBER takes memberEndpointId plus source and target group references with both etags; a lone add cannot implicitly displace another exclusive native group. Contradictory edits return 400; list position is not a procedural ordering mechanism. MERGE_INTO and aggregate/route enablement accept only PORTOS_ONLY. Rename does not automatically merge groups. DELETE_GROUP can delete provider groups. Routes not confirmed retired are disabled and orphaned, so rediscovery cannot resurrect the deleted group. SET_ENABLEMENT can hide an aggregate without deleting it; SET_GROUP_ROUTE_ENABLEMENT changes one provider route's contribution locally; its etag is the native route version and groupEtag is also required when the route belongs to a group. Obtain explicit user authorization for the exact MERGE_INTO or DELETE_GROUP targets and effects before calling. Hue supports native group creation, deletion, membership and rename. Roborock supports room rename only; membership changes do not reshape robot maps. Sonos native group mutations are not implemented. Declared support is a

Find rooms, floors, zones, homes and device groups, with their members and supported controls. Returns canonical IDs, names, etags, spatial roles, parent paths, children, members, controllers and providers. Start without arguments and follow every paginationContext.nextToken; filter large accounts with query. Controllers list endpoints and messages accepting this group: room cleaning targets the controller with payload {"groupIds":[<group ID>]}, not the group itself. Messages target the logical group ID through control. Port OS selects compatible native or equivalent member delivery for the complete effective membership, including scenes/media. Native interfaces and membershipComplete do not establish aggregate coverage. Disabled routes cannot control. For ambiguous names ask which parentPath the user means. Read one group with id; merged IDs resolve to the survivor with redirectedFrom. Show room maps with endpoint_show on the vacuum controller, primary house-map; never draw spatial geometry yourself. Expand uses capability names as in endpoint_query; forceDeviceAttributeQuery refreshes observations. Omitted or failed fresh route attributes are unavailable. membershipComplete is provider-declared: false means incomplete/unreported, absent means unknown. members lists resolved endpoints; empty does not prove a native group empty. Disabled groups are hidden unless enablement is DISABLED or * and cannot be targeted; re-enable with group_manage SET_ENABLEMENT. Copy IDs and etags verbatim.

Stop watching by cancelling one Port OS event subscription using its exact ID from subscription_list or subscription_inspect. Cancellation is idempotent. Select the intended subscription by name, source endpoint and catalog event; names are not cancellation keys. A stopped monitor requires a new subscription to watch again.

Inspect one Port OS event subscription by its exact ID returned by subscription_list. Returns its safe query, source endpoint, catalog name and lifecycle status. A retained active subscription establishes registration; it does not prove that any client has received or acted on a camera event.

Change only the display name of one Port OS event subscription by exact ID. Use a PLAIN name-value object. The event, endpoint, filter and destination are immutable; to change what is watched, establish a replacement monitor and cancel the old ID.

Enumerate the user's Port OS event subscriptions, including their exact IDs, names, source endpoint, catalog event and status. For requests to stop watching a camera, list subscriptions and follow every nextCursor, select the intended monitor, then use subscription_cancel with its exact ID. Creating a monitor uses the host's events/subscribe capability after discovering supported camera events; these tools never accept callback URLs or signing keys.