You are using staging server - a separate instance of the ESP Component Registry that allows you to try distribution tools and processes without affecting the real registry.

bitandpin/libcctalk

0.1.0

Latest
uploaded 55 minutes ago
ccTalk v4.7 host library for coin acceptors, bill validators, hoppers and changers

Readme

# libcctalk

Portable C99 library implementing the host (master) side of the **ccTalk serial protocol** (v4.7) for coin acceptors, bill validators, hoppers, changers, and payment peripherals.

## Features

- Command wrappers for coin acceptors, bill validators, hoppers and changers, each checked against the byte layout in Part 2 of the specification
- Simple 8-bit checksum and CRC-CCITT per spec Part 1 §7
- Replies are validated before use: length, checksum, destination and source address, reply header
- Half-duplex local echo is compared with the transmitted packet (Part 4 §1.2.11)
- Retransmission with configurable attempts (Part 1 §12.1); commands that move money are sent once and never retried
- Multi-drop MDCES (address poll / clash / change / random, Part 1 §20.2)
- Coin and bill ID parsing with exact values for every value code in the specification, and a decoder for Coin Value Format bytes
- Event counter tracking for the credit polling loop, including the start-up rule that keeps stale buffer entries from being credited
- Coin, fault, status and bill event code tables per Part 3 Tables 2, 3, 4 and 7
- Single public header — zero dependencies beyond platform SDK

### What it does not do

The library implements **no cryptography**. The encryption-related commands
(DES / AES key switching, Diffie-Hellman key exchange, encrypted event and
status requests, hopper dispense security bytes) only carry bytes to and from
the device; computing keys, challenges and ciphertext is the caller's job. The
encrypted packet layout of Part 1 §7.3 is not implemented.

It is a host only: it sends commands and reads replies, and cannot act as a
peripheral. It does no locking; guard a context with a mutex if several tasks
share it.

## Platforms

| Platform | Build | HAL backend |
|----------|-------|-------------|
| **ESP-IDF 5.5 or later** (built on 5.5 and 6.1 for ESP32, ESP32-S3, ESP32-C3) | `idf.py build` | `cctalk_hal_esp32` (UART driver) |
| **Linux / macOS** | `make` | `cctalk_hal_posix` (termios) |
| **Windows** | `make PLATFORM=win32 CC=x86_64-w64-mingw32-gcc` | `cctalk_hal_win32` (Win32 API) |

