Merge pull request 'fix(batm3): get cash-in working — EBDS escrow latch + correct serial device paths' (#79) from fix/ebds-escrow-stack-latch into dev

Reviewed-on: #79

apps/machine/electron/hal-service.ts

@@ -221,6 +221,15 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
     },
 
     disableValidator: () => {
+      // If a note is sitting in escrow when we disable (inactivity timeout,
+      // cancel, or leaving the insert screen), return it to the customer.
+      // Disabling alone does NOT release an escrowed note on EBDS — it would
+      // be stranded in the transport until the next power cycle.
+      if (escrowDenomination !== null) {
+        console.log('[HAL] Returning escrowed bill on disable:', escrowDenomination)
+        escrowDenomination = null
+        validator?.reject()
+      }
       validator?.disable()
       validator?.lightOff()
     },

apps/machine/src/config/device.ts

@@ -139,11 +139,21 @@ export const MACHINE_PRESETS: Record<MachineModel, Omit<DeviceConfig, 'fiatCode'
     model: 'batm3',
     validator: {
       type: 'ebds',
-      device: '/dev/ttyACM0',
+      // MEI bill acceptor (EBDS) on a USB-serial bridge, exposed via the
+      // stable udev symlink /dev/ttyMEI (batm3.nix, serial A9YW78OC). The old
+      // /dev/ttyACM0 default assumed a CDC-ACM BNR; this hardware enumerates as
+      // ttyUSB* instead, so ACM0 never existed and cash-in was silently
+      // disabled ("[HAL] No validator"). Per-box override: VITE_LAMASSU_VALIDATOR_DEVICE.
+      device: '/dev/ttyMEI',
     },
     dispenser: {
       type: 'f56',
-      device: '/dev/ttyUSB0',
+      // Fujitsu F56 on a USB-serial bridge, via the stable udev symlink
+      // /dev/ttyF56 (batm3.nix, serial DDDLb103Y23). Avoids the raw
+      // /dev/ttyUSB0, which is enumeration-order dependent and could point at
+      // the wrong adapter after a re-plug/reboot. Per-box override:
+      // VITE_LAMASSU_DISPENSER_DEVICE.
+      device: '/dev/ttyF56',
       cassettes: [
         { denomination: 20, count: 400 },
         { denomination: 1, count: 400 },

apps/machine/src/stores/atm.ts

@@ -458,7 +458,7 @@ export const useAtmStore = defineStore('atm', () => {
     actor.value.subscribe((newSnapshot: SnapshotFrom<ATMMachine>) => {
       const prevSnapshot = snapshot.value
       snapshot.value = newSnapshot
-      console.log('[ATM] State:', newSnapshot.value)
+      console.log('[ATM] State:', JSON.stringify(newSnapshot.value))
 
       // Detect transition into a complete state
       const state = newSnapshot.value
@@ -1374,7 +1374,7 @@ export const useAtmStore = defineStore('atm', () => {
       console.error('[ATM] Cannot send event: machine not initialized')
       return
     }
-    console.log('[ATM] Sending event:', event)
+    console.log('[ATM] Sending event:', event.type, JSON.stringify(event))
     actor.value.send(event)
   }
 

packages/hal/src/validators/ebds/ebds-rs232.ts

@@ -313,6 +313,13 @@ export class EbdsRs232 extends EventEmitter {
   private serial: SerialPort | null = null
   private ack: number = 0x0
   private enabledDenominations: number = 0x00
+  // Latched escrow decision. In EBDS the stack/return choice is NOT a one-shot
+  // message — it's carried as bits in the omnibus poll command, and the device
+  // holds the escrowed note until a poll asserts stack or return. We keep the
+  // action set and re-assert it on every poll until the device leaves escrow
+  // (cleared in _process), so a single dropped/collided frame no longer strands
+  // the note in escrow forever.
+  private pendingAction: 'none' | 'stack' | 'return' = 'none'
   private lastStatusFlags: string | null = null
   private firmwareLogged: boolean = false
 
@@ -405,23 +412,38 @@ export class EbdsRs232 extends EventEmitter {
 
   // -- Commands (Appendix D, Controller Message) ---------------------------
 
-  /** Send an Omnibus poll command with current denomination mask */
+  /**
+   * Command byte 1 for the omnibus poll, encoding any latched escrow action.
+   * `stack` (0x3f) and `return` (0x5f) differ from the plain poll (0x1b) only
+   * in the stack/return bits; while an action is latched every poll re-asserts
+   * it until the device acts.
+   */
+  private commandByte(): number {
+    if (this.pendingAction === 'stack') return 0x3f
+    if (this.pendingAction === 'return') return 0x5f
+    return 0x1b
+  }
+
+  /** Send an Omnibus poll command with the current mask + latched action */
   poll(): void {
-    this._dispatch([this.enabledDenominations, 0x1b, 0x10])
+    this._dispatch([this.enabledDenominations, this.commandByte(), 0x10])
   }
 
-  /** Stack the bill currently in escrow */
+  /** Latch "stack the escrowed note"; re-asserted each poll until it takes. */
   stack(): void {
-    this._dispatch([this.enabledDenominations, 0x3f, 0x10])
+    this.pendingAction = 'stack'
+    this.poll()
   }
 
-  /** Reject/return the bill currently in escrow */
+  /** Latch "return the escrowed note"; re-asserted each poll until it takes. */
   reject(): void {
-    this._dispatch([this.enabledDenominations, 0x5f, 0x10])
+    this.pendingAction = 'return'
+    this.poll()
   }
 
   /** Send initial setup command (disable all, reset state) */
   reset(): void {
+    this.pendingAction = 'none'
     this._dispatch([0x00, 0x1b, 0x10])
   }
 
@@ -470,7 +492,13 @@ export class EbdsRs232 extends EventEmitter {
       validatePacket(packet)
       const result = interpret(packet)
       if (result) {
-        if (result.destructedData) this._logStatusOnChange(result.destructedData)
+        if (result.destructedData) {
+          // Clear a latched stack/return once the device has left escrow — it
+          // is now stacking/returning/idle, so we must stop asserting the
+          // action or it would leak onto the next note.
+          if (!result.destructedData[0].escrowed) this.pendingAction = 'none'
+          this._logStatusOnChange(result.destructedData)
+        }
         this.emit('message', result)
       }
     } catch (ex) {