@johntalton/ftdi 1.0.0

package/src/mpsse/command.ts

@@ -0,0 +1,113 @@
+export const BAD_COMMAND = 0xAF // suggested bad command
+export const BAD_COMMAND_RESPONSE = 0xFA // first response byte when any bad command sent
+
+// Shifting commands IN MPSSE Mode
+export const SHIFT_COMMANDS_DEFINITION = {
+	WRITE_NEGATIVE_EDGE: 0b0000_0001, // -ve CLK on write
+	BIT_MODE:            0b0000_0010, // bit mode = 1 else byte mode
+	READ_NEGATIVE_EDGE:  0b0000_0100, // -ve CLK on read
+	LSB_FIRST:           0b0000_1000, // LSB first = 1 else MSB first
+	WRITE_TDI:           0b0001_0000, // Do write TDI
+	READ_TDO:            0b0010_0000, // Do read TDO
+	WRITE_TMS:           0b0100_0000  // Do writeTMS
+}
+
+export type ShiftCommand = number
+
+export const SHIFT_COMMAND = {
+	OUT_MSB_BYTES_POSITIVE_VE: 0x10, // WRITE_TDI
+	OUT_MSB_BYTES_NEGATIVE_VE: 0x11, // WRITE_TDI | WRITE_NEGATIVE_EDGE
+	OUT_MSB_BITS_POSITIVE_VE:  0x12, // WRITE_TDI | BIT_MODE
+	OUT_MSB_BITS_NEGATIVE_VE:  0x13, // WRITE_TDI | BIT_MODE | WRITE_NEGATIVE_EDGE
+
+	IN_MSB_BYTES_POSITIVE_VE: 0x20, // READ_TDO
+	IN_MSB_BYTES_NEGATIVE_VE: 0x24, // READ_TDO | READ_NEGATIVE_EDGE
+	IN_MSB_BITS_POSITIVE_VE:  0x22, // READ_TDO | BIT_MODE
+	IN_MSB_BITS_NEGATIVE_VE:  0x26, // READ_TDO | BIT_MODE | READ_NEGATIVE_EDGE
+
+	IN_OUT_MSB_BYTES_OUT_NEGATIVE_IN_POSITIVE_VE: 0x31,
+	IN_OUT_MSB_BYTES_OUT_POSITIVE_IN_NEGATIVE_VE: 0x34,
+	IN_OUT_MSB_BITS_OUT_NEGATIVE_IN_POSITIVE_VE: 0x33,
+	IN_OUT_MSB_BITS_OUT_POSITIVE_IN_NEGATIVE_VE: 0x36,
+
+	//
+	OUT_LSB_BYTES_POSITIVE_VE: 0x18, // LSB_FIRST | WRITE_TDI
+	OUT_LSB_BYTES_NEGATIVE_VE: 0x19, // LSB_FIRST | WRITE_TDI | WRITE_NEGATIVE_EDGE
+	OUT_LSB_BITS_POSITIVE_VE: 0x1A, // LSB_FIRST | WRITE_TDI | BIT_MODE
+	OUT_LSB_BITS_NEGATIVE_VE: 0x1B, // LSB_FIRST | WRITE_TDI | BIT_MODE | WRITE_NEGATIVE_EDGE
+
+	IN_LSB_BYTES_POSITIVE_VE: 0x28, // LSB_FIRST | READ_TDI
+	IN_LSB_BYTES_NEGATIVE_VE: 0x2C, // LSB_FIRST | READ_TDI | READ_NEGATIVE_EDGE
+	IN_LSB_BITS_POSITIVE_VE: 0x2A, // LSB_FIRST | READ_TDI | BIT_MODE
+	IN_LSB_BITS_NEGATIVE_VE: 0x2E, // LSB_FIRST | READ_TDI | BIT_MODE | READ_NEGATIVE_EDGE
+
+	IN_OUT_LSB_BYTES_OUT_NEGATIVE_IN_POSITIVE_VE: 0x39,
+	IN_OUT_LSB_BYTES_OUT_POSITIVE_IN_NEGATIVE_VE: 0x3C,
+	IN_OUT_LSB_BITS_OUT_NEGATIVE_IN_POSITIVE_VE: 0x3B,
+	IN_OUT_LSB_BITS_OUT_POSITIVE_IN_NEGATIVE_VE: 0x3E,
+
+}
+
+// export const LSB_FIRST_TMS_COMMANDS = {
+// 	CLOCK_DATA_NO_READ_POSITIVE_VE: 0x4A,
+// 	CLOCK_DATA_NO_READ_NEGATIVE_VE: 0x4B,
+
+// 	CLOCK_DATA_WITH_READ_ON_POSITIVE_VE_READ_POSITIVE_VE: 0x6A,
+// 	CLOCK_DATA_WITH_READ_ON_NEGATIVE_VE_READ_POSITIVE_VE: 0x6B,
+// 	CLOCK_DATA_WITH_READ_ON_POSITIVE_VE_READ_NEGATIVE_VE: 0x6E,
+// 	CLOCK_DATA_WITH_READ_ON_NEGATIVE_VE_READ_NEGATIVE_VE: 0x6F
+// }
+
+export const PIN_STATE_COMMANDS = {
+	SET_DATA_BITS_LOW_BYTE: 0x80,
+	SET_DATA_BITS_HIGH_BYTE: 0x82,
+
+	READ_DATA_BITS_LOW_BYTE: 0x81,
+	READ_DATA_BITS_HIGH_BYTE: 0x83
+}
+
+export const LOOPBACK_COMMANDS = {
+	ENABLED: 0x84,
+	DISABLE: 0x85
+}
+
+export const CLOCK_DIVISOR_COMMANDS = {
+	SET_CLK_DIVISOR: 0x86
+}
+
+export const HOST_AND_MPSSE_MODE_COMMANDS = {
+	SEND_IMMEDIATE: 0x87,
+	// WAIT_IO_HIGH: 0x88,
+	// WAIT_IO_LOW: 0x89
+}
+
+// export const HOST_EMULATION_MODE_COMMANDS = {
+// 	READ_SHORT_ADDRESS: 0x90,
+// 	READ_EXTENDED_ADDRESS: 0x91,
+// 	WRITE_SHORT_ADDRESS: 0x92,
+// 	WRITE_EXTENDED_ADDRESS: 0x93
+// }
+
+export const H_COMMANDS = {
+	DISABLE_CLOCK_DIVIDE_BY_FIVE: 0x8A,
+	ENABLE_CLOCK_DIVIDE_BY_FIVE: 0x8B,
+
+	ENABLE_THREE_PHASE_CLOCKING: 0x8C,
+	DISABLE_THREE_PHASE_CLOCKING: 0x8D,
+
+	// CLOCK_N_BITS_NO_TRANSFER: 0x8E,
+	// CLOCK_N_EIGHT_BITS_NO_TRANSFER: 0x8F,
+
+	// CLOCK_WAIT_IO_HIGH: 0x94,
+	// CLOCK_WAIT_IO_LOW: 0x95,
+
+	ENABLE_ADAPTIVE_CLOCKING: 0x96,
+	DISABLE_ADAPTIVE_CLOCKING: 0x97,
+
+	// CLOCK_N_BITS_NO_TRANSFER_OR_UNTIL_HIGH: 0x9C,
+	// CLOCK_N_EIGHT_BITS_NO_TRANSFER_OR_UNTIL_LOW: 0x9D
+}
+
+export const FT232H_ONLY_COMMANDS = {
+	SET_IO_ONLY_DRIVE_LOW: 0x9E
+}

