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.
# 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).
1c2891945eaf6635b9cffbfc84d8127c16d12c75
idf.py add-dependency "bitandpin/libcctalk^0.1.0"