Bicara Serial dengan Kontroler Vending Machine

Bicara Serial dengan Kontroler Vending Machine

Mesin vending spring-coil modern — hardware kelas TCN yang mendominasi pasar — sebenarnya dua komputer dalam satu kabinet. Board Android menjalankan layar, pembayaran, dan software aplikasinya. Driver board terpisah menjalankan motor, drop sensor, dan kompresor — dan komunikasinya lewat serial.

Aplikasi Anda tidak pernah menyentuh motor langsung. Semua perintah lewat command board di port semacam /dev/ttyS3, dan semua yang Anda jual bergantung pada lancarnya percakapan itu.

Yang benar-benar dikirim vendor

Bukan dokumen protokol. Yang datang adalah AAR tertutup — format paket library Android — semacam tcn_springboard-release.aar, plus aplikasi demo dan dokumentasi yang tipis, hasil machine-translation, atau dua-duanya.

SDK-nya — paket kode siap pakai dari pabrikan untuk mengendalikan mesinnya — minta Application class aplikasi meng-extend base class miliknya dan serial port dikonfigurasi saat startup, lalu menjalankan VendService di background dan mengembalikan hasil lewat listener terdaftar berupa event ID bernomor. Biasanya ada langkah otorisasi satu kali yang terikat ke board.

Tidak ada yang aneh di sini. Ini bentuk standar SDK vendor hardware, dan melawannya buang-buang tenaga. Yang menentukan justru cara Anda mengurungnya.

Bungkus tipis, dan tulis panduan yang tidak ditulis vendor

Bayangkan penerjemah di pengadilan: pihak asing bicara bahasanya sendiri, tapi semua orang di ruangan cuma mendengar satu bahasa yang konsisten lewat dia. Wrapper tipis kerja seperti itu untuk SDK vendor.

Langkah praktisnya: satu modul di codebase yang memegang seluruh siklus hidup SDK — inisialisasi, konfigurasi serial port, registrasi listener — dan mengekspos interface kecil dalam kosakata sendiri: vend(slot, orderNo), querySlot(slot), setTemperature(mode), plus event stream yang bersih. Tipe-tipe SDK tidak pernah bocor keluar dari modul itu. Saat vendor merilis update yang breaking, atau proyek pindah ke keluarga kontroler lain, yang perlu dirombak cuma satu file itu.

Separuh sisanya dokumentasi: panduan SDK internal yang ditulis sendiri, mencatat apa yang sesungguhnya dibutuhkan integrasi — permission yang diminta SDK, setup AAR, konfigurasi serial port, event ID yang penting dan artinya dalam praktik. Biayanya satu sore, dan menghemat satu minggu bagi setiap developer berikutnya yang tak perlu lagi menggali fakta dari PDF hasil machine-translation. Di proyek integrasi, panduan itu saya perlakukan sebagai deliverable, bukan pelengkap.

Command, acknowledge, dan drop sensor

Semua komunikasi dengan board bersifat asinkron. Anda meminta vend; hasilnya datang belakangan sebagai event — sukses, gagal, atau tidak datang sama sekali. Diam pun sebuah jawaban, dan wajib Anda tangani:

Yang membedakan mesin yang beres dari mesin yang panen komplain adalah drop sensor. Motor berputar bukan jaminan barang keluar — bisa jadi spring macet, produk terjepit, atau coil-nya habis satu baris lebih awal. Sensor inilah yang memastikan ada barang yang benar-benar jatuh.

Aturan turunannya: jangan pernah menandai order terkirim sebelum drop terkonfirmasi, dan sambungkan jalur gagal dan timeout langsung ke refund. Pelanggan yang bayar dan tidak dapat apa-apa memaafkan mesin yang refund seketika. Mereka tidak memaafkan mesin yang cuek.

Fault slot perlu diperlakukan sama seriusnya. Board melaporkan event sold-out dan fault per slot — perlakukan slot yang gagal dua kali berturut-turut sebagai macet, keluarkan otomatis dari pool yang bisa dijual, dan biarkan manusia mengaktifkannya lagi setelah inspeksi.

Telemetri yang layak ditangkap

Jalur serial membawa lebih dari sekadar perintah vend, dan kebanyakan integrasi menyia-nyiakannya. Layak disimpan sejak hari pertama: stok per slot, suhu kabinet (kompresor yang mulai rusak ketahuan dari suhunya beberapa hari lebih awal), hitungan vend gagal per slot (pola khas slot macet), event pintu terbuka, dan event pembayaran dari hardware uang kertas dan koin.

Stream itulah yang membuat mesin-mesin yang tersebar bisa dikelola sebagai satu sistem — rute restock direncanakan dari data, mesin ditandai sebelum pelanggan komplain. Menyalurkannya ke dashboard adalah masalah normalisasi yang sama seperti pada perangkat IoT campuran lainnya; pendekatannya ada di normalisasi perangkat IoT multi-protokol.

Catatan kaki lisensi yang bukan catatan kaki

AAR itu datang tanpa teks lisensi. Status hukumnya — apa yang boleh Anda redistribusikan, kepada siapa, di dalam produk apa — sering kali memang tidak jelas, dan "semua orang juga pakai" bukan berarti boleh.

Sebelum SDK itu ikut terkirim di dalam produk, pertanyaan redistribusi harus masuk kontrak pengadaan dengan vendor mesin. Panduan lengkap soal apa yang boleh dan tidak boleh Anda ship ada di lisensi open-source di software komersial.

Intinya

Terima SDK vendor sebagai kondisi lapangan yang tidak bisa ditawar: kurung di balik wrapper tipis, dokumentasikan sendiri, hormati model command/ack yang asinkron, percayai drop sensor dan bukan putaran motor, dan tangkap telemetri yang memang sudah ditawarkan jalur serial.

Setelah itu, mesin-mesin tadi jadi sebagaimana mestinya — endpoint lapangan yang membosankan dan terpantau.