index ↓
system
client.systemDevice identity, health, logs, and power control for a webapp. versionRequest and
diagnosticsGet return the daemon version and a health snapshot, logsTail returns a batch of
log entries, and logsSubscribe streams them as onLogEntry. onOtaProgress and
onOtaFinished track a software update.
requests
you ask, the daemon answers. await the tagged result and check .ok
versionRequest(): Promise<TypedRequestResult<BridgeThingMeta, never>>
push form: onVersion (subscribe instead of awaiting)
Returns the daemon's version and identity as BridgeThingMeta.
const res = await client.system.versionRequest();
if (res.ok) {
console.log(res.response.bridgethingVersion);
}type Result =
| { ok: true; response: BridgeThingMeta }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };diagnosticsGet(): Promise<TypedRequestResult<DiagnosticsReply, never>>
push form: onDiagnosticsReply (subscribe instead of awaiting)
Returns disk and memory use, uptime, SoC temperature, load average, and versions.
const res = await client.system.diagnosticsGet();
if (res.ok) {
console.log(res.response.diagnostics);
}type Result =
| { ok: true; response: DiagnosticsReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };logsTail(LogsTail): Promise<TypedRequestResult<LogsTailReply, never>>
push form: onLogsTailReply (subscribe instead of awaiting)
const res = await client.system.logsTail({ source: 'daemon', levels: 'trace', maxLines: 0 });
if (res.ok) {
console.log(res.response.entries);
}type Result =
| { ok: true; response: LogsTailReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };logsSubscribe(LogsSubscribe): Promise<TypedRequestResult<LogsSubscribeReply, never>>
push form: onLogsSubscribeReply (subscribe instead of awaiting)
const res = await client.system.logsSubscribe({ source: 'daemon', levels: 'trace' });
if (res.ok) {
console.log(res.response.token);
}type Result =
| { ok: true; response: LogsSubscribeReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };deviceGetNickname(): Promise<TypedRequestResult<DeviceNicknameReply, never>>
push form: onDeviceNickname (subscribe instead of awaiting)
const res = await client.system.deviceGetNickname();
if (res.ok) {
console.log(res.response.nickname);
}type Result =
| { ok: true; response: DeviceNicknameReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };factoryReset(): Promise<TypedRequestResult<FactoryResetStarted, FactoryResetRefused>>
push form: onFactoryResetStarted (subscribe instead of awaiting)
Arms a wipe of the data partition and restarts the device.
const res = await client.system.factoryReset();
if (res.ok) {
// res.response: FactoryResetStarted
} else {
console.warn(res.kind, res.error);
}type Result =
| { ok: true; response: FactoryResetStarted }
| { ok: false; kind: 'domain'; error: FactoryResetRefused }
| { ok: false; kind: 'protocol'; error: WireError };launcherGestureGet(): Promise<TypedRequestResult<LauncherGestureReply, never>>
push form: onLauncherGestureReply (subscribe instead of awaiting)
Returns the M-button gesture that jumps to the launcher.
const res = await client.system.launcherGestureGet();
if (res.ok) {
console.log(res.response.gesture);
}type Result =
| { ok: true; response: LauncherGestureReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };companionLaunchGet(): Promise<TypedRequestResult<CompanionLaunchReply, never>>
push form: onCompanionLaunchReply (subscribe instead of awaiting)
Returns whether the device opens the companion app when an iPhone reconnects without it running.
const res = await client.system.companionLaunchGet();
if (res.ok) {
console.log(res.response.enabled);
}type Result =
| { ok: true; response: CompanionLaunchReply }
| { ok: false; kind: 'domain'; error: never }
| { ok: false; kind: 'protocol'; error: WireError };commands
fire-and-forget. the promise resolves once the daemon has taken the message
logsUnsubscribe(LogsUnsubscribe): Promise<void>
await client.system.logsUnsubscribe({ token: '...' });reboot(): Promise<void>
await client.system.reboot();powerOff(): Promise<void>
await client.system.powerOff();launcherGestureSet(LauncherGestureSet): Promise<void>
await client.system.launcherGestureSet({ gesture: 'longPress' });companionLaunchSet(CompanionLaunchSet): Promise<void>
await client.system.companionLaunchSet({ enabled: true });events
the daemon pushes these unprompted. subscribing returns an unsubscribe function
onLogEntry(handler: (LogEntry) => void): () => void
const off = client.system.onLogEntry((entry) => {
console.log(entry.tsUnixS);
});
// call off() to unsubscribeonOtaProgress(handler: (OtaProgress) => void): () => void
const off = client.system.onOtaProgress((otaProgress) => {
console.log(otaProgress.phase);
});
// call off() to unsubscribeonOtaError(handler: (OtaError) => void): () => void
const off = client.system.onOtaError((otaError) => {
console.log(otaError.code);
});
// call off() to unsubscribeonOtaFinished(handler: (OtaFinished) => void): () => void
const off = client.system.onOtaFinished((otaFinished) => {
console.log(otaFinished.kind);
});
// call off() to unsubscribeonDeviceNicknameChanged(handler: (DeviceNicknameReply) => void): () => void
const off = client.system.onDeviceNicknameChanged((reply) => {
console.log(reply.nickname);
});
// call off() to unsubscribeonLauncherGestureChanged(handler: (LauncherGestureReply) => void): () => void
const off = client.system.onLauncherGestureChanged((reply) => {
console.log(reply.gesture);
});
// call off() to unsubscribeonCompanionLaunchChanged(handler: (CompanionLaunchReply) => void): () => void
const off = client.system.onCompanionLaunchChanged((reply) => {
console.log(reply.enabled);
});
// call off() to unsubscribetypes
shapes referenced above, as the sdk types them
type LogEntry = {
tsUnixS: number;
level: LogLevel;
target: string;
message: string;
};type OtaProgress = {
phase: OtaPhase;
percent: number; // 0 to 100, within the current phase.
step: number;
nsteps: number;
dwlPercent: number; // Mirrors `percent`.
dwlBytes: number; // Always 0.
etaMs?: number;
};type OtaError = {
code: OtaErrorCode;
msg: string;
updateId?: string; // A resume of the same artifact reuses the id.
replayed: boolean; // The device is redelivering a failure the phone missed.
};type OtaFinished = {
kind: OtaKind;
updateId: string;
};type DeviceNicknameReply = {
nickname?: string;
};type LauncherGestureReply = {
gesture: LauncherGesture;
};type CompanionLaunchReply = {
enabled: boolean;
};Identity and build information for the device.
type BridgeThingMeta = {
bridgethingVersion: string;
libbridgethingVersion: string;
appName: string;
nickname?: string;
bluetoothName?: string; // The adapter's bluetooth alias, the name phones see when pairing. Absent where the daemon has no radio.
launcherGesture: LauncherGesture;
companionLaunch: boolean; // Whether the device opens the companion app when an iPhone reconnects without it running.
display: DisplaySettings;
appVersion: string;
daemonSha256?: string;
wakewordModelVersion?: string; // Null when no wake word model is loaded, or the loaded model carries no version.
osName: string;
osVersion: string;
osDescription: string;
btMac: string;
serialNumber: string;
fccId: string;
icId: string;
modelName: string;
channel: string;
imageVariant: string;
imageVersion: string;
imageBuildId: string;
imageBuildDate: string;
imageDistro: string;
imageMachine: string;
discord: string;
credits: string;
};type DiagnosticsReply = {
diagnostics: Diagnostics;
};type LogsTail = {
source: LogSource;
levels: LogLevel[];
filter?: string;
maxLines: number;
};type LogsTailReply = {
entries: LogEntry[];
};type LogsSubscribe = {
source: LogSource;
levels: LogLevel[];
filter?: string;
verbosity?: LogLevel;
};type LogsSubscribeReply = {
token: string;
};type FactoryResetStarted = {};type FactoryResetRefused = {
refusal: FactoryResetRefusal;
reason: string;
};type LogsUnsubscribe = {
token: string;
};type LauncherGestureSet = {
gesture: LauncherGesture;
};type CompanionLaunchSet = {
enabled: boolean;
};type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';Each kind emits the phases that apply to it.
type OtaPhase =
| 'streaming'
| 'verifying'
| 'writing'
| 'confirming'
| 'reboot';type OtaErrorCode =
| 'unknownUpdate' // The update id does not match an update the device has begun.
| 'offsetMismatch' // A fragment arrived at an offset the device was not expecting.
| 'hashMismatch' // The transferred bytes do not match the declared sha256.
| 'sizeMismatch' // The transferred bytes do not match the declared size.
| 'cancelled'
| 'writeFailed' // The device rejected the payload while writing it.
| 'confirmFailed' // The update wrote successfully. The device could not mark the new slot bootable.
| 'internal' // An unexpected failure.;What an update installs.
type OtaKind =
| 'image'
| 'daemon'
| 'builtinWebapp'
| 'installedWebapp'
| 'wakewordModel';Which M-button gesture jumps to the launcher.
type LauncherGesture = 'longPress' | 'fivePress' | 'doublePress';The display settings a user chooses. Nothing the light sensor moves.
type DisplaySettings = {
mode: BrightnessMode;
level: number; // `0.0` to `1.0`. The backlight in `manual` mode.
dim: DimSettings;
};type Diagnostics = {
diskUsedBytes: number;
diskFreeBytes: number;
memUsedBytes: number;
memAvailBytes: number;
uptimeS: number;
socTempC?: number;
loadAvg: [f32 ; 3];
daemonVersion: string;
kernelVersion: string;
bootId: string;
};type LogSource = 'daemon' | 'system' | 'all';type FactoryResetRefusal =
| 'offDevice' // The daemon is not running on a Car Thing.
| 'noWipeStep' // The system image has no boot step that erases the device. Update the system image first.
| 'failed' // The reset failed before the restart, and nothing was erased.
| 'stillArmed' // The restart failed and the wipe could not be called off, so the next restart erases the device.;type BrightnessMode =
| 'auto' // The device sets the backlight from its ambient light sensor.
| 'manual' // `setLevel` sets the backlight.;When the screen dims. A connected computer can also ask for a dim with hostState.away.
type DimSettings = {
afterS?: number; // Seconds without input on the device or a connected computer, 15 to 86400. Null never dims.
level: number; // `0.0` (dark) to `1.0`. Caps a manual level and scales an auto level.
};