package/src/mpsse/index.ts

@@ -0,0 +1,6 @@
+/** biome-ignore-all lint/performance/noBarrelFile: barrel */
+/** biome-ignore-all lint/performance/noReExportAll: barrel */
+export * from './clock.ts'
+export * from './command.ts'
+export * from './mpsse.ts'
+export * from './mpsse-template.ts'

package/src/mpsse/mpsse-template.ts

@@ -0,0 +1,96 @@
+/** biome-ignore-all lint/style/useConsistentArrayType: <explanation> */
+import {
+	CLOCK_DIVISOR_COMMANDS,
+	FT232H_ONLY_COMMANDS,
+	H_COMMANDS,
+	LOOPBACK_COMMANDS,
+	PIN_STATE_COMMANDS,
+	type ShiftCommand
+} from './command.ts'
+
+
+export class MPSSETemplate {
+	static shiftOutByte(command: ShiftCommand, length: number, data: number): Array<number> {
+		const lengthL = (length - 1) & 0x0F
+		const lengthH = ((length - 1) & 0xF0) >> 8
+		return [ command, lengthL, lengthH, data ]
+	}
+
+	static shiftInByte(command: ShiftCommand, length: number): Array<number> {
+		const lengthL = (length - 1) & 0x0F
+		const lengthH = ((length - 1) & 0xF0) >> 8
+		return [ command, lengthL, lengthH ]
+	}
+
+	static shiftOutBits(command: ShiftCommand, length: number, data: number): Array<number> {
+		return [ command, length - 1, data ]
+	}
+
+	static shiftInBits(command: ShiftCommand, length: number): Array<number> {
+		return [ command, length - 1 ]
+	}
+
+	static gpioSetHigh(pins: number, directions: number): Array<number> {
+		return [
+			PIN_STATE_COMMANDS.SET_DATA_BITS_HIGH_BYTE,
+			pins,
+			directions
+		]
+	}
+
+	static gpioSetLow(pins: number, directions: number): Array<number> {
+		return [
+			PIN_STATE_COMMANDS.SET_DATA_BITS_LOW_BYTE,
+			pins,
+			directions
+		]
+	}
+
+	static gpioGetHigh(): Array<number> {
+		return [ PIN_STATE_COMMANDS.READ_DATA_BITS_HIGH_BYTE ]
+	}
+
+	static gpioGetLow(): Array<number> {
+		return [ PIN_STATE_COMMANDS.READ_DATA_BITS_LOW_BYTE ]
+	}
+
+	static setClockDivisor(divider: number): Array<number> {
+		const divisorL = divider & 0xFF
+		const divisorH = (divider >> 8) & 0xFF
+
+		return [
+			CLOCK_DIVISOR_COMMANDS.SET_CLK_DIVISOR,
+			divisorL,
+			divisorH
+		]
+	}
+
+	static enableLoopback(enable = true): Array<number> {
+		if(enable) { return [ LOOPBACK_COMMANDS.ENABLED ] }
+		return [ LOOPBACK_COMMANDS.DISABLE ]
+	}
+
+	static enableClockDivideBy5(enable = true): Array<number> {
+		if(enable) { return [ H_COMMANDS.ENABLE_CLOCK_DIVIDE_BY_FIVE ] }
+		return [ H_COMMANDS.DISABLE_CLOCK_DIVIDE_BY_FIVE]
+	}
+
+	static enableThreePhaseClocking(enable = true): Array<number> {
+		if(enable) { return [ H_COMMANDS.ENABLE_THREE_PHASE_CLOCKING ] }
+		return [ H_COMMANDS.DISABLE_THREE_PHASE_CLOCKING ]
+	}
+
+	static enableAdaptiveClocking(enable = true): Array<number> {
+		if(enable) { return [ H_COMMANDS.ENABLE_ADAPTIVE_CLOCKING ] }
+		return [ H_COMMANDS.DISABLE_ADAPTIVE_CLOCKING ]
+	}
+
+	static setDriveOnlyZero(pinsLow: number, pinsHigh: number): Array<number> {
+		return [
+			FT232H_ONLY_COMMANDS.SET_IO_ONLY_DRIVE_LOW,
+			pinsLow,
+			pinsHigh
+		]
+	}
+}
+

