@xshore/telemetry-client

TypeScript client for the X-Shore Thingsboard PE telemetry API at telemetry.xshore.com.

Install

npm install @xshore/telemetry-client

Quick start

import { ThingsboardClient, TelemetryKeys, BASE_URL } from '@xshore/telemetry-client';

// Authenticate with an API key (create one in Thingsboard → Account Settings → Security)
const client = new ThingsboardClient(BASE_URL, {
  apiKey: process.env.XSHORE_API_KEY,
});

// Or log in with username and password
await client.login('[email protected]', 'password');

// Scoped telemetry — no need to repeat 'DEVICE' on every call
const tel = client.telemetry.forDevice(deviceId);

const latest = await tel.getLatest([
  TelemetryKeys.HVBAT_SOC,
  TelemetryKeys.GPS_LATITUDE,
  TelemetryKeys.GPS_LONGITUDE,
  TelemetryKeys.VCU_STATE,
]);

const history = await tel.getHistory({
  keys: [TelemetryKeys.HVBAT_SOC],
  startTs: Date.now() - 24 * 60 * 60 * 1000,
  endTs: Date.now(),
  agg: 'AVG',
  interval: 60 * 60 * 1000,
});

Features

• Auth — API key, username/password JWT, token persistence and restore
• Devices — list, paginate, listAll() async generator
• Telemetry — latest snapshot, historical time-series with aggregation, attributes
• Realtime — WebSocket subscriptions with auto-reconnect
• Alarms — list, acknowledge, clear
• RPC — one-way and two-way device commands
• Constants — verified TelemetryKeys, VcuStates, resolveVcuState()

Realtime subscriptions

const rt = client.createRealtimeClient();

const unsubscribe = rt.subscribeDevice(deviceId, [TelemetryKeys.MOTOR_RPM], (update) => {
  const rpm = update.data[TelemetryKeys.MOTOR_RPM]?.[0]?.value;
  console.log('RPM:', rpm);
});

// Later:
unsubscribe();
rt.disconnect();

Node.js < 22: pass a WebSocket constructor via new ThingsboardClient(url, { WebSocket: WS.WebSocket }) using the ws package.

VCU state

Thingsboard stores the ECU state as a raw C enum integer. Use resolveVcuState() to decode it:

import { resolveVcuState, VcuStates } from '@xshore/telemetry-client';

const state = resolveVcuState(raw); // '27' → 'E_ECUSTATE_DRIVE'

if (state === VcuStates.DRIVE)   console.log('Underway');
if (state === VcuStates.CHARGE)  console.log('Charging');
if (state === VcuStates.SLEEP)   console.log('Docked');

Error handling

import { ThingsboardError } from '@xshore/telemetry-client';

try {
  await client.devices.listInfos();
} catch (err) {
  if (err instanceof ThingsboardError) {
    console.error(err.status, err.message); // 401, 403, 404, …
  }
}

Requirements

• Node.js 18+ (uses global fetch)
• Node.js 22+ for realtime WebSocket support without the ws package