Physical controls

Manage paired controls, shared quick lists, personal profiles and assistive outputs.

Source 0.1.0 Private source package

How the calls fit together

Read a selected paired device and its personal profiles. Keep firmware pairing and device-token protocols in their protected owner.

JavaScript examples

Supply your configured client. Each call awaits a decoded result; errors pass to your caller. These identifiers and values are fictional. Use selected development records and review every change before running it. Opening this page sends no API requests.

See the complete TypeScript workflow · Explore the Node starter

controlSurfaces.list

Lists control surfaces owned by an account.

const result = await client.controlSurfaces.list(
  "account 1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account whose control surfaces should be listed.

Returns Promise<RailDeckControlSurfaceListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.get

Loads one control surface.

const result = await client.controlSurfaces.get(
  "account 1",
  "control-surface-1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface to load.

Returns Promise<RailDeckControlSurface>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.update

Updates one control surface.

const result = await client.controlSurfaces.update(
  "account 1",
  "control-surface-1",
  {
    "buttonLayout": "four",
    "showLocomotiveImages": false
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface to update.
input · required: UpdateRailDeckControlSurfaceInput
Partial control-surface update.

Returns Promise<RailDeckControlSurface>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.revoke

Revokes one control surface.

const result = await client.controlSurfaces.revoke(
  "account 1",
  "control-surface-1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface to revoke.

Returns Promise<RailDeckControlSurface>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.listQuickList

Lists shared quick-list entries for one control surface.

const result = await client.controlSurfaces.listQuickList(
  "account 1",
  "control-surface-1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface whose quick list should be loaded.

Returns Promise<RailDeckControlSurfaceQuickListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.replaceQuickList

Replaces shared quick-list entries for one control surface.

const result = await client.controlSurfaces.replaceQuickList(
  "account 1",
  "control-surface-1",
  {
    "items": [
      {
        "itemKind": "route",
        "targetId": "route-1",
        "displayName": "{{fixtureDisplayName}}",
        "position": 1
      }
    ]
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface whose quick list should be replaced.
input · required: ReplaceRailDeckControlSurfaceQuickListInput
Ordered quick-list entries.

Returns Promise<RailDeckControlSurfaceQuickListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.listProfiles

Lists personal profiles for one control surface and signed-in operator.

const result = await client.controlSurfaces.listProfiles(
  "account 1",
  "control-surface-1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface whose profiles should be listed.

Returns Promise<RailDeckControlSurfaceProfileListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.createProfile

Creates a personal profile for one control surface and signed-in operator.

const result = await client.controlSurfaces.createProfile(
  "account 1",
  "control-surface-1",
  {
    "displayName": "{{fixtureDisplayName}}",
    "isDefault": true,
    "showLocomotiveImages": true,
    "buttonLayout": "three"
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface receiving the profile.
input · required: CreateRailDeckControlSurfaceProfileInput
Personal display, button, image, and metadata preferences.

Returns Promise<RailDeckControlSurfaceProfileDetail>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.getProfile

Loads one personal control-surface profile.

const result = await client.controlSurfaces.getProfile(
  "account 1",
  "control-surface-1",
  "profile-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface containing the profile.
controlSurfaceProfileId · required: RailDeckIdentifier
Profile to load.

Returns Promise<RailDeckControlSurfaceProfileDetail>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.updateProfile

Updates one personal control-surface profile.

const result = await client.controlSurfaces.updateProfile(
  "account 1",
  "control-surface-1",
  "profile-2",
  {
    "buttonLayout": "four"
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface containing the profile.
controlSurfaceProfileId · required: RailDeckIdentifier
Profile to update.
input · required: UpdateRailDeckControlSurfaceProfileInput
Partial personal profile update.

Returns Promise<RailDeckControlSurfaceProfileDetail>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.deleteProfile

Deletes one personal control-surface profile.

const result = await client.controlSurfaces.deleteProfile(
  "account 1",
  "control-surface-1",
  "profile-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface containing the profile.
controlSurfaceProfileId · required: RailDeckIdentifier
Profile to delete.

Returns Promise<RailDeckControlSurfaceProfileDetail>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.listProfileQuickList

Lists personal favourites for one control-surface profile.

const result = await client.controlSurfaces.listProfileQuickList(
  "account 1",
  "control-surface-1",
  "profile-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface containing the profile.
controlSurfaceProfileId · required: RailDeckIdentifier
Profile whose favourites should be loaded.

Returns Promise<RailDeckControlSurfaceProfileQuickListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.replaceProfileQuickList

Replaces personal favourites for one control-surface profile.

const result = await client.controlSurfaces.replaceProfileQuickList(
  "account 1",
  "control-surface-1",
  "profile-2",
  {
    "items": [
      {
        "itemKind": "accessory",
        "targetId": "accessory-1",
        "position": 1
      }
    ]
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface containing the profile.
controlSurfaceProfileId · required: RailDeckIdentifier
Profile whose favourites should be replaced.
input · required: ReplaceRailDeckControlSurfaceQuickListInput
Ordered personal quick-list entries.

Returns Promise<RailDeckControlSurfaceProfileQuickListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.listAssistiveOutputs

Lists assistive output profiles for one control surface.

const result = await client.controlSurfaces.listAssistiveOutputs(
  "account 1",
  "control-surface-1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface whose assistive outputs should be loaded.

Returns Promise<RailDeckControlSurfaceAssistiveOutputListResponse>.

Example evidence: Retained SDK transport fixture.

controlSurfaces.replaceAssistiveOutputs

Replaces assistive output profiles for one control surface.

const result = await client.controlSurfaces.replaceAssistiveOutputs(
  "account 1",
  "control-surface-1",
  {
    "outputs": [
      {
        "outputKind": "haptic",
        "displayName": "{{fixtureDisplayName}}",
        "eventKinds": [
          "command_result"
        ]
      }
    ]
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the control surface.
controlSurfaceId · required: RailDeckIdentifier
Control surface whose assistive outputs should be replaced.
input · required: ReplaceRailDeckControlSurfaceAssistiveOutputsInput
Assistive output profiles for speech, audio, haptic, visual, or captions.

Returns Promise<RailDeckControlSurfaceAssistiveOutputListResponse>.

Example evidence: Retained SDK transport fixture.

Download all TypeScript method examples

JavaScript calls and TypeScript downloads are checked through the real SDK using local response fixtures. This verifies the calls and decoding for those fixtures.

Handle errors and uncertain outcomes

Choose another feature

The complete TypeScript workflow

Follow how the calls fit together, including the review and recovery steps. Supply your configured client and explicitly selected development records. Importing the download performs no requests; mutations are never retried automatically.

import type { RailDeckDirectIntegrationClient as Client } from '@raildeck/frontend-sdk/direct-integration';

/**
 * Read a paired control with its profiles and shared quick list.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param deviceId - Explicitly selected paired device.
 * @returns Management data; firmware pairing and token exchange remain outside this workflow.
 */
export async function openPairedControl(
  client: Client,
  accountId: string,
  deviceId: string,
) {
  const device = await client.controlSurfaces.get(accountId, deviceId);
  const profiles = await client.controlSurfaces.listProfiles(accountId, deviceId);
  const quickList = await client.controlSurfaces.listQuickList(accountId, deviceId);
  return { device, profiles, quickList };
}

Download TypeScript example

How the calls fit together

JavaScript examples

The complete TypeScript workflow

Related information