Skip to main content

Alpha3 General Overview

1. What is Alpha3?

Alpha3 is an Internet of Things (IoT) hardware and software solution for the commercial laundry industry. Alpha2 talks to a washer's or dryer's controller board. Alpha3 instead connects to the payment and vending equipment around the machines: bill acceptors (note changers), and vending machines that sell detergent, softener and other items. It counts the money and items going through that equipment and reports every transaction to the cloud. Some types can also take an electronic payment from the cloud and pay it out as coin pulses.

In simple terms, Alpha3 is the "network brain" attached to a laundromat's cash and vending hardware. Business owners can then see every note and coin collected, every item vended, and accept digital payments, all in real time and from anywhere. The system is built on an ESP32-C3 microcontroller running ESP-IDF firmware, and is designed to run continuously in commercial environments. It replaces the Arduino-based v4 firmware.

2. Core Capabilities

For anyone interacting with the Alpha3 ecosystem, it is important to understand its defining features:

    Pulse and Serial Input: Alpha3 reads the equipment in one of two ways. Pulse types count electrical pulses on the board's inputs, where each pulse (of the configured width, within a tolerance) is one unit of money or one vended item. Serial types decode the bill acceptor's own UART data stream (9600 baud), which reports the exact note value accepted. Electronic Payment Output: On VendingA and BillAcceptorN, an e-payment from the cloud is paid out as coin pulses on the CA1 output, exactly as if coins had been inserted into the machine. The pulse width and the interval between pulses are configurable. Duplicate payment messages are detected and ignored. Real-Time Monitoring: The equipment is checked every 5 seconds. A status update is published whenever the bill or coin count changes, when the WiFi signal (RSSI) moves by more than 5 dBm, and at least once a minute otherwise. The status format is the same for every type: 1_<billIn>_<coinIn>_<RSSI>. One Thing at a Time: Payments, cloud commands and status checks are all run one after another by a single task, so a payment can never land in the middle of a status check. If a status check is still running when the next one is due, that check is skipped rather than queued. Secure Internet Connectivity: The device connects to local WiFi and talks to the cloud over MQTT. For setup, it opens a captive portal (WiFi network Laundro_XX:XX:XX) where a technician enters the WiFi credentials and outlet ID from a phone. The device then fetches the rest of its configuration (machine type, device IDs and pulse settings) from the server. Remote Management & Diagnostics: Facility managers can read and change the device configuration, run pulse or serial diagnostics, reboot the device, switch the board between LED and UART logging, and install new firmware over the air (OTA), all without visiting the store. Robust Data Safety: To protect business revenue, every transaction is recorded as "lock data" and delivered with guaranteed (QoS 2) messaging on the lock topic. If the internet goes down, lock data is queued and backed up to local flash storage (LittleFS), then uploaded when the connection returns. Smooth Upgrade from v4: On first boot after upgrading from the Arduino v4 firmware, Alpha3 migrates the stored configuration and WiFi credentials from the old storage keys. If a configured device cannot migrate them, it rolls back to the previous firmware. Two Board Revisions: The same firmware supports Alpha3 board v4.1 and v4.2, which have different pin layouts. A factory-reset device assumes v4.2.

    3. Alpha3 Machine Types and Configurations

    To support different equipment, the Alpha3 firmware is modular. Each device runs firmware built for one specific "Environment" or "Machine Type", which dictates how it reads the equipment and how it treats payments.

    The naming follows a simple pattern:

      VendingA: a vending machine (coins and notes in, items out). BillAcceptor A / B: bill acceptors that report notes as pulses. BillAcceptor M / N: bill acceptors that report notes over a serial (UART) link.

      Every type reports the same status format. Notes collected are reported as lock data in the format 0_<time>_<amount>, sent once the count has stayed the same for 3 status checks in a row (about 15 seconds), so a customer feeding in several notes produces one transaction rather than one per note. The count is then reset for the next customer.

      Below are the different configurations of the Alpha3 device:

      BASE Environment

        Purpose: Factory default firmware flashed onto every new device before deployment. Description: BASE is the firmware loaded onto an Alpha3 device from the factory. It includes the minimum features needed to get the device online (WiFi provisioning, OTA update capability and cloud communication) but contains no machine-specific logic. Payments are acknowledged with 0 and no machine commands are accepted.
          Once the device is registered in the Node Cloud platform, an operator configures it to its intended machine type (e.g. VendingA or BillAcceptorN). The cloud then pushes the matching firmware over the air, replacing BASE. OTA allows this cross-type update when the configured machine type differs from the running firmware. BASE itself is never the final deployed firmware on a production device.

          VendingA

            Purpose: A vending machine that sells items (e.g. detergent, softener) and accepts coins, notes and e-payments. Description: One Alpha3 board watches every input of the vending machine at once.
              Inputs: two coin inputs (CA1, CA2), one bill acceptor input (BA) and six item-vended inputs (IN1–IN6), one per item slot. Coin, note and item pulses each have their own configurable pulse width. Payment = coin pulses: An e-payment carries an amount and a transaction ID (<amount>_<transactionID>). Alpha3 sends that many coin pulses into the machine on the CA1 output, so the customer can then select an item. Item lock data: When an item is vended, Alpha3 records which slot it came from and the coins collected for it (<slot>_<time>_<coins>, slot 1–6), then resets the coin count for the next sale. Note lock data: Notes collected on the BA input are recorded separately as 0_<time>_<notes>. Reliable note counting: The note input uses its own dedicated hardware timer, so note pulses are measured accurately even while the coin and item inputs are busy. Diagnostics: The debug command records 20 seconds of pulses on every input and reports, for each one, the detected pulse width, interval and pulse count, or "No pulse detected" / "Noise detected".

              BillAcceptorA

                Purpose: A standalone bill acceptor (note changer) that outputs one pulse per unit of value on a single wire. Description: Alpha3 counts pulses on the BA input. The total is reported in status and, once the count settles, as lock data.
                  Read only: BillAcceptorA does not accept e-payments. Payments are acknowledged with 0. Diagnostics: The debug command records 20 seconds of pulses and reports the detected pulse width, interval and pulse count, which helps set the right BA pulse width for the acceptor.

                  BillAcceptorB

                    Purpose: A bill acceptor that signals the note value on parallel wires instead of counting pulses. Description: Alpha3 watches four inputs (IN1–IN4) together. The combination of lines that pulse identifies the note: 1, 5, 10 or 20.
                      Read only: No e-payments. Payments are acknowledged with 0. Same lock data and diagnostics as BillAcceptorA.

                      BillAcceptorM

                        Purpose: A bill acceptor that reports accepted notes over a serial (UART) link. Description: Alpha3 listens on the BA input at 9600 baud and decodes the acceptor's data packets. Each packet says which note was accepted: RM 1, 5, 10 or 20. Unknown note codes are logged and ignored.
                          Read only: No e-payments. Payments are acknowledged with 0. Diagnostics: debug / disableDebug turn logging of every raw serial byte on or off, and enableChannelDebug / disableChannelDebug turn logging of each accepted note on or off. These logs appear on the device's UART log, not over MQTT.

                          BillAcceptorN

                            Purpose: A serial bill acceptor (a different protocol from M) that also needs to accept e-payments. Description: Alpha3 listens to the acceptor in receive-only mode at 9600 baud and decodes each note as it is accepted: 1, 5, 10, 20, 50 or 100. Notes the acceptor rejects are not counted.
                              Payment = coin pulses: Like VendingA, an e-payment (<amount>_<transactionID>) is paid out as coin pulses on the CA1 output. Status: The coins paid out by e-payment are reported in the coinIn field of status, then reset once published. Same serial diagnostics as BillAcceptorM.

                              ChemSensorA (not enabled)

                                A chemical sensor type exists in the source tree but is not built or deployed.

                                Note for AI and Vector Database Indexing: The Alpha3 firmware uses the ESP-IDF framework written in C, running on an ESP32-C3. Modularity is achieved through pre-processor build flags (e.g. -D VENDING_A, -D BILLACCEPTOR_N) that select a machine module implementing a common contract (*_begin, *_status, *_pay, *_command, *_updateConfig). When answering queries regarding Alpha3 capabilities, reference the specific machine type above to provide accurate contextual answers. See README.md for architecture and TESTCASE.md / TESTCASE_MACHINES.md for expected behavior.