New Bindings interface

[reconbot]

💥 Proposal

The current binding interface is a result of 8 years of slight modifications. It works pretty good but I have idea for a different interface. This would be internal and the @serialport/stream interface would go mostly unchanged.

What feature you'd like to see

Fewer functions, an async factory, less state.

Motivation

I'd like our binding interface to good enough to replace the current proposed web serial spec and provide an easy to use api that can be wrapped by whatever the latest stream or iterator, approach

I also want the port to have all the info about the port already on it. This needs some thinking through for non exclusive ports (eg open by more than one processes) but that is a much less common use case.

Pitch

import { openPort, listPorts } from '@serialport/bindings'

const ports = await listPorts() /[ { path: '/dev/tty-usb' , vendorId: 'foobar' }]

const path = ports[0].path // '/dev/tty-usb'

const port = await openPort({ path, baudRate: 9600 })

port.baudRate // 9600
port.vendorId  // foobar
port.dtr // true or false
port.descriptor // open file descriptor, can be passed to child processes on linux and used to pass ports around context like to a service worker?

// and then the very similar to what we have now
const data = await port.read()
await port.write(data)

// combine set and update to just an update
await port.udate({ dtr: false, baudRate: 14400, rts: true })

// have port.getState() only return the stuff that is remote state, like cts, dcd, and dsr
const { cts } = await port.getState()

// rejects all pending writes and ends all pending reads with any available data (0 byte buffers or null for no data?)
await port.close()

[reconbot]

Here is the new API I've settled on. It has an AbstractBinding.open() method which returns an open port. The port as the path, vendor information and all local state as properties. Remote state (CTS, DSR, DCD) is now wrapped in a call to getRemoteState(). To change local state you call setLocalState() for anything you could control locally.

TODO

• Figure out what can have default values when you open() a port.
• ensure inflight reads when a port closes makes sense
• think about how events for remote state changes might work, this would need a lot of c++ work but it's a wonderful future feature and should be in the web spec if possible
• get feedback from Need prototype implementation WICG/serial#18

You can track my progress on the typescript2 branch.

/**
 * You never have to use `Binding` objects directly. SerialPort uses them to access the underlying hardware. This documentation is geared towards people who are making bindings for different platforms. 
*/
export class AbstractBinding implements PortInfo, LocalState {
  locationId?: string
  manufacturer?: string
  path: string
  pnpId?: string
  productId?: string
  serialNumber?: string
  vendorId?: string
  baudRate: number
  brk: boolean
  dataBits: 5 | 6 | 7 | 8
  dtr: boolean
  lock: boolean
  parity: 'none' | 'even' | 'mark' | 'odd' | 'space'
  rts: boolean
  rtscts: boolean
  stopBits: 1 | 1.5 | 2
  descriptor: number
  hasClosed: boolean

  /**
   * Retrieves a list of available serial ports with metadata. The `comName` must be guaranteed, and all other fields should be undefined if unavailable. The `comName` is either the path or an identifier (eg `COM1`) used to open the serialport.
   */
  static async list(): Promise<ReadonlyArray<PortInfo>> {
    throw new Error('#list is not implemented')
  }

  /**
   * Opens a connection to the serial port referenced by the path.
   */
  static async open<T>(this: T, options: OpenOptions): Promise<T> {
    throw new Error('#open is not implemented')
  }

  constructor(opt: ConstructorOptions) {
    throw new Error('Cannot create an AbstractBinding Implemented')
  }

  /**
   * Closes an open connection
   */
  async close() {
    throw new Error('.close is not implemented')
  }

  /**
   * Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns.
   */
  async drain() {
    throw new Error('.drain is not implemented')
  }

  /**
   * Flush (discard) data received but not read, and written but not transmitted.
   */
  async flush() {
    throw new Error('.flush is not implemented')
  }

  /**
   * Get the remote state flags (CTS, DSR, DCD) on the open port.
   */
  async getRemoteState(): Promise<RemoteState> {
    throw new Error('.get is not implemented')
  }

