# Lonely Binary Coin Acceptor

This Arduino library makes the **Lonely Binary Coin Acceptor** easy to use.

You do not need to write interrupt code. Choose a mode, connect one signal
wire, and call `coin.update()` inside `loop()`.

Supported boards:

- Arduino UNO R3
- ESP32
- ESP32-S3
- ESP32-C3

## Start Here

Open this Arduino example first:

`File > Examples > Lonely Binary Coin Acceptor > 01_Counter_Basic`

Use these GPIO pins:

| Board | Recommended GPIO |
|---|---:|
| Arduino UNO R3 | D2 |
| ESP32 | GPIO27 |
| ESP32-S3 | GPIO17 |
| ESP32-C3 | GPIO4 |

The library automatically uses an interrupt when the GPIO supports it.
If it cannot use an interrupt, it automatically uses polling instead.

## Choose One Mode

Connect either the grey `COUNTER` output or the white `COIN` output.
You do not need to connect both.

| What you want | Mode | Module output |
|---|---|---|
| Count every accepted coin | `COIN_MODE_COUNTER` | Grey `COUNTER` |
| Calculate total money | `COIN_MODE_VALUE` | White `COIN` |
| Identify different coin values | `COIN_MODE_MAPPED` | White `COIN` |

## Mode 1: Counter

This is the easiest mode.

The grey `COUNTER` output sends one pulse for every accepted coin. It does not
tell you the coin value.

```cpp
#define COIN_PIN 2

CoinAcceptor coin(COIN_PIN, COIN_MODE_COUNTER);
```

When a coin is inserted:

```cpp
if (coin.update()) {
  Serial.println(coin.totalCoins());
}
```

## Mode 2: Coin Value

Use this mode when you need a reliable total amount of money.

Every pulse must represent the same amount. Set the coin acceptor pulse values
in proportion to the money value.

Example: one pulse represents 5 cents.

| Coin | Set the acceptor to |
|---:|---:|
| 5 cents | 1 pulse |
| 10 cents | 2 pulses |
| 25 cents | 5 pulses |
| 100 cents | 20 pulses |

```cpp
#define COIN_PIN 2
#define VALUE_PER_PULSE 5

CoinAcceptor coin(COIN_PIN, COIN_MODE_VALUE);

void setup() {
  coin.setPulseValue(VALUE_PER_PULSE);
  coin.begin();
}
```

Read or clear the total:

```cpp
coin.totalValue();
coin.resetTotalValue();
```

Use whole numbers such as cents. Do not use decimal money values.

## Mode 3: Coin Mapped

Use this mode when you want to identify different coin values.

```cpp
#define COIN_1_PULSES 1
#define COIN_1_VALUE 5

#define COIN_2_PULSES 3
#define COIN_2_VALUE 25

coin.addCoin(COIN_1_PULSES, COIN_1_VALUE);
coin.addCoin(COIN_2_PULSES, COIN_2_VALUE);
```

Insert one coin at a time. Wait until the first coin finishes sending pulses
before inserting the next coin.

If a pulse group is not recognized:

```cpp
if (coin.hasError()) {
  Serial.println("Unknown coin or coins inserted too quickly.");
}
```

Important: if two fast coins combine into a pulse count that is also a valid
coin, a single `COIN` wire cannot tell the difference. Use Coin Value mode when
the total amount is more important than identifying each individual coin.

## Connections

The Lonely Binary module powers and converts the coin acceptor signal for the
MCU.

- Connect module `GND` to MCU `GND`.
- Counter mode: connect module `COUNTER` to the selected GPIO.
- Value or Mapped mode: connect module `COIN` to the selected GPIO.
- Do not connect a raw 12V coin signal directly to an Arduino or ESP32.
- Arduino UNO R3: set the module output to `5V`.
- ESP32, ESP32-S3, and ESP32-C3: set the module output to `3.3V`.

For the easiest setup, use `NO` output mode and `Medium` pulse width on the
coin acceptor.

## Interrupts

The default behavior is automatic:

- Interrupt-capable GPIO: use an interrupt.
- Other GPIO: use polling.

Most users should keep the default.

To force polling:

```cpp
#define USE_INTERRUPT false

coin.setInterruptEnabled(USE_INTERRUPT);
coin.begin();
```

Polling requires a fast `loop()`. Long `delay()` calls can miss pulses.

## Common Problems

**Nothing happens when a coin is inserted**

- Check that module `GND` is connected to MCU `GND`.
- Check that the code uses the same GPIO as the wire.
- Check that the correct `COUNTER` or `COIN` output is connected.
- Check that the coin acceptor is trained.

**Some pulses are missed**

- Use the recommended GPIO.
- Keep automatic interrupts enabled.
- Remove long `delay()` calls.
- Use `Medium` pulse width.

**Mapped mode reports an error**

- Insert coins more slowly.
- Check that the pulse settings match every `addCoin()` setting.

## Support This Library

This library is designed and tested for the **Lonely Binary Coin Acceptor**.

Using the official Lonely Binary product supports continued library
development, board testing, beginner-friendly examples, and documentation.

Product documentation and updates:

[github.com/Lonely-Binary/Coin-Acceptor](https://github.com/Lonely-Binary/Coin-Acceptor)