package/src/mpsse/mpsse.ts

@@ -0,0 +1,95 @@
+/** biome-ignore-all lint/style/useConsistentArrayType: <explanation> */
+import type { FTDIDevice } from '../ftdi.ts'
+import { Util } from '../util.ts'
+import { BAD_COMMAND, BAD_COMMAND_RESPONSE } from './command.ts'
+import { MPSSETemplate } from './mpsse-template.ts'
+
+export class MPSSE {
+	readonly #device: FTDIDevice
+
+	constructor(device: FTDIDevice) {
+		this.#device = device
+	}
+
+	async executeCommands(commands: Array<number>|number): Promise<void> {
+		const cmdList = Array.isArray(commands) ? commands : [ commands ]
+		const flatCmdList = cmdList.flat()
+		await this.#device.sendData(Uint8Array.from(flatCmdList))
+	}
+
+	async validateMPSSE(command = BAD_COMMAND): Promise<boolean> {
+		await this.executeCommands(command)
+		const response = await Util.pollData(this.#device).catch(() => undefined)
+
+		if(response === undefined) { return false }
+		const [ first, second ] = response
+		if(first !== BAD_COMMAND_RESPONSE) { return false }
+		if(second !== command) { return false }
+		return true
+	}
+
+	async setGpioHigh(pins: number, directions: number): Promise<void> {
+		const command = MPSSETemplate.gpioSetHigh(pins, directions)
+		return this.executeCommands(command)
+	}
+
+	async setGpioLow(pins: number, directions: number): Promise<void> {
+		const command = MPSSETemplate.gpioSetLow(pins, directions)
+		return this.executeCommands(command)
+	}
+
+	async getGpioHigh(): Promise<void> {
+		const command = MPSSETemplate.gpioGetHigh()
+		return this.executeCommands(command)
+	}
+
+	async getGpioLow(): Promise<void> {
+		const command = MPSSETemplate.gpioGetLow()
+		return this.executeCommands(command)
+	}
+
+
+	async setClockDivisor(divider: number): Promise<void> {
+		const command = MPSSETemplate.setClockDivisor(divider)
+		return this.executeCommands(command)
+	}
+
+	// async waitIOHigh(): Promise<void> {s
+
+	// async waitIOLow(): Promise<void> {
+	// }
+
+	async enableClockDivideBy5(enable = true): Promise<void> {
+		const command = MPSSETemplate.enableClockDivideBy5(enable)
+		return this.executeCommands(command)
+	}
+
+	async enableThreePhaseClocking(enable = true): Promise<void> {
+		const command = MPSSETemplate.enableThreePhaseClocking(enable)
+		return this.executeCommands(command)
+	}
+
+	// async clcokWaitIOHigh(): Promise<void> {
+	// }
+
+	// async clockWaitIOLow(): Promise<void> {
+	// }
+
+	async enableAdaptiveClocking(enable = true): Promise<void> {
+		const command = MPSSETemplate.enableAdaptiveClocking(enable)
+		return this.executeCommands(command)
+	}
+
+	// async clockBitsNoTransferOrUntilHigh(): Promise<void> {
+	// }
+
+	// async clockByteNoTransferOrUntilLow(): Promise<void> {
+	// }
+
+	async setDriveOnlyZero(pinsLow: number, pinsHigh: number): Promise<void> {
+		const command = MPSSETemplate.setDriveOnlyZero(pinsLow, pinsHigh)
+		return this.executeCommands(command)
+	}
+}
+
+

package/src/status.ts

@@ -0,0 +1,94 @@
+
+export const STATUS_PREFIX_LENGTH = 2
+
+export const MODEM_STATUS_CLEAR_TO_SEND = 0x10
+export const MODEM_STATUS_DATA_SET_READY = 0x20
+export const MODEM_STATUS_RING_INDICATOR = 0x40
+export const MODEM_STATUS_DATA_CARRIER_DETECT = 0x80
+
+
+export const LINE_STATUS_DATA_READY = 0x01
+export const LINE_STATUS_OVERRUN_ERROR = 0x02
+export const LINE_STATUS_PARITY_ERROR = 0x04
+export const LINE_STATUS_FRAMING_ERROR = 0x08
+export const LINE_STATUS_BREAK_INTERRUPT = 0x10
+export const LINE_STATUS_TX_HOLDING_EMPTY = 0x20
+export const LINE_STATUS_TX_EMPTY = 0x40
+export const LINE_STATUS_RECEIVER_ERROR = 0x80
+
+
+export interface DeviceModemStatus {
+	data: number
+	isClearToSend: boolean
+	isDataSetReady: boolean
+	isRing: boolean
+	isCarrierDetect: boolean
+}
+
+export interface DeviceLineStatus {
+	data: number
+	isDataReady: boolean
+	isOverrunError: boolean
+	isParityError: boolean
+	isFramingError: boolean
+	isInterrupt: boolean
+	isTXHoldingEmpty: boolean
+	isTXEmpty: boolean
+	isReceiverError: boolean
+}
+
+export interface DeviceStatusInfo {
+	modem: DeviceModemStatus,
+	line: DeviceLineStatus
+}
+
+
+export class DeviceStatus {
+	static parse(data: BufferSource): DeviceStatusInfo|undefined {
+		const u8 = ArrayBuffer.isView(data) ?
+			new Uint8Array(data.buffer, data.byteOffset, STATUS_PREFIX_LENGTH) :
+			new Uint16Array(data, 0, STATUS_PREFIX_LENGTH)
+
+		const [ modemStatus, lineStatus ] = u8
+
+		if(modemStatus === undefined) { return undefined }
+		if(lineStatus === undefined) { return undefined }
+
+		//
+		const isClearToSend = (modemStatus & MODEM_STATUS_CLEAR_TO_SEND) !== 0
+		const isDataSetReady = (modemStatus & MODEM_STATUS_DATA_SET_READY) !== 0
+		const isRing = (modemStatus & MODEM_STATUS_RING_INDICATOR) !== 0
+		const isCarrierDetect = (modemStatus & MODEM_STATUS_DATA_CARRIER_DETECT) !== 0
+
+		//
+		const isDataReady = (lineStatus & LINE_STATUS_DATA_READY) !== 0
+		const isOverrunError = (lineStatus & LINE_STATUS_OVERRUN_ERROR) !== 0
+		const isParityError = (lineStatus & LINE_STATUS_PARITY_ERROR) !== 0
+		const isFramingError = (lineStatus & LINE_STATUS_FRAMING_ERROR) !== 0
+		const isInterrupt = (lineStatus & LINE_STATUS_BREAK_INTERRUPT) !== 0
+		const isTXHoldingEmpty = (lineStatus & LINE_STATUS_TX_HOLDING_EMPTY) !== 0
+		const isTXEmpty = (lineStatus & LINE_STATUS_TX_EMPTY) !== 0
+		const isReceiverError = (lineStatus & LINE_STATUS_RECEIVER_ERROR) !== 0
+
+		return {
+			modem: {
+				data: modemStatus,
+				isClearToSend,
+				isDataSetReady,
+				isRing,
+				isCarrierDetect,
+			},
+			line: {
+				data: lineStatus,
+				isDataReady,
+				isOverrunError,
+				isParityError,
+				isFramingError,
+				isInterrupt,
+				isTXHoldingEmpty,
+				isTXEmpty,
+				isReceiverError
+			}
+		}
+	}
+}

package/src/util.ts

@@ -0,0 +1,72 @@
+/** biome-ignore-all lint/performance/noAwaitInLoops: <explanation> */
+/** biome-ignore-all lint/style/useConsistentArrayType: <explanation> */
+import type { FTDIDevice } from "./ftdi.ts"
+import { STATUS_PREFIX_LENGTH } from "./status.ts"
+
+export interface ChipInfo {
+	major: number
+	minor: number
+	name: string
+
+	mpsse?: boolean
+	cbus?: boolean
+	driveZero?: boolean
+
+	eepromSize?: number
+}
+
+export const USB_MAJOR_TYPE_BM = 4
+export const USB_MAJOR_TYPE_2232C = 5
+export const USB_MAJOR_TYPE_R = 6
+export const USB_MAJOR_TYPE_2232H = 7
+export const USB_MAJOR_TYPE_4232H = 8
+export const USB_MAJOR_TYPE_232H = 9
+
+export const CHIP_INFO: Array<ChipInfo> = [
+	// FT8U232AM FT8U245AM // AM Series 1st gen
+	// FT245BM FT232BL FT232BQ FT245BL // BM Series 2nd gen
+	// FT2232C FT2232D
+	// FT4222H // Hi-Speed Quad SPI/I2C Bridge
+	// FT600Q / FT601Q / FT602Q
+	{ major: 0x02, minor: 0, name: 'FT232AM' }, // 1st gen
+	{ major: 0x04, minor: 0, name: 'FT232BM', eepromSize: 64 }, // 2nd gen
+	{ major: 0x05, minor: 0, name: 'FT2232C', mpsse: true },
+	{ major: 0x06, minor: 0, name: 'FT232R', eepromSize: 64, cbus: true },
+	{ major: 0x07, minor: 0, name: 'FT2232H', mpsse: true }, // Dual Channel UART/FIFO/MPSSE
+	{ major: 0x08, minor: 0, name: 'FT4232H', mpsse: true }, // Quad Channel UART/FIFO/MPSSE
+	{ major: 0x09, minor: 0, name: 'FT232H', eepromSize: 128, mpsse: true, driveZero: true, cbus: true }, // Single Channel UART/FIFO/MPSSE
+	{ major: 0x10, minor: 0, name: 'FT-X', cbus: true },
+	{ major: 0x20, minor: 0, name: 'FT2233HP' }, // Dual Channel Type-C + Power Delivery
+	{ major: 0x28, minor: 0, name: 'FT2233HP' },
+	{ major: 0x29, minor: 0, name: 'FT4233HP' }, // Quad Channel Type-C + Power Delivery
+	{ major: 0x30, minor: 0, name: 'FT2232HP' }, // Dual Channel Type-C + Power Delivery
+	{ major: 0x31, minor: 0, name: 'FT4232HP', mpsse: true }, // Quad Channel Type-C + Power Delivery
+	{ major: 0x32, minor: 0, name: 'FT233HP' }, // Single Channel Type-C + Power Delivery
+	{ major: 0x33, minor: 0, name: 'FT232HP' }, // Single Channel Type-C + Power Delivery
+	{ major: 0x36, minor: 0, name: 'FT4232HA', mpsse: true }, // Automotive Grade Quad UART
+]
+
+
+export const DEFAULT_DATA_READ_SIZE = 64
+export const DEFAULT_MAX_POLL_ATTEMPTS = 5
+
+export class Util {
+	static chip(major: number, minor: number): ChipInfo | undefined {
+		const info = CHIP_INFO.find(ci => ci.major === major && ci.minor === minor)
+		if(info === undefined) { return undefined }
+		return info
+	}
+
+	static async pollData(device: FTDIDevice, attempts = DEFAULT_MAX_POLL_ATTEMPTS): Promise<Uint8Array<ArrayBuffer>> {
+		for(let i = 0; i < attempts; i += 1) {
+			const response = await device.readData(DEFAULT_DATA_READ_SIZE)
+			if(response.byteLength === STATUS_PREFIX_LENGTH) { continue }
+			if(response === undefined) { throw new Error('no response') }
+			// const status = DeviceStatus.parse(response)
+			// console.log('attempts', i)
+			return new Uint8Array(response.buffer, STATUS_PREFIX_LENGTH)
+		}
+
+		throw new Error('no valid data acquired')
+	}
+}