README

PHP helper library that wraps the ftdi extension with global functions and enums. Each helper delegates to Ftdi\FTDI.

This project provides direct bindings to libftdi1 through helper-style globals.

Highlights

• C-ish global helper API (ftdi_usb_open, ftdi_read_data, etc.)
• Support for serial-only devices (for example FT232RL) and MPSSE-capable devices (for example FT232H)
• USB open/read/write/flush/reset operations
• EEPROM read/write/decode/build operations
• Async transfer submission and completion

Requirements

• PHP 8.3+
• ext-ftdi ^0.4.0 - install from php-io-extensions/ftdi
• Runtime dependency of ext-ftdi:
  • Debian/Ubuntu/Raspberry Pi OS: libftdi1-2 (dev package for builds: libftdi1-dev)
  • macOS: brew install libftdi

Installation

Confirm ext-ftdi is loaded before using this package:

php -m | grep ftdi

Install the helper package:

composer require microscrap/ftdi

Composer autoloads src/Helpers/ftdi.php, registering global helpers when installed.

Usage

FTDI bindings are exposed as global helper functions (ftdi_new, ftdi_usb_open, etc). Helpers are only defined when a function name is not already taken (function_exists guard), matching the style used in other microscrap binding packages.

Optional enums are available under:

• Microscrap\Bindings\FTDI\Enums\FtdiVendorId
• Microscrap\Bindings\FTDI\Enums\FtdiProductId

<?php

$ftdi = ftdi_new();
if ($ftdi->handle < 0) {
    throw new RuntimeException('ftdi_new failed');
}

ftdi_init($ftdi);

// FT232RL defaults: vendor 0x0403, product 0x6001
if (ftdi_usb_open($ftdi, 0x0403, 0x6001) !== 0) {
    throw new RuntimeException(ftdi_get_error_string($ftdi));
}

ftdi_set_baudrate($ftdi, 115200);
ftdi_set_line_property($ftdi, 8, 1, 0); // 8N1

ftdi_write_data($ftdi, "hello\n", 6);
$response = ftdi_read_data($ftdi, 256);

ftdi_usb_close($ftdi);
ftdi_deinit($ftdi);
ftdi_free($ftdi);

Constants and enum values follow libftdi1 conventions. Define them in PHP or load them from your platform headers.

Global Helper API

ftdi_new(): Ftdi\FTDIContext

Allocates a new libftdi1 context (ftdi_new). Check $ctx->handle >= 0 before use.

ftdi_init(Ftdi\FTDIContext $ftdi): int

Initialises an allocated context (ftdi_init). Returns 0 on success.

ftdi_deinit(Ftdi\FTDIContext $ftdi): void

Deinitialises the context (ftdi_deinit) without freeing it.

ftdi_free(Ftdi\FTDIContext $ftdi): void

Frees the context (ftdi_free). Do not use it afterward.

ftdi_usb_open(Ftdi\FTDIContext $ftdi, int $vendor, int $product): int

Opens the first device matching vendor/product (ftdi_usb_open). Returns 0 on success.

ftdi_usb_close(Ftdi\FTDIContext $ftdi): int

Closes the open USB connection (ftdi_usb_close).

ftdi_set_baudrate(Ftdi\FTDIContext $ftdi, int $baudrate): int

Sets UART baud rate (ftdi_set_baudrate).

ftdi_set_line_property(Ftdi\FTDIContext $ftdi, int $bits, int $sbit, int $parity): int

Sets line framing (ftdi_set_line_property).

ftdi_write_data(Ftdi\FTDIContext $ftdi, string $data, int $size): int

Writes up to $size bytes (ftdi_write_data).

ftdi_read_data(Ftdi\FTDIContext $ftdi, int $size): string

Reads up to $size bytes (ftdi_read_data).

ftdi_set_bitmode(Ftdi\FTDIContext $ftdi, int $bitmask, int $mode): int

Enables/disables bitbang or MPSSE mode (ftdi_set_bitmode).

ftdi_get_error_string(Ftdi\FTDIContext $ftdi): string

Returns the last libftdi1 error string (ftdi_get_error_string).

Quick reference

License

MIT. See LICENSE.