Class Device

A connected Qualithm device.

Example

const device = new Device({
  provisioningUrl: "https://api.qualithm.com",
  claimCode: process.env.QUALITHM_CLAIM_CODE
})
await device.connect()
await device.publish(
  "telemetry",
  JSON.stringify({ ts: Date.now(), metrics: { temperature: 21.4 } })
)

Index

Constructors

constructor

new Device(options: DeviceOptions): Device
Parameters
- options: DeviceOptions
Returns Device
- Defined in device.ts:163

Accessors

connectionState

get connectionState(): ConnectionState
The current connection state.

Returns ConnectionState
- Defined in device.ts:175

identity

get identity(): DeviceCredential | null
The active device credential once provisioned, otherwise null.

Returns DeviceCredential | null
- Defined in device.ts:180

Methods

connect

connect(): Promise<void>
Provision (claim once, or load the stored credential) and open the auto-reconnecting MQTT-over-TLS session. Resolves once connected.

Returns Promise<void>
- Defined in device.ts:287

declareCapabilities

declareCapabilities(declarations: CapabilityDeclaration[]): Promise<void>
Declare (or re-declare) the device's capability set. The manifest is validated locally, published on the current session, and re-published on every subsequent connect. Throws a CapabilityError on an invalid declaration.
Parameters
- declarations: CapabilityDeclaration[]
Returns Promise<void>
- Defined in device.ts:235

disconnect

disconnect(): Promise<void>
Gracefully close the session. The state becomes closed (terminal).

Returns Promise<void>
- Defined in device.ts:368

onCommand

onCommand<V>(key: string, handler: CommandHandler<V>): () => void
Register a handler for commands addressed to one capability key.

The SDK subscribes command/# once and dispatches by key, decoding the payload first: a settable capability's handler receives the decoded value; a trigger capability's handler is invoked with no value. A malformed payload or a throwing handler is reported through onError without interrupting dispatch. Returns an unregister function.
Type Parameters
- V
Parameters
- key: string
- handler: CommandHandler<V>
Returns () => void
- Defined in device.ts:211

onError

onError(listener: ErrorListener): () => void
Subscribe to transport errors. Returns an unsubscribe function.
Parameters
- listener: ErrorListener
Returns () => void
- Defined in device.ts:197

onMessage

onMessage(listener: MessageListener): () => void
Subscribe to inbound messages. Returns an unsubscribe function.
Parameters
- listener: MessageListener
Returns () => void
- Defined in device.ts:191

onState

onState(listener: StateListener): () => void
Subscribe to connection-state transitions. Returns an unsubscribe function.
Parameters
- listener: StateListener
Returns () => void
- Defined in device.ts:185

publish

publish(
    topic: string,
    payload: string | Uint8Array<ArrayBufferLike>,
    options?: IClientPublishOptions,
): Promise<void>
Publish a payload to a (device-relative) topic.

A QoS 1 publish carries a msg-id user property. When the gateway answers it with a failed PUBACK (reason code 0x80 or above), it is published again with the same msg-id, after a capped, jittered backoff, so the gateway stores it once.
Parameters
- topic: string
- payload: string | Uint8Array<ArrayBufferLike>
- Optionaloptions: IClientPublishOptions
Returns Promise<void>
Throws
PayloadTooLargeError when the payload exceeds the ceiling the gateway advertised in CONNACK (qualithm/pm#126) — caught before the bytes go on the wire, so the device is told rather than silently dropped.

Throws
the last failed PUBACK's error once every attempt has failed.
- Defined in device.ts:306

startProvisioning

startProvisioning(
options?: Omit<ProvisioningServerOptions, "provisioningUrl" | "store">,
): Promise<ProvisioningServer>
Start soft-AP provisioning mode: serve the claim exchange on the device's setup network until the companion app claims the device.

Only available before a gateway session exists — never alongside one. A successful claim persists the credential, stops the server and the setup access point, and invokes onProvisioned; connect() then proceeds with the stored credential. While the server is serving, the device's state is provisioning.
Parameters
- Optionaloptions: Omit<ProvisioningServerOptions, "provisioningUrl" | "store">
Returns Promise<ProvisioningServer>
Throws
ConnectionError when a gateway session is active or the device is closed.

Throws
ProvisioningError when the device is already provisioned or the server fails to start.
- Defined in device.ts:255

subscribe(
topic: string | string[],
options?: IClientSubscribeOptions,
): Promise<void>
Subscribe to one or more (device-relative) topic filters.
Parameters
- topic: string | string[]
- Optionaloptions: IClientSubscribeOptions
Returns Promise<void>
- Defined in device.ts:354

Class Device

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Device

Accessors

connectionState

Returns ConnectionState

identity

Returns DeviceCredential | null

Methods

connect

Returns Promise<void>

declareCapabilities

Parameters

Returns Promise<void>

disconnect

Returns Promise<void>

onCommand

Type Parameters

Parameters

Returns () => void

onError

Parameters

Returns () => void

onMessage

Parameters

Returns () => void

onState

Parameters

Returns () => void

publish

Parameters

Returns Promise<void>

Throws

Throws

startProvisioning

Parameters

Returns Promise<ProvisioningServer>

Throws

Throws

subscribe

Parameters

Returns Promise<void>

Settings

On This Page