The protocol code and all three serial drivers are covered by host tests (see
[Testing](#testing)). The drivers have not yet been verified on physical
hardware; treat the first run on a board or adapter as part of your bring-up.

## Quick Start

### Linux

```bash
make          # build libcctalk.a
make test     # build and run all test programs
```

```c
#include "cctalk.h"

int main(void) {
    cctalk_hal_t hal = cctalk_hal_posix_init();
    cctalk_ctx_t ctx;
    cctalk_init(&ctx, &hal);
    ctx.echo_on_bus = true;

    cctalk_open(&ctx, "/dev/ttyUSB0", 9600);
    cctalk_simple_poll(&ctx);          // ping device
    cctalk_close(&ctx);
    cctalk_hal_posix_deinit(&hal);
    return 0;
}
```

### ESP-IDF

Add the component to your project:

```bash
idf.py add-dependency "bitandpin/libcctalk"
```

or, to work from a checkout, point your `main/idf_component.yml` at it:

```yaml
dependencies:
  bitandpin/libcctalk:
    version: "*"
    override_path: "/path/to/libcctalk"
```

Then:

```c
#include "cctalk.h"

void app_main(void) {
    cctalk_hal_t hal = cctalk_hal_esp32_init();
    cctalk_ctx_t ctx;
    cctalk_init(&ctx, &hal);
    ctx.echo_on_bus = true;
    ctx.device_addr = 2;

    cctalk_open(&ctx, NULL, 9600);     // NULL → uses Kconfig pins
    cctalk_simple_poll(&ctx);
    cctalk_close(&ctx);
    cctalk_hal_esp32_deinit(&hal);
}
```

Pin assignments are configured via `idf.py menuconfig` → **ccTalk Protocol**.
To choose them at run time, or to run several buses on different UARTs, use
`cctalk_hal_esp32_init_config()` instead:

```c
cctalk_hal_esp32_config_t cfg = { .uart_num = 2, .tx_pin = 25, .rx_pin = 26 };
cctalk_hal_t hal = cctalk_hal_esp32_init_config(&cfg);
```

The ccTalk bus is 5 V and single-wire; the wiring the driver expects (diode on
TX, level shifter on RX) is described at the top of
`src/hal/cctalk_hal_esp32.c`.

## Polling for credits

Coin acceptors and bill validators keep the last five events in a buffer with
an event counter. Let the tracker work out what is new: its first update only
stores the counter, so events that happened before the host started are not
credited again.

```c
cctalk_credit_t events;
cctalk_event_tracker_t tracker;
cctalk_event_update_t update;

cctalk_event_tracker_init(&tracker);
for (;;) {
    if (cctalk_read_credit(&ctx, &events) != CCTALK_OK) {
        continue;
    }
    cctalk_event_tracker_update(&tracker, events.counter, &update);
    if (update.reset) {
        /* device was reset or lost power: credits may be lost, re-enable it */
    }
    /* events.events[0] is the newest; walk backwards for arrival order */
    for (int i = update.new_events - 1; i >= 0; i--) {
        /* result_a > 0: credit for coin result_a; 0: error code in result_b */
    }
    ctx.hal.delay_ms(200);
}
```

## Several devices on one bus

`ctx.device_addr` is the address of the peripheral the next command goes to;
the host's own address is `ctx.host_addr` (1). To talk to several devices,
change `device_addr` before each command and keep one event tracker per
device:

```c
ctx.device_addr = 2;                      /* coin acceptor */
cctalk_read_credit(&ctx, &coin_events);
ctx.device_addr = 40;                     /* bill validator */
cctalk_read_bill_events(&ctx, &bill_events);
```

## Architecture

```
┌─────────────────────────────────────┐
│  Convenience API (coin, bill,       │
│  hopper, changer, misc, data)       │
├─────────────────────────────────────┤
│  Transport (send / receive / retry) │
├─────────────────────────────────────┤
│  Message (build / parse / validate) │
├──────────┬──────────┬───────────────┤
│  HAL     │  HAL     │  HAL          │
│  POSIX   │  Win32   │  ESP32        │
└──────────┴──────────┴───────────────┘
```

- **HAL** — 6-function vtable (`open`, `close`, `write`, `read`, `flush`, `delay_ms`). Zero platform dependencies in the core.
- **Message** — builds and parses both simple-checksum and CRC-CCITT packets.
- **Transport** — half-duplex echo handling, inter-byte timeout, checksum validation, retransmission.
- **Convenience** — domain-specific wrappers: `cctalk_simple_poll()`, `cctalk_read_credit()`, `cctalk_dispense_coins()`, etc.

## API Overview

```c
// Lifecycle
cctalk_hal_t hal = cctalk_hal_posix_init();   // or cctalk_hal_esp32_init() / cctalk_hal_win32_init()
cctalk_init(&ctx, &hal);
cctalk_open(&ctx, device, 9600);
// ... use ...
cctalk_close(&ctx);
cctalk_hal_posix_deinit(&hal);                // or the matching _esp32_deinit() / _win32_deinit()

// Core
cctalk_simple_poll(&ctx);
cctalk_reset_device(&ctx);
cctalk_request_manufacturer_id(&ctx, buf, sizeof(buf));
cctalk_request_serial_number(&ctx, &serial);

// Coin acceptor
cctalk_read_credit(&ctx, &events);
cctalk_enable_all_coins(&ctx);
cctalk_request_coin_id(&ctx, 1, &coin);

// Bill validator
cctalk_read_bill_events(&ctx, &events);
cctalk_route_bill(&ctx, CCTALK_BILL_ROUTE_STACK);   // 0 = done, 254/255 = device error code

// Hopper / payout
cctalk_enable_hopper(&ctx, true);
cctalk_dispense_coins(&ctx, security, security_len, 5, &counter, &has_counter);  // sent once
cctalk_request_hopper_status(&ctx, &status);   // event counter, remaining, paid, unpaid
cctalk_emergency_stop(&ctx, &coins_remaining);

// Changer
cctalk_pay_money_out(&ctx, 250);               // sent once
cctalk_verify_money_out(&ctx, &paid);          // event counter, paid, unpaid

// Error handling
const char *msg = cctalk_strerror(ret);
```

Full API: see [`include/cctalk.h`](include/cctalk.h).

## Configuration

| Context field | Default | Description |
|---------------|---------|-------------|
| `host_addr` | 1 | Host (master) address; must be 1 in CRC mode |
| `device_addr` | 2 | Address of the device the next command is sent to |
| `echo_on_bus` | false | Half-duplex bus: expect and check the local echo of each command |
| `max_retries` | 3 | Transport retry attempts |
| `retry_delay_ms` | 0 | Pause before each retransmission |
| `use_crc` | false | Use CRC-CCITT instead of simple checksum |
| `answer_timeout_ms` | 1000 | Time allowed for a reply to start; raise it for slow commands such as the ROM checksum |
| `interbyte_timeout_ms` | 50 | Longest gap allowed inside a packet |

## Testing

```bash
make test              # every test program
make test SANITIZE=1   # the same under AddressSanitizer + UBSan
```

Everything runs on a Linux host; no hardware is needed.

- **Conformance** (`test_spec_*.c`, `test_transport_spec.c`): each command is
  run through a scripted serial port (`test/mock_hal.h`) and the exact bytes
  sent and the values decoded from literal reply bytes are asserted, using the
  specification's own example exchanges where it has them. The scripted port
  has a virtual clock, so time-outs and listening windows are asserted too.
- **Sessions** (`test_session_trace.c`): whole host/device exchanges and a
  frame captured from a real bill validator, taken from other open-source
  ccTalk projects.
- **Error paths** (`test_error_paths.c`): silent devices, NAKs, closed ports
  and misbehaving serial drivers.
- **Serial drivers** (`test_hal_*.c`): the POSIX driver on pseudo-terminals;
  the ESP32 and Windows drivers on fakes of the ESP-IDF UART and Win32 serial
  APIs.

A change that drifts from the specification fails one of the conformance
tests. When adding or changing a command, add its frame to the matching
`test_spec_*.c` with the Part/section it comes from.

## References

- ccTalk Generic Specification Issue 4.7, Parts 1–4 (public domain document; a copy is in `docs/` of the source repository)
- [ESP-IDF Style Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/style-guide.html)

## License

MIT — see [LICENSE](LICENSE).

Links

Maintainer

  • Bit & Pin <bitandpin@gmail.com>
To add this component to your project, run:

idf.py add-dependency "bitandpin/libcctalk^0.1.0"

download archive

Stats

  • Archive size
    Archive size ~ 65.45 KB
  • Downloaded in total
    Downloaded in total 0 times
  • Downloaded this version
    This version: 0 times

Badge

bitandpin/libcctalk version: 0.1.0
|