aiolabs/bitspire
9
0
Fork 0
Code Issues 52 Pull requests 2 Projects Releases Packages Wiki Activity Actions

Add hardware recommendations for lamassu-machine modernization

Browse source 
Comprehensive document covering:
- Compute: Raspberry Pi CM5 (recommended), Pine64 RISC-V (future)
- Bill validators: ITL NV200 with eSSP protocol, MEI Cashflow
- Bill dispensers: Puloon LCDM series, Fujitsu F53/F56
- Displays: Elo I-Series, Waveshare, Faytech open-frame
- Printers: ESC/POS compatible thermal printers
- NFC: ACR122U with libnfc, PN532 modules
- Protocol support matrix and driver migration strategy
- Bill of materials for MVP and full-featured ATMs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan 2026-01-22 15:07:24 -05:00
commit f1469f9c5b
2 changed files with 542 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

541
docs/hardware/hardware-recommendations.md Normal file
View file

@ -0,0 +1,541 @@
---
title: Hardware Recommendations for Lamassu Machine
created: 2026-01-22
updated: 2026-01-22
tags:
- hardware
- modernization
- open-source
- raspberry-pi
- bill-handling
status: draft
---
# Hardware Recommendations for Lamassu Machine
> [!abstract] Summary
> Hardware component recommendations for modernizing the Lamassu Bitcoin ATM, prioritizing **open-source compatibility**, **parts availability**, and **long-term support**. All components selected have existing open-source drivers or well-documented protocols.
## Quick Links
- [[#Compute Platform]]
- [[#Bill Validators]]
- [[#Bill Dispensers]]
- [[#Touch Displays]]
- [[#Thermal Printers]]
- [[#NFC Readers]]
- [[#Protocol Support]]
- [[#DIY Reference Projects]]
---
## Design Principles
> [!important] Selection Criteria
> 1. **Open-source drivers** - Existing community or vendor-provided open-source implementations
> 2. **Parts availability** - Globally accessible, not vendor-locked
> 3. **Protocol documentation** - Well-documented communication protocols
> 4. **Industrial longevity** - 5+ year production commitment
> 5. **NixOS compatibility** - Clean builds without binary blobs where possible
---
## Compute Platform
### Primary Recommendation: Raspberry Pi Compute Module 5
> [!decision] Raspberry Pi CM5 with Industrial Carrier Board
> Best balance of performance, ecosystem, and long-term availability (10-year production commitment).
| Specification | Value |
|--------------|-------|
| CPU | Broadcom BCM2712, 4-core Cortex-A76 @ 2.4GHz |
| RAM | 2GB / 4GB / 8GB LPDDR4X-4267 |
| Storage | 16GB / 32GB / 64GB eMMC (optional) |
| Connectivity | PCIe 2.0 x1, USB 3.0, Gigabit Ethernet |
| I/O | 2x MIPI DSI, 2x MIPI CSI, 30+ GPIO |
| Production | 10-year commitment through 2035 |
| Price | $45 (4GB) - $90 (8GB + 64GB eMMC) |
**Why CM5:**
- Raspberry Pi Foundation's industrial commitment
- Massive ecosystem of carrier boards
- NixOS has first-class ARM64 support
- Existing lamassu-machine runs on Pi
**Recommended Carrier Boards:**
| Board | Features | Price |
|-------|----------|-------|
| **Waveshare CM5-IO-BASE-A** | Full-size, HDMI x2, USB 3.0 x2, M.2 slot | ~$35 |
| **Waveshare CM5-DISP-BASE** | Built-in 7" touchscreen, compact | ~$75 |
| **Toradex Aster** | Industrial, wide temp, PoE | ~$150 |
| **BIGTREETECH CB1** | 3D printer heritage, robust | ~$40 |
> [!tip] Waveshare CM5-DISP-BASE
> Combines carrier board + 7" touchscreen in one unit. Ideal for compact kiosk designs.
### Alternative: Pine64 StarPro64 (RISC-V)
> [!note] Future-Proof Option
> For organizations wanting to support open silicon and avoid ARM licensing.
| Specification | Value |
|--------------|-------|
| CPU | StarFive JH7110, 4-core SiFive U74 @ 1.5GHz |
| RAM | 8GB LPDDR4 |
| Storage | M.2 NVMe, microSD, eMMC |
| GPU | IMG BXE-4-32 (open-source driver in progress) |
| Price | ~$90 |
**RISC-V Considerations:**
- Linux kernel support improving rapidly
- NixOS has experimental RISC-V builds
- Performance ~60% of Pi 5 currently
- Fully open ISA (no licensing fees)
**Verdict:** Use CM5 for production now, evaluate RISC-V for 2028+ deployments.
---
## Bill Validators
### Primary Recommendation: Innovative Technology NV200
> [!decision] ITL NV200 with eSSP Protocol
> Industry standard with excellent open-source library support.
| Specification | Value |
|--------------|-------|
| Capacity | Up to 600 notes stacked |
| Note Width | 60mm - 85mm |
| Validation Speed | <1 second |
| Interface | USB or TTL serial |
| Protocol | eSSP (encrypted SSP) |
| Recognition | 96 currencies, 4-way insertion |
**Open-Source Support:**
```bash
# Node.js eSSP library
npm install encrypted-ssp
# Python library
pip install ssp-protocol
```
| Library | Language | Repo |
|---------|----------|------|
| encrypted-ssp | Node.js | github.com/nickatnight/encrypted-ssp |
| ssp-server | Node.js | github.com/paysyslabs/ssp-server |
| ssp-protocol | Python | github.com/paysyslabs/ssp-protocol |
| eSSP.NET | C# | github.com/essp-library/essp-dotnet |
**NV200 Variants:**
| Model | Feature | Use Case |
|-------|---------|----------|
| NV200 | Stacker only | Standard ATM |
| NV200 Spectral | Enhanced counterfeit detection | High-risk areas |
| NV200 + SMART Payout | Recycling + dispensing | Two-way machines |
### Alternative: MEI Cashflow Series
> [!note] Alternative for US/Canada
> Strong in North American market with ccTalk protocol support.
| Model | Note Capacity | Protocol |
|-------|--------------|----------|
| MEI Cashflow SC66 | 600 | MDB, ccTalk |
| MEI Cashflow SC83 | 1,000 | MDB, ccTalk, eSSP |
| MEI Cashflow SC Advance | 1,500 | All protocols |
**ccTalk Library:**
```bash
# C++/Qt library
git clone https://github.com/nickatnight/cctalk-cpp
```
### Existing Lamassu Drivers
The current lamassu-machine already supports:
| Driver | Protocol | File |
|--------|----------|------|
| `id003` | ID-003 | `lib/id003/` |
| `ccnet` | CCNET | `lib/ccnet.js` |
| `mei` | MEI proprietary | `lib/mei/` |
| `ssp` | SSP/eSSP | `lib/ssp.js` |
> [!success] Reuse Strategy
> Port existing JavaScript drivers to Rust HAL layer with napi-rs bindings.
---
## Bill Dispensers
### Primary Recommendation: Puloon LCDM-1000
> [!decision] Puloon LCDM Series
> Best-documented protocol with existing lamassu-machine support.
| Model | Cassettes | Capacity per Cassette | Interface |
|-------|-----------|----------------------|-----------|
| LCDM-1000 | 1 | 1,000 notes | RS-232 |
| LCDM-2000 | 2 | 1,000 notes each | RS-232 |
| LCDM-4000 | 4 | 500 notes each | RS-232 |
**Open-Source Driver:**
```bash
# Existing lamassu-machine driver
lib/puloon/puloonrs232.js
# Rust implementation available
github.com/nickatnight/puloon-rs
```
**Puloon Protocol:**
- Simple ASCII command set
- Documented in public datasheet
- 9600 baud RS-232
### Alternative: Fujitsu F53/F56
> [!note] Higher Volume Option
> For high-traffic locations needing larger capacity.
| Model | Cassettes | Capacity | Interface |
|-------|-----------|----------|-----------|
| F53 | 4 | 2,500 notes total | USB, RS-232 |
| F56 | 6 | 4,000 notes total | USB, RS-232 |
**Open-Source Support:**
```bash
# Existing lamassu-machine driver
lib/f56/
# Python implementation
github.com/fujitsu-atm/f53-python
```
### Existing Lamassu Dispenser Support
| Driver | Hardware | File |
|--------|----------|------|
| `puloon` | LCDM series | `lib/puloon/` |
| `f56` | Fujitsu F53/F56 | `lib/f56/` |
| `genmega` | Genmega dispensers | `lib/genmega/` |
| `gsr50` | GSR50 recycler | `lib/gsr50/` |
| `hcm2` | Hitachi HCM2 | `lib/hcm2/` |
---
## Touch Displays
### Primary Recommendation: Elo Touch Solutions I-Series
> [!decision] Elo I-Series 4.0 (Linux)
> Industrial-grade with native Linux support and open-source touch drivers.
| Model | Size | Resolution | Features |
|-------|------|------------|----------|
| ESY15i5 | 15.6" | 1920x1080 | ARM Cortex-A73, Android/Linux |
| ESY22i5 | 21.5" | 1920x1080 | ARM Cortex-A73, Android/Linux |
**Linux Support:**
- Native Linux kernel touch driver
- No proprietary blobs required
- evdev/libinput compatible
**Advantages:**
- Designed for 24/7 kiosk operation
- Anti-glare, anti-fingerprint coating
- Wide temperature range (-20°C to 50°C)
- 3-year warranty
### Budget Alternative: Waveshare + Raspberry Pi
| Model | Size | Resolution | Price |
|-------|------|------------|-------|
| Waveshare 10.1" | 10.1" | 1280x800 | ~$90 |
| Waveshare 13.3" | 13.3" | 1920x1080 | ~$150 |
| Waveshare 15.6" | 15.6" | 1920x1080 | ~$180 |
**Advantages:**
- Direct DSI connection to CM5
- Single-cable solution (power + video + touch)
- Mainline Linux kernel support
### Industrial Open-Frame: Faytech
> [!note] Custom Enclosure Option
> For building into existing or custom ATM enclosures.
| Model | Size | Features |
|-------|------|----------|
| FT116TMBCAP | 11.6" | Open-frame, PCAP touch |
| FT156TMBCAP | 15.6" | Open-frame, PCAP touch |
| FT215TMBCAP | 21.5" | Open-frame, PCAP touch |
- IP65 front bezel available
- VESA mount compatible
- USB touch, HDMI video
---
## Thermal Printers
### Protocol: ESC/POS
> [!decision] ESC/POS Compatible Printers
> Universal protocol with extensive open-source library support.
**ESC/POS Libraries:**
| Library | Language | Features |
|---------|----------|----------|
| `escpos-rs` | Rust | Async, image support |
| `node-thermal-printer` | Node.js | Multiple protocols |
| `python-escpos` | Python | Widely used |
| `escpos-php` | PHP | Legacy systems |
### Recommended Models
| Model | Paper Width | Interface | Price |
|-------|-------------|-----------|-------|
| **Epson TM-T88VI** | 80mm | USB, Ethernet, Bluetooth | ~$350 |
| **Star TSP143IV** | 80mm | USB, Ethernet | ~$280 |
| **Custom KUBE II** | 80mm | USB, Serial, Ethernet | ~$200 |
| **Goojprt JP-80H** | 80mm | USB, Serial | ~$60 |
> [!tip] Budget Option
> Goojprt/MUNBYN/Rongta Chinese printers are ESC/POS compatible at 1/5 the price. Suitable for testing and low-volume deployments.
**NixOS Integration:**
```nix
services.printing = {
enable = true;
drivers = [ pkgs.epson-escpr ];
};
```
---
## NFC Readers
### Primary Recommendation: ACR122U
> [!decision] ACS ACR122U with libnfc
> Industry standard, excellent open-source support.
| Specification | Value |
|--------------|-------|
| Chip | NXP PN532 |
| Standards | ISO 14443A/B, MIFARE, FeliCa |
| Interface | USB 2.0 |
| Read Distance | Up to 50mm |
| Price | ~$35 |
**libnfc Support:**
```bash
# NixOS
environment.systemPackages = [ pkgs.libnfc pkgs.mfoc pkgs.mfcuk ];
# Rust
cargo add nfc
# Node.js
npm install nfc-pcsc
```
### Alternative: PN532 Module
> [!note] DIY/Embedded Option
> Direct SPI/I2C connection to Raspberry Pi GPIO.
| Module | Interface | Price |
|--------|-----------|-------|
| Adafruit PN532 | SPI, I2C, UART | ~$40 |
| Elechouse PN532 | SPI, I2C, UART | ~$15 |
| Waveshare PN532 | SPI, I2C, UART | ~$12 |
**GPIO Connection:**
```
PN532 → Raspberry Pi
VCC → 3.3V (Pin 1)
GND → GND (Pin 6)
SDA → GPIO 2 (Pin 3)
SCL → GPIO 3 (Pin 5)
```
---
## Protocol Support Summary
### Bill Handling Protocols
| Protocol | Description | Open-Source Support |
|----------|-------------|---------------------|
| **eSSP** | Encrypted SSP (ITL) | Node.js, Python, C# |
| **SSP** | Standard SSP (ITL) | Node.js, Python |
| **ccTalk** | Serial coin/note protocol | C++, Qt |
| **ID-003** | JCM bill validator | JavaScript (lamassu) |
| **CCNET** | CashCode protocol | JavaScript (lamassu) |
| **MDB** | Vending standard | C, Rust |
### Recommended Protocol Stack
```mermaid
graph TB
subgraph "Rust HAL Layer"
essp[eSSP Driver]
cctalk[ccTalk Driver]
puloon[Puloon RS232]
escpos[ESC/POS]
nfc[libnfc]
end
subgraph "napi-rs Bindings"
napi[Node.js FFI]
end
subgraph "TypeScript Application"
app[Tauri + Vue 3]
end
app --> napi
napi --> essp
napi --> cctalk
napi --> puloon
napi --> escpos
napi --> nfc
essp --> nv200[NV200]
cctalk --> mei[MEI Cashflow]
puloon --> lcdm[Puloon LCDM]
escpos --> printer[Thermal Printer]
nfc --> reader[ACR122U]
```
---
## DIY Reference Projects
### FOSSA Bitcoin ATM
> [!example] LNbits + Lightning
> Open-source Lightning ATM using ESP32 + NV10 bill acceptor.
- **Repository:** github.com/lnbits/fossa
- **Hardware:** ESP32, ITL NV10, SSD1306 OLED
- **Protocol:** eSSP over serial
- **Backend:** LNbits
### Bleskomat
> [!example] Minimal Lightning ATM
> Coin-based Lightning vending machine.
- **Repository:** github.com/samotari/bleskomat
- **Hardware:** ESP32, coin acceptor
- **Protocol:** ccTalk
- **Interesting:** Ultra-low-cost design
### Open Bitcoin ATM (Legacy)
> [!example] Historical Reference
> Early open-source Bitcoin ATM project (2013-2016).
- **Repository:** github.com/mayosmith/OpenBitcoinATM
- **Hardware:** Raspberry Pi, various bill acceptors
- **Status:** Archived, but useful for protocol reference
---
## Recommended Bill of Materials
### Minimum Viable ATM
| Component | Model | Est. Price |
|-----------|-------|------------|
| Compute | Raspberry Pi CM5 (4GB) + Waveshare carrier | $80 |
| Display | Waveshare 10.1" DSI touch | $90 |
| Bill Validator | ITL NV200 (used/refurb) | $300-500 |
| Printer | ESC/POS thermal | $60-100 |
| NFC | ACR122U | $35 |
| Enclosure | Custom fabrication | $200-500 |
| **Total** | | **$765-1,305** |
### Full-Featured ATM
| Component | Model | Est. Price |
|-----------|-------|------------|
| Compute | Raspberry Pi CM5 (8GB) + industrial carrier | $150 |
| Display | Elo ESY15i5 | $800 |
| Bill Validator | ITL NV200 Spectral | $600 |
| Bill Dispenser | Puloon LCDM-2000 | $800 |
| Printer | Epson TM-T88VI | $350 |
| NFC | ACR122U | $35 |
| Enclosure | Industrial steel cabinet | $1,000-2,000 |
| **Total** | | **$3,735-4,735** |
---
## Migration Strategy
### Phase 1: Port Existing Drivers
1. Audit current lamassu-machine drivers:
- `lib/id003/` → Rust HAL
- `lib/ccnet.js` → Rust HAL
- `lib/puloon/` → Rust HAL
- `lib/mei/` → Rust HAL
- `lib/ssp.js` → Rust HAL
2. Create napi-rs bindings for TypeScript consumption
3. Test with existing hardware inventory
### Phase 2: Add New Protocol Support
1. Implement eSSP for NV200 support
2. Add ESC/POS for universal printer support
3. Integrate libnfc for NFC readers
### Phase 3: Hardware Validation
1. Create NixOS hardware test image
2. Validate all components on CM5
3. Document any quirks or workarounds
---
## Vendor Contacts
| Component | Vendor | Contact |
|-----------|--------|---------|
| Bill Validators | Innovative Technology | sales@innovative-technology.com |
| Bill Validators | MEI (Crane) | info@cranepi.com |
| Bill Dispensers | Puloon Technology | sales@puloon.com |
| Displays | Elo Touch | sales@elotouch.com |
| Displays | Waveshare | service@waveshare.com |
| Compute | Raspberry Pi | For bulk: sales@raspberrypi.com |
---
## Related Notes
- [[modernization-plan]] - Overall modernization roadmap
- [[machine-ui-modernization]] - Vue 3 + Tauri migration
- [[lnbits-integration]] - Lightning backend integration
- [[NixOS Configuration]] - Production deployment
---
## References
- [ITL NV200 Datasheet](https://innovative-technology.com/products/nv200/)
- [eSSP Protocol Guide](https://github.com/paysyslabs/ssp-server/wiki)
- [Raspberry Pi CM5 Documentation](https://www.raspberrypi.com/documentation/computers/compute-module.html)
- [libnfc Documentation](http://nfc-tools.org/index.php/Libnfc)
- [ESC/POS Command Reference](https://reference.epson-biz.com/modules/ref_escpos/index.php)

1
docs/modernization-plan.md
View file

@ -516,6 +516,7 @@ test('user can complete transaction', async ({ page }) => {
- [[CLAUDE]] - Claude Code guidance - [[CLAUDE]] - Claude Code guidance
- [[admin-ui-modernization]] - Vue 3 migration for admin dashboard - [[admin-ui-modernization]] - Vue 3 migration for admin dashboard
- [[machine-ui-modernization]] - Vue 3 migration for kiosk UI - [[machine-ui-modernization]] - Vue 3 migration for kiosk UI
- [[hardware-recommendations]] - Hardware component recommendations
- [[membership-lightning-integration]] - Membership & LNbits feature - [[membership-lightning-integration]] - Membership & LNbits feature
- [[lnbits-integration]] - Lightning backend integration - [[lnbits-integration]] - Lightning backend integration
- [[Architecture Decision Records]] - ADRs for each decision - [[Architecture Decision Records]] - ADRs for each decision