  /**
   * Request a number of bytes from the SerialPort. This function is similar to Node's [`fs.read`](http://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) except it will always read at least one byte while the port is open. In progress reads must resolve with any available data when the port is closed, if there is no data when a port is closed read 0 bytes.
   */
  async read(buffer: Buffer, offset: number, length: number): Promise<number> {
    throw new Error('.read is not implemented')
  }

  /**
   * Set local state on an open port including updating baudRate and control flags. The state is represented on the object as well as resolved in the promise.
   */
  async setLocalState(options: Partial<LocalState>): Promise<LocalState> {
    throw new Error('.setLocalState is not implemented')
  }

  /**
   * Write bytes to the SerialPort. Only call when there is no pending write operation. In progress writes must error when the port is closed.
   */
  async write(buffer: Buffer): Promise<void> {
    throw new Error('.write is not implemented')
  }
}

export interface ConstructorOptions extends PortInfo, LocalState {
  readonly descriptor: number
}

export interface OpenOptions extends LocalState {
  readonly path: string
}

export interface PortInfo {
  readonly path: string
  readonly locationId?: string
  readonly manufacturer?: string
  readonly pnpId?: string
  readonly productId?: string
  readonly serialNumber?: string
  readonly vendorId?: string
}

export interface LocalState {
  /* The system reported baud rate */
  readonly baudRate: number
  /* Break Suspends character transmission local status */
  readonly brk: boolean
  readonly dataBits: 5 | 6 | 7 | 8
  /* Data terminal Ready local status (local DTR => remote DSR) */
  readonly dtr: boolean
  readonly lock: boolean
  readonly parity: 'none' | 'even' | 'mark' | 'odd' | 'space'
  /* Request To Send local status (local RTS => remote CTS) */
  readonly rts: boolean
  /* enable rts/cts control flow, disables manually setting rts */
  readonly rtscts: boolean
  readonly stopBits: 1 | 1.5 | 2
}

export interface RemoteState {
  /* Clear To Send remote status (remote RTS => local CTS) */
  readonly cts: boolean
  /* Data Carrier Detect remote status */
  readonly dcd: boolean
  /* Data Set Ready remote status (local DSR => remote DTR) */
  readonly dsr: boolean
}

[HipsterBrown]

@reconbot Is this going to be a major version bump for the existing @serialport/bindings package or an underlying architecture change for serialport?

[HipsterBrown]

Also, I like the use of typings to describe the interface. It's a great documentation format.

[reconbot]

Both for sure.

…

On Fri, Oct 26, 2018, 1:59 PM Nick Hehr ***@***.***> wrote: Also, I like the use of typings to describe the interface. It's a great documentation format. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1679 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABlbrtpBg10KxVdR7hb0YsPIbQxJZTEks5uo01wgaJpZM4W1jsf> .

[reconbot]

having worked a little with pyserial today I realized that if you're not streaming data node-serialport is really annoying to work with. pyserial's read() takes a timeout and can return nothing. The proposed read here just waits for data and can't be canceled. We need one or the other or both in a safe way 🤔

[JBtje]

having worked a little with pyserial today I realized that if you're not streaming data node-serialport is really annoying to work with. pyserial's read() takes a timeout and can return nothing. The proposed read here just waits for data and can't be canceled. We need one or the other or both in a safe way 🤔

Amen... but luckely you guys helped out allot! (see #1758) and with that, using node-serialport all of the sudden becomes quite simple....

[shenzhuxi]

As I understand, https://github.com/serialport/bindings-cpp/blob/27c1685158f300d00d07e9c2de3f8af415cc8ad2/lib/linux-list.ts is using udevadm and does not check the hierarchy with --attribute-walk
#2126 (comment).

@reconbot What do you think about https://github.com/MadLittleMods/node-usb-detection ? I feel it's a more mature solution.