yoto-nodejs-client 0.0.2 → 0.0.3

package/lib/mqtt/client.js

@@ -20,8 +20,8 @@
  * @typedef {Object} YotoEventsMessage
  * @property {boolean} [repeatAll] - Repeat all tracks
  * @property {boolean} [streaming] - Whether streaming
- * @property {number} [volume] - Current volume level
- * @property {number} [volumeMax] - Maximum volume level
+ * @property {number} [volume] - Current user volume level (0-16 scale, maps to userVolumePercentage in status)
+ * @property {number} [volumeMax] - Maximum volume limit (0-16 scale, maps to systemVolumePercentage in status)
  * @property {boolean} [playbackWait] - Playback waiting
  * @property {boolean} [sleepTimerActive] - Sleep timer active
  * @property {number} [eventUtc] - Unix timestamp
@@ -34,37 +34,52 @@
  * @property {string} [chapterKey] - Current chapter key
  * @property {string} [trackTitle] - Current track title
  * @property {string} [trackKey] - Current track key
- * @property {string} [playbackStatus] - Playback status (e.g., "playing", "paused", "stopped")
+ * @property {'playing' | 'paused' | 'stopped' | 'loading' | string} [playbackStatus] - Playback status
  * @property {number} [sleepTimerSeconds] - Seconds remaining on sleep timer
  */
 
 /**
- * Status message from device
+ * Status message from device (MQTT /data/status)
+ *
+ * Device automatically publishes status updates every 5 minutes (matching keepalive interval).
+ * Can also be requested on-demand via requestStatus().
+ *
+ * Note: MQTT types differ from HTTP - uses booleans, non-nullable fields
  * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceiddatastatus
  * @typedef {Object} YotoStatusMessage
+ * @property {YotoMqttStatus} status - Status object
+ */
+
+/**
+ * MQTT status payload structure (documented spec)
+ *
+ * Automatic updates (every 5 minutes): 21 fields (excludes nightlightMode and temp)
+ * Requested status: All 23 fields including nightlightMode and temp
+ *
+ * @typedef {Object} YotoMqttStatus
  * @property {number} statusVersion - Status message version
  * @property {string} fwVersion - Firmware version
  * @property {string} productType - Product type identifier
  * @property {number} batteryLevel - Battery level percentage
  * @property {number} als - Ambient light sensor reading
- * @property {number} freeDisk - Free disk space
+ * @property {number} freeDisk - Free disk space in bytes
  * @property {number} shutdownTimeout - Shutdown timeout in seconds
  * @property {number} dbatTimeout - DBAT timeout
  * @property {number} charging - Charging state (0 or 1)
- * @property {string} activeCard - Active card ID
- * @property {number} cardInserted - Card insertion state
+ * @property {string} activeCard - Active card ID or 'none'
+ * @property {0 | 1 | 2} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
  * @property {number} playingStatus - Playing status code
  * @property {boolean} headphones - Headphones connected
  * @property {number} dnowBrightness - Current display brightness
  * @property {number} dayBright - Day brightness setting
  * @property {number} nightBright - Night brightness setting
  * @property {boolean} bluetoothHp - Bluetooth headphones enabled
- * @property {number} volume - Current volume
- * @property {number} userVolume - User volume setting
+ * @property {number} volume - System/max volume level (0-100 percentage, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number} userVolume - User volume setting (0-100 percentage, represents 0-16 hardware scale, maps to volume in events)
  * @property {'12' | '24'} timeFormat - Time format preference
- * @property {string} nightlightMode - Nightlight mode setting
- * @property {string} temp - Temperature reading
- * @property {number} day - Day mode (0 or 1)
+ * @property {string} [nightlightMode] - Current nightlight color (actual hex color like '0xff5733' or 'off') - only in requested status, most accurate source
+ * @property {string} [temp] - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status
+ * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
  */
 
 /**
@@ -85,14 +100,136 @@
 
  */
 
+/**
+ * Legacy status message from device (MQTT /status)
+ *
+ * This is the older undocumented status topic that contains critical lifecycle information
+ * not available in the documented /data/status topic, including:
+ * - shutDown field: Indicates device power state changes ('userShutdown', 'nA', etc.)
+ * - Startup detection: Low upTime values, utcTime: 0 after power on
+ * - Full hardware diagnostics: battery voltage, memory stats, temperatures
+ *
+ * Both documented and legacy status topics are necessary for complete device monitoring.
+ *
+ * @typedef {Object} YotoStatusLegacyMessage
+ * @property {YotoLegacyStatus} status - Legacy status object with full hardware details
+ */
+
+/**
+ * Legacy MQTT status payload structure (undocumented)
+ *
+ * Contains all fields from documented status plus additional lifecycle and diagnostic fields.
+ *
+ * @typedef {Object} YotoLegacyStatus
+ * @property {number} statusVersion - Status message version
+ * @property {string} fwVersion - Firmware version
+ * @property {string} shutDown - Power state: 'nA' = device running, any other value = shutting down/shut down (e.g., 'userShutdown') - ONLY in legacy topic
+ * @property {number} totalDisk - Total disk space in bytes
+ * @property {string} productType - Product type identifier
+ * @property {number} wifiStrength - WiFi signal strength in dBm
+ * @property {string} ssid - WiFi SSID
+ * @property {number} rtcResetReasonPRO - RTC reset reason (PRO)
+ * @property {number} rtcResetReasonAPP - RTC reset reason (APP)
+ * @property {number} rtcWakeupCause - RTC wakeup cause code
+ * @property {number} espResetReason - ESP reset reason code
+ * @property {string} sd_info - SD card information string
+ * @property {number} battery - Raw battery voltage in millivolts
+ * @property {string} powerCaps - Power capabilities
+ * @property {number} batteryLevel - Battery level percentage
+ * @property {number} batteryTemp - Battery temperature
+ * @property {string} batteryData - Battery data string (format: 'val1:val2:val3')
+ * @property {number} batteryLevelRaw - Raw battery level reading
+ * @property {number} free - Free memory in bytes
+ * @property {number} freeDMA - Free DMA memory in bytes
+ * @property {number} free32 - Free 32-bit memory in bytes
+ * @property {number} upTime - Device uptime in seconds (low values indicate recent startup)
+ * @property {number} utcTime - UTC timestamp (0 indicates fresh startup before time sync)
+ * @property {number} aliveTime - Total alive time in seconds
+ * @property {number} accelTemp - Accelerometer temperature in Celsius
+ * @property {string} batteryProfile - Battery profile identifier
+ * @property {number} freeDisk - Free disk space in bytes
+ * @property {number} failReason - Failure reason code
+ * @property {number} failData - Failure data
+ * @property {number} shutdownTimeout - Shutdown timeout in seconds
+ * @property {number} utcOffset - UTC offset in seconds
+ * @property {string} nfcErrs - NFC error rates (format: 'xx.xx%-xx.xx%')
+ * @property {number} dbatTimeout - DBAT timeout in seconds
+ * @property {number} charging - Charging state (0 or 1)
+ * @property {0 | 1 | 2 | 3} powerSrc - Power source (0=battery, 1=V2 dock, 2=USB-C, 3=Qi)
+ * @property {string} activeCard - Active card ID or 'none'
+ * @property {0 | 1 | 2} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
+ * @property {number} playingStatus - Playing status code
+ * @property {number} headphones - Headphones connected (0 or 1)
+ * @property {number} wifiRestarts - WiFi restart count
+ * @property {number} qiOtp - Qi OTP value
+ * @property {number} buzzErrors - Buzzer error count
+ * @property {number} dnowBrightness - Current display brightness
+ * @property {number} dayBright - Day brightness setting
+ * @property {number} nightBright - Night brightness setting
+ * @property {number} errorsLogged - Number of errors logged
+ * @property {number} twdt - Task watchdog timer value
+ * @property {number} bluetoothHp - Bluetooth headphones state (0 or 1)
+ * @property {string} nightlightMode - Current nightlight color (hex color like '0xff5733' or 'off')
+ * @property {number} bgDownload - Background download state
+ * @property {number} bytesPS - Bytes per second
+ * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
+ * @property {string} temp - Temperature readings (format: 'val1:val2:val3')
+ * @property {number} als - Ambient light sensor reading
+ * @property {number} volume - System/max volume level (0-100 percentage, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number} userVolume - User volume setting (0-100 percentage, represents 0-16 hardware scale, maps to volume in events)
+ * @property {'12' | '24'} timeFormat - Time format preference
+ * @property {number} chgStatLevel - Charge state level
+ * @property {number} missedLogs - Missed log count
+ * @property {number} nfcLock - NFC lock state
+ * @property {number} batteryFullPct - Battery full percentage threshold
+ */
+
 /**
  * MQTT connection state
  * @typedef {'disconnected' | 'connected' | 'reconnecting'} YotoMqttConnectionState
  */
 
+/**
+ * Events message callback
+ * @callback EventsCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoEventsMessage} payload - Events message payload
+ */
+
+/**
+ * Status message callback
+ * @callback StatusCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoStatusMessage} payload - Status message payload
+ */
+
+/**
+ * Legacy status message callback
+ * @callback StatusLegacyCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoStatusLegacyMessage} payload - Legacy status message payload with lifecycle events
+ */
+
+/**
+ * Response message callback
+ * @callback ResponseCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoResponseMessage} payload - Response message payload
+ */
+
+/**
+ * Unknown message callback
+ * @callback UnknownCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {any} payload - Unknown message payload
+ */
+
 import { EventEmitter } from 'events'
 import {
   getSubscriptionTopics,
+  getEventsTopic,
+  getStatusTopic,
+  getResponseTopic,
   parseTopic,
   getEventsRequestTopic,
   getStatusRequestTopic,
@@ -118,9 +255,14 @@ import { commands } from './commands.js'
  * Yoto MQTT Client class
  * @extends EventEmitter
  *
- * @fires YotoMqttClient#events
- * @fires YotoMqttClient#status
- * @fires YotoMqttClient#response
+ * Device automatically publishes status updates every 5 minutes when connected.
+ * Status can also be requested on-demand via requestStatus() and requestEvents().
+ *
+ * @fires YotoMqttClient#events - Emits (topic, payload) when device sends events
+ * @fires YotoMqttClient#status - Emits (topic, payload) when device sends status (automatic every 5 min, or on-demand)
+ * @fires YotoMqttClient#status-legacy - Emits (topic, payload) when device sends legacy status with lifecycle events
+ * @fires YotoMqttClient#response - Emits (topic, payload) when device responds to commands
+ * @fires YotoMqttClient#unknown - Emits (topic, payload) when receiving unknown message type
  * @fires YotoMqttClient#connected
  * @fires YotoMqttClient#disconnected
  * @fires YotoMqttClient#reconnecting
@@ -209,14 +351,43 @@ export class YotoMqttClient extends EventEmitter {
 
   /**
    * Subscribe to device topics
+   * @param {Array<'events' | 'status' | 'response'> | 'all'} [types='all'] - Topic types to subscribe to, or 'all' for all topics
    * @returns {Promise<void>}
+   * @example
+   * // Subscribe to all topics (default)
+   * await client.subscribe()
+   * await client.subscribe('all')
+   *
+   * // Subscribe to specific topics
+   * await client.subscribe(['events', 'status'])
+   * await client.subscribe(['response'])
    */
-  async #subscribe () {
-    const topics = getSubscriptionTopics(this.deviceId)
+  async subscribe (types = 'all') {
+    let topicsToSubscribe = []
+
+    if (types === 'all') {
+      // Subscribe to all device topics
+      topicsToSubscribe = getSubscriptionTopics(this.deviceId)
+    } else {
+      // Subscribe to specific topic types
+      const typeArray = Array.isArray(types) ? types : [types]
+
+      for (const type of typeArray) {
+        if (type === 'events') {
+          topicsToSubscribe.push(...getEventsTopic(this.deviceId))
+        } else if (type === 'status') {
+          topicsToSubscribe.push(...getStatusTopic(this.deviceId))
+        } else if (type === 'response') {
+          topicsToSubscribe.push(getResponseTopic(this.deviceId))
+        } else {
+          throw new Error(`Invalid topic type: ${type}. Must be 'events', 'status', 'response', or 'all'`)
+        }
+      }
+    }
 
     // Wait for all subscriptions to complete
     await Promise.all(
-      topics.map((topic) => {
+      topicsToSubscribe.map((topic) => {
         return new Promise((resolve, reject) => {
           this.mqttClient.subscribe(topic, (err) => {
             if (err) {
@@ -232,6 +403,14 @@ export class YotoMqttClient extends EventEmitter {
     )
   }
 
+  /**
+   * Subscribe to device topics (internal - used by autoSubscribe)
+   * @returns {Promise<void>}
+   */
+  async #subscribe () {
+    return this.subscribe('all')
+  }
+
   /**
    * Handle incoming MQTT message
    * @param {string} topic - MQTT topic
@@ -245,21 +424,22 @@ export class YotoMqttClient extends EventEmitter {
       return
     }
 
-    // Ignore unknown message types
-    if (messageType === 'unknown') {
-      return
-    }
-
     try {
       const payload = JSON.parse(message.toString())
 
-      // Emit typed events based on message type
+      // Emit typed events based on message type, including raw topic
       if (messageType === 'events') {
-        this.emit('events', /** @type {YotoEventsMessage} */ (payload))
+        this.emit('events', topic, /** @type {YotoEventsMessage} */ (payload))
       } else if (messageType === 'status') {
-        this.emit('status', /** @type {YotoStatusMessage} */ (payload))
+        this.emit('status', topic, /** @type {YotoStatusMessage} */ (payload))
+      } else if (messageType === 'status-legacy') {
+        // Legacy status topic contains lifecycle events (shutdown, startup) and full hardware diagnostics
+        // The documented /data/status topic does not include these critical lifecycle fields
+        this.emit('status-legacy', topic, /** @type {YotoStatusLegacyMessage} */ (payload))
       } else if (messageType === 'response') {
-        this.emit('response', /** @type {YotoResponseMessage} */ (payload))
+        this.emit('response', topic, /** @type {YotoResponseMessage} */ (payload))
+      } else if (messageType === 'unknown') {
+        this.emit('unknown', topic, payload)
       }
     } catch (err) {
       const error = /** @type {Error} */ (err)
@@ -346,20 +526,22 @@ export class YotoMqttClient extends EventEmitter {
 
   /**
    * Request current events from device
+   * @param {string} [body=''] - Optional request body for tracking/identification
    * @returns {Promise<void>}
    */
-  async requestEvents () {
+  async requestEvents (body = '') {
     const topic = getEventsRequestTopic(this.deviceId)
-    return this.#publish(topic, '')
+    return this.#publish(topic, body)
   }
 
   /**
    * Request current status from device
+   * @param {string} [body=''] - Optional request body for tracking/identification
    * @returns {Promise<void>}
    */
-  async requestStatus () {
+  async requestStatus (body = '') {
     const topic = getStatusRequestTopic(this.deviceId)
-    return this.#publish(topic, '')
+    return this.#publish(topic, body)
   }
 
   /**

package/lib/mqtt/factory.d.ts

@@ -19,8 +19,25 @@
  *
  * await client.connect()
  * ```
+ *
+ * @example
+ * ```javascript
+ * // Disable automatic reconnection
+ * const client = createYotoMqttClient({
+ *   deviceId: 'abc123',
+ *   accessToken: 'token',
+ *   mqttOptions: {
+ *     reconnectPeriod: 0,     // Disable auto-reconnect (default is 5000ms)
+ *     connectTimeout: 30000   // 30 second connection timeout
+ *   }
+ * })
+ * ```
  */
 export function createYotoMqttClient(options: YotoMqttOptions): YotoMqttClient;
+/**
+ * MQTT.js client options that can be passed to createYotoMqttClient
+ */
+export type MqttClientOptions = Partial<mqtt.IClientOptions>;
 export type YotoMqttOptions = {
     /**
      * - Device ID to connect to
@@ -38,10 +55,6 @@ export type YotoMqttOptions = {
      * - MQTT broker URL
      */
     brokerUrl?: string;
-    /**
-     * - Keepalive interval in seconds
-     */
-    keepalive?: number;
     /**
      * - MQTT broker port
      */
@@ -50,6 +63,11 @@ export type YotoMqttOptions = {
      * - Auto-subscribe to device topics on connect
      */
     autoSubscribe?: boolean;
+    /**
+     * - Additional MQTT.js client options (defaults: reconnectPeriod=5000, keepalive=300; cannot override: clientId, username, password, protocol, ALPNProtocols)
+     */
+    mqttOptions?: MqttClientOptions;
 };
 import { YotoMqttClient } from './client.js';
+import mqtt from 'mqtt';
 //# sourceMappingURL=factory.d.ts.map

package/lib/mqtt/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CApBW,eAAe,GACb,cAAc,CAkE1B;;;;;cAzFa,MAAM;;;;iBACN,MAAM;;;;qBACN,MAAM;;;;gBACN,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;oBACN,OAAO;;+BAIU,aAAa"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8CAjCW,eAAe,GACb,cAAc,CAmF1B;;;;gCA/GY,OAAO,CAAC,mBAAc,CAAC;;;;;cAKtB,MAAM;;;;iBACN,MAAM;;;;qBACN,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;oBACN,OAAO;;;;kBACP,iBAAiB;;+BAIA,aAAa;iBAD3B,MAAM"}

package/lib/mqtt/factory.js

@@ -13,15 +13,20 @@
 // MQTT Factory: Create properly configured MQTT clients for Yoto devices
 // ============================================================================
 
+/**
+ * MQTT.js client options that can be passed to createYotoMqttClient
+ * @typedef {Partial<IClientOptions>} MqttClientOptions
+ */
+
 /**
  * @typedef {Object} YotoMqttOptions
  * @property {string} deviceId - Device ID to connect to
  * @property {string} accessToken - JWT access token for authentication
  * @property {string} [clientIdPrefix='DASH'] - Prefix for MQTT client ID (default: 'DASH')
  * @property {string} [brokerUrl='wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com'] - MQTT broker URL
- * @property {number} [keepalive=300] - Keepalive interval in seconds
  * @property {number} [port=443] - MQTT broker port
  * @property {boolean} [autoSubscribe=true] - Auto-subscribe to device topics on connect
+ * @property {MqttClientOptions} [mqttOptions] - Additional MQTT.js client options (defaults: reconnectPeriod=5000, keepalive=300; cannot override: clientId, username, password, protocol, ALPNProtocols)
  */
 
 import mqtt from 'mqtt'
@@ -56,6 +61,19 @@ import {
  *
  * await client.connect()
  * ```
+ *
+ * @example
+ * ```javascript
+ * // Disable automatic reconnection
+ * const client = createYotoMqttClient({
+ *   deviceId: 'abc123',
+ *   accessToken: 'token',
+ *   mqttOptions: {
+ *     reconnectPeriod: 0,     // Disable auto-reconnect (default is 5000ms)
+ *     connectTimeout: 30000   // 30 second connection timeout
+ *   }
+ * })
+ * ```
  */
 export function createYotoMqttClient (options) {
   // Validate required options
@@ -73,9 +91,9 @@ export function createYotoMqttClient (options) {
     accessToken,
     clientIdPrefix = 'DASH',
     brokerUrl = MQTT_BROKER_URL,
-    keepalive = MQTT_KEEPALIVE,
     port = MQTT_PORT,
-    autoSubscribe = true
+    autoSubscribe = true,
+    mqttOptions: additionalMqttOptions = {}
   } = options
 
   // Build MQTT client ID
@@ -85,15 +103,19 @@ export function createYotoMqttClient (options) {
   const username = `${deviceId}?x-amz-customauthorizer-name=${MQTT_AUTH_NAME}`
 
   // Create MQTT connection options
+  // Merge additional options first, then override with required Yoto settings
   /** @type {IClientOptions} */
   const mqttOptions = {
+    // Defaults (can be overridden by additionalMqttOptions)
+    reconnectPeriod: 5000, // Default: auto-reconnect after 5 seconds
+    keepalive: MQTT_KEEPALIVE, // Default: 300 seconds (5 minutes)
+    ...additionalMqttOptions, // Allow overriding defaults
+    // Required Yoto-specific settings (cannot be overridden)
     clientId,
     username,
     password: accessToken,
-    keepalive,
     port,
     protocol: MQTT_PROTOCOL,
-    reconnectPeriod: 0, // Disable auto-reconnect, handle manually
     ALPNProtocols: MQTT_ALPN_PROTOCOLS
   }
 

package/lib/mqtt/mqtt.test.js

@@ -1,13 +1,13 @@
 import test from 'node:test'
 import assert from 'node:assert'
 import { getDevices } from '../api-endpoints/devices.js'
-import { loadTestTokens, logResponse } from '../api-endpoints/test-helpers.js'
+import { loadTestTokens, logResponse } from '../api-endpoints/endpoint-test-helpers.js'
 import { createYotoMqttClient } from './index.js'
 
 const { accessToken } = loadTestTokens()
 
 test('MQTT client', async (t) => {
-  await t.test('should connect, request status/events, and receive response and events messages', async () => {
+  await t.test('should connect, request status/events, and receive response and events messages (status-legacy is optional)', async () => {
     // Get an online device
     const response = await getDevices({ accessToken })
     assert.ok(response.devices.length > 0, 'Should have at least one device')
@@ -28,23 +28,26 @@ test('MQTT client', async (t) => {
     let eventsResponseReceived = false
     let eventsMessageReceived = false
     let statusMessageReceived = false
+    let statusLegacyMessageReceived = false
     /** @type {Error[]} */
     const errors = []
 
     // Setup message handlers
-    mqttClient.on('events', (message) => {
-      logResponse('MQTT events message', message)
+    mqttClient.on('events', (topic, payload) => {
+      logResponse('MQTT events message', { topic, payload })
 
       try {
         // Validate events message structure
-        assert.ok(message, 'Events message should exist')
+        assert.ok(payload, 'Events message should exist')
+        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.ok(topic.includes('/data/events'), 'Topic should contain /data/events')
 
         // Events messages are partial - not all fields are always present
-        if (message.playbackStatus !== undefined) {
-          assert.ok(typeof message.playbackStatus === 'string', 'playbackStatus should be string')
+        if (payload.playbackStatus !== undefined) {
+          assert.ok(typeof payload.playbackStatus === 'string', 'playbackStatus should be string')
         }
-        if (message.cardId !== undefined) {
-          assert.ok(typeof message.cardId === 'string', 'cardId should be string')
+        if (payload.cardId !== undefined) {
+          assert.ok(typeof payload.cardId === 'string', 'cardId should be string')
         }
 
         eventsMessageReceived = true
@@ -53,18 +56,20 @@ test('MQTT client', async (t) => {
       }
     })
 
-    mqttClient.on('status', (message) => {
-      logResponse('MQTT status message', message)
+    mqttClient.on('status', (topic, payload) => {
+      logResponse('MQTT status message', { topic, payload })
 
       try {
         // Validate status message structure
-        assert.ok(message, 'Status message should exist')
-        assert.ok(message.status, 'Status message should have status object')
-        assert.ok(typeof message.status.statusVersion === 'number', 'Should have statusVersion number')
-        assert.ok(typeof message.status.fwVersion === 'string', 'Should have fwVersion string')
-        assert.ok(typeof message.status.productType === 'string', 'Should have productType string')
-        assert.ok(typeof message.status.batteryLevel === 'number', 'Should have batteryLevel number')
-        assert.ok(typeof message.status.volume === 'number', 'Should have volume number')
+        assert.ok(payload, 'Status message should exist')
+        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.ok(topic.includes('/data/status'), 'Topic should contain /data/status')
+        assert.ok(payload.status, 'Status message should have status object')
+        assert.ok(typeof payload.status.statusVersion === 'number', 'Should have statusVersion number')
+        assert.ok(typeof payload.status.fwVersion === 'string', 'Should have fwVersion string')
+        assert.ok(typeof payload.status.productType === 'string', 'Should have productType string')
+        assert.ok(typeof payload.status.batteryLevel === 'number', 'Should have batteryLevel number')
+        assert.ok(typeof payload.status.volume === 'number', 'Should have volume number')
 
         statusMessageReceived = true
       } catch (err) {
@@ -72,28 +77,71 @@ test('MQTT client', async (t) => {
       }
     })
 
-    mqttClient.on('response', (message) => {
-      logResponse('MQTT response message', message)
+    mqttClient.on('status-legacy', (topic, payload) => {
+      logResponse('MQTT status-legacy message', { topic, payload })
+
+      try {
+        // Validate legacy status message structure
+        assert.ok(payload, 'Legacy status message should exist')
+        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.ok(!topic.includes('/data/'), 'Legacy topic should NOT contain /data/')
+        assert.ok(payload.status, 'Legacy status message should have status object')
+
+        // Validate lifecycle fields unique to legacy format
+        assert.ok(typeof payload.status.statusVersion === 'number', 'Should have statusVersion number')
+        assert.ok(typeof payload.status.fwVersion === 'string', 'Should have fwVersion string')
+
+        // shutDown field is the key field for lifecycle events
+        if (payload.status.shutDown !== undefined) {
+          assert.ok(typeof payload.status.shutDown === 'string', 'shutDown should be string')
+        }
+
+        // upTime and utcTime are key for startup detection
+        if (payload.status.upTime !== undefined) {
+          assert.ok(typeof payload.status.upTime === 'number', 'upTime should be number')
+        }
+        if (payload.status.utcTime !== undefined) {
+          assert.ok(typeof payload.status.utcTime === 'number', 'utcTime should be number')
+        }
+
+        // Hardware diagnostic fields unique to legacy
+        if (payload.status.battery !== undefined) {
+          assert.ok(typeof payload.status.battery === 'number', 'battery should be number')
+        }
+        if (payload.status.wifiStrength !== undefined) {
+          assert.ok(typeof payload.status.wifiStrength === 'number', 'wifiStrength should be number')
+        }
+
+        statusLegacyMessageReceived = true
+      } catch (err) {
+        errors.push(/** @type {Error} */ (err))
+      }
+    })
+
+    mqttClient.on('response', (topic, payload) => {
+      logResponse('MQTT response message', { topic, payload })
 
       try {
         // Validate response message structure
-        assert.ok(message, 'Response message should exist')
-        assert.ok(message.status, 'Response should have status object')
-        assert.ok(typeof message.status.req_body === 'string', 'Response should have req_body string')
+        assert.ok(payload, 'Response message should exist')
+        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.ok(topic.includes('/response'), 'Topic should contain /response')
+        assert.ok(payload.status, 'Response should have status object')
+        assert.ok(typeof payload.status.req_body === 'string', 'Response should have req_body string')
 
         // Check if status request was acknowledged (field name is 'status/request')
-        if (message.status['status/request']) {
+        if (payload.status['status/request']) {
           assert.ok(
-            message.status['status/request'] === 'OK' || message.status['status/request'] === 'FAIL',
+            payload.status['status/request'] === 'OK' || payload.status['status/request'] === 'FAIL',
             'Status request field should be OK or FAIL'
           )
           statusResponseReceived = true
         }
 
         // Check if events request was acknowledged
-        if (message.status.events) {
+        if (payload.status.events) {
           assert.ok(
-            message.status.events === 'OK' || message.status.events === 'FAIL',
+            payload.status.events === 'OK' || payload.status.events === 'FAIL',
             'Events request field should be OK or FAIL'
           )
           eventsResponseReceived = true
@@ -125,7 +173,7 @@ test('MQTT client', async (t) => {
       // Wait for messages (with timeout)
       await new Promise((resolve, reject) => {
         timeoutId = setTimeout(() => {
-          reject(new Error(`Timeout waiting for messages. statusResponse=${statusResponseReceived}, eventsResponse=${eventsResponseReceived}, eventsMessage=${eventsMessageReceived}, statusMessage=${statusMessageReceived}`))
+          reject(new Error(`Timeout waiting for messages. statusResponse=${statusResponseReceived}, eventsResponse=${eventsResponseReceived}, eventsMessage=${eventsMessageReceived}, statusMessage=${statusMessageReceived}, statusLegacy=${statusLegacyMessageReceived} (optional)`))
         }, 5000) // 5 second timeout
 
         checkIntervalId = setInterval(() => {
@@ -134,6 +182,8 @@ test('MQTT client', async (t) => {
             clearInterval(checkIntervalId)
             reject(errors[0])
           }
+          // Note: status-legacy is NOT required - it doesn't respond to requestStatus()
+          // It only emits on real-time lifecycle events (shutdown/startup) or 5-minute periodic updates
           if (statusResponseReceived && eventsResponseReceived && eventsMessageReceived && statusMessageReceived) {
             clearTimeout(timeoutId)
             clearInterval(checkIntervalId)
@@ -147,6 +197,13 @@ test('MQTT client', async (t) => {
       assert.ok(eventsResponseReceived, 'Should have received events request response')
       assert.ok(eventsMessageReceived, 'Should have received events data message')
       assert.ok(statusMessageReceived, 'Should have received status data message')
+
+      // Note: status-legacy message is optional in this test because it does NOT respond to requestStatus()
+      // It only emits on real-time lifecycle events (shutdown/startup) or 5-minute periodic updates
+      // If we happened to catch one during the test window, validate it was received correctly
+      if (statusLegacyMessageReceived) {
+        console.log('✓ Received optional status-legacy message with lifecycle events')
+      }
     } catch (err) {
       // Clean up timers on error
       if (timeoutId) clearTimeout(timeoutId)