bitspire/docs/device-configuration.md

Device Configuration

This document describes how to configure the ATM hardware for different machine models.

Overview

bitSpire ships built-in presets for the hardware platforms we've tested on. Configuration is handled through:

1. Machine presets — built-in defaults for known hardware (Sintra, tejo, douro, batm3)
2. Environment variables — override any setting at runtime
3. Runtime overrides — programmatic configuration

Supported machine models

Sintra

The Sintra (Aaeon UP Board-based, Intel Atom x5-Z8350) uses:

Device	Protocol	Path	Underlying device
Bill Validator	ID003	/dev/ttyJ5	FTDI USB-serial → /dev/ttyUSB1
Bill Dispenser	F56	/dev/ttyJ7	SoC MMIO UART → /dev/ttyS4
Printer	Nippon	/dev/ttyJ4	FTDI USB-serial → /dev/ttyUSB0

Hardware:

• Platform: Aaeon UP Board (Intel Atom x5-Z8350)
• Validator: JCM iVIZION
• Dispenser: Fujitsu F53/F56

Sintra-specific gotcha: the kernel allocates ttyS0..ttyS3 as placeholder serial nodes that error on any I/O. Only ttyS0 (legacy 8250 at I/O 0x3f8) and ttyS4 (SoC MMIO 16550A at 0xa171b000) are real on this hardware. The bitspire-atm NixOS module's upboard.nix keeps the kernel console on tty0 only (not ttyS4) so userspace can claim ttyS4 for the F56 dispenser.

tejo

The Tejo runs on the same Aaeon UP Board family as Sintra; same validator + dispenser layout. Uses the same upboard.nix hardware module.

Douro

Runs on a Dell OptiPlex 9030 AIO (Intel i7-4790S, Intel HD 4600) — Lamassu's stock Douro motherboard. SATA SSD instead of eMMC, eGalax touchscreen, dispenser/validator on USB-attached FTDI bridges. See deploy/nixos/hardware/douro.nix for the specifics.

BATM3

The "batm3" target in this repo is not the stock GeneralBytes BATM3 — it's a custom modification where the original ARM/Android board has been physically replaced with a Dell OptiPlex 9030 AIO (same hardware family as the Douro). The chassis, cash-handling units (MEI SCR validator/recycler + Puloon F56 dispenser), and screen are stock BATM3; everything compute-side is grafted in. See deploy/nixos/hardware/batm3.nix for the boot configuration; functionally it shares the Dell-board layout with Douro but with different cash hardware on the inside.

Environment Variables

All configuration can be overridden via environment variables. For Vite/Electron, prefix with VITE_:

Variable	Description	Default
VITE_BITSPIRE_MACHINE_MODEL	Machine preset	sintra
VITE_BITSPIRE_FIAT_CODE	Fiat currency (ISO 4217)	USD
VITE_BITSPIRE_VALIDATOR_DEVICE	Validator serial device path	(from preset)
VITE_BITSPIRE_DISPENSER_DEVICE	Dispenser serial device path	(from preset)
VITE_BITSPIRE_CASSETTES	JSON array of cassettes	(from preset)

Example: Custom Cassette Configuration

# Two cassettes: $20 bills (100 count) and $50 bills (50 count)
export VITE_BITSPIRE_CASSETTES='[{"denomination":20,"count":100},{"denomination":50,"count":50}]'

Example: Custom Device Paths

export VITE_BITSPIRE_VALIDATOR_DEVICE="/dev/ttyUSB0"
export VITE_BITSPIRE_DISPENSER_DEVICE="/dev/ttyUSB1"

Cassette Configuration

Each cassette is defined with:

interface CassetteConfig {
  denomination: number // Bill denomination (e.g., 20 for $20)
  count?: number // Number of bills loaded (optional, for inventory tracking)
}

Default Sintra Configuration

[{ "denomination": 20, "count": 50 }]

This configures a single cassette with $20 bills, 50 bill capacity.

Multi-Cassette Example

[
  { "denomination": 20, "count": 100 },
  { "denomination": 50, "count": 50 },
  { "denomination": 100, "count": 25 }
]

Programmatic Configuration

You can also configure devices programmatically:

import { getDeviceConfig, toHalConfig } from '@/config'

// Use preset with custom fiat code
const config = getDeviceConfig('sintra', 'EUR')

// Or with overrides
const config = getDeviceConfig('sintra', 'USD', {
  dispenser: {
    type: 'f56',
    device: '/dev/ttyUSB1',
    cassettes: [
      { denomination: 20, count: 100 },
      { denomination: 50, count: 50 },
    ],
  },
})

// Convert to HAL config format
const halConfig = toHalConfig(config)

Initialization

For Production (Recommended)

The simplest way to initialize with hardware:

import { useAtmStore } from '@/stores/atm'

const atm = useAtmStore()

// Uses environment variables with Sintra defaults
await atm.initializeForProduction()

With Custom Config

import { useAtmStore } from '@/stores/atm'
import { getDeviceConfig, toHalConfig } from '@/config'

const atm = useAtmStore()

const config = getDeviceConfig('sintra', 'USD', {
  dispenser: {
    type: 'f56',
    device: '/dev/ttyJ7',
    cassettes: [{ denomination: 20, count: 100 }],
  },
})

await atm.initializeWithHal(toHalConfig(config))

Verifying Device Paths

On a Sintra running Linux, verify the serial devices exist:

ls -la /dev/ttyJ*

Expected output on a working Sintra:

lrwxrwxrwx 1 root root 7 May 13 09:22 /dev/ttyJ4 -> ttyUSB0
lrwxrwxrwx 1 root root 7 May 13 09:22 /dev/ttyJ5 -> ttyUSB1
lrwxrwxrwx 1 root root 5 May 13 09:22 /dev/ttyJ7 -> ttyS4

(ttyUSB0/ttyUSB1 are the two FTDI USB-serial bridges — printer + validator. ttyS4 is the SoC's on-carrier MMIO UART used for the F56 dispenser.)

If the symlinks don't exist, check the udev rules in deploy/nixos/hardware/upboard.nix, then run mdev -s (or udevadm trigger on a non-Alpine system) to repopulate /dev.

If you see a symlink pointing at ttyS1/ttyS2/ttyS3 instead, those are kernel-allocated placeholder nodes that always error on I/O — the udev rule needs to map to ttyS4 for Sintra. The current upboard.nix covers all the cases (ttyS1, ttyS4, ttyS5) so whichever real device shows up gets the ttyJ7 alias.

Troubleshooting

Permission Denied on Serial Port

Add your user to the dialout group:

sudo usermod -a -G dialout $USER
# Log out and back in for changes to take effect

Device Not Found

1. Check the device exists: ls -la /dev/ttyJ* or ls -la /dev/ttyS*
2. Check dmesg for hardware detection: dmesg | grep tty
3. Verify udev rules are loaded: udevadm info /dev/ttyS5

Validator Not Responding

1. Verify baud rate: ID003 uses 9600 baud, 8 data bits, even parity, 1 stop bit
2. Check cable connections
3. Power cycle the validator
4. Check validator is in "online" mode (not standalone)

Dispenser Not Dispensing

1. Verify cassette is properly seated
2. Check for bill jams
3. Verify dispenser firmware is compatible with F56 protocol
4. Check the dispenser is powered and initialized