Skip to content

Latest commit

 

History

History
460 lines (270 loc) · 12.8 KB

driver.md

File metadata and controls

460 lines (270 loc) · 12.8 KB
Raw

@jprayner/piconet-nodejs / Modules / driver

Module: driver

Table of contents

Type Aliases

Functions

Type Aliases

EventMatcher

Ƭ EventMatcher: (event: EconetEvent) => boolean

Type declaration

▸ (event): boolean

Use to filter events from the Econet driver.

Parameters
Name Type
event EconetEvent
Returns

boolean

Defined in

driver/index.ts:32

EventQueue

Ƭ EventQueue: Object

Holds an ordered set of events.

Type declaration

Name Type
events EconetEvent[]
listener Listener

Defined in

driver/index.ts:37

Listener

Ƭ Listener: (event: EconetEvent) => void

Type declaration

▸ (event): void

Used to register a listener for events from the Econet driver.

Parameters
Name Type
event EconetEvent
Returns

void

Defined in

driver/index.ts:27

Functions

addListener

▸ addListener(listener): void

Adds a new listener for events generated by the board.

Parameters

Name Type Description
listener Listener The listener to add.

Returns

void

Defined in

driver/index.ts:277

close

▸ close(): Promise<void>

Disconnects from the board and closes the serial port.

Returns

Promise<void>

Defined in

driver/index.ts:264

connect

▸ connect(requestedDevice?): Promise<void>

Connect the driver to the Piconet board.

This function must be successfully called before interacting with the Econet driver. The following steps are carried out:

  1. Open a serial connection to the board. If requestedDevice is not specified then an attempt will be made to autodetect it. This step may fail if the board is not connected or another application is using it.
  2. The driver will then send a STATUS command to the board. This step may fail if the Raspberry Pi Pico has not been flashed with correct firmware (.uf2 image).
  3. The driver will then compare the firmware version returned by the board against that of the driver using semantic versioning. If the versions are not compatible then an error will be thrown.

After connecting, the board will be in the STOP operating mode. Remember to call setMode to start it doing useful work.

Parameters

Name Type Description
requestedDevice? string Optionally specifies the serial device for the Raspberry Pi Pico on the Piconet board. If left undefined then an attempt will be made to automatically detect it.

Returns

Promise<void>

Defined in

driver/index.ts:76

eventQueueCreate

▸ eventQueueCreate(matcher): EventQueue

Creates an event queue to store all events matching the specified criteria, ready for collection at the caller's convenience.

The queue should be destroyed using eventQueueDestroy when it is no longer needed to avoid consuming memory unnecessarily.

Parameters

Name Type Description
matcher EventMatcher Specifies which events should be stored in the queue.

Returns

EventQueue

A queue object which can be passed to the other eventQueueXXX functions.

Defined in

driver/index.ts:343

eventQueueDestroy

▸ eventQueueDestroy(queue): void

Removes all events from queue and removes listener, preventing new events from being added.

Parameters

Name Type Description
queue EventQueue The queue to destroy.

Returns

void

Defined in

driver/index.ts:364

eventQueueShift

▸ eventQueueShift(queue): undefined | EconetEvent

Removes an event from the queue, if one is available. Otherwise returns undefined.

Parameters

Name Type Description
queue EventQueue Queue to shift from.

Returns

undefined | EconetEvent

Defined in

driver/index.ts:398

eventQueueWait

▸ eventQueueWait(queue, timeoutMs): Promise<EconetEvent>

Waits for a matching event with a timeout, removing it from the queue.

If no matching event is found within the specified timeout then an error is thrown.

Parameters

Name Type Description
queue EventQueue The queue to wait on.
timeoutMs number Maximum time to wait for a matching event in milliseconds.

Returns

Promise<EconetEvent>

Defined in

driver/index.ts:377

readStatus

▸ readStatus(): Promise<StatusEvent>

Queries the current status of the board.

Returns

Promise<StatusEvent>

The current status of the board.

Defined in

driver/index.ts:409

removeListener

▸ removeListener(listener): void

Removes a listener previously registered with addListener.

Parameters

Name Type Description
listener Listener The listener to remove.

Returns

void

Defined in

driver/index.ts:288

setDebugEnabled

▸ setDebugEnabled(enabled): void

Enables/disables driver debug logging. When enabled, shows the raw data passing between the driver and the board.

Parameters

Name Type
enabled boolean

Returns

void

Defined in

driver/index.ts:175

setEconetStation

▸ setEconetStation(station): Promise<void>

Sets the Econet station number for the board so that it knows which received frames to generate events for and how to populate the "from address" of outbound frames.

The station number should be unique on the Econet network.

Parameters

Name Type Description
station number The new Econet station number (an integer in range 1-254, inclusive).

Returns

Promise<void>

Defined in

driver/index.ts:156

setMode

▸ setMode(mode): Promise<void>

Puts the board into a new operating mode.

The board can be in one of three operating modes:

  • STOP - The board starts in this mode. No events are generated in response to network traffic, allowing the client to initialise configuration before proceeding.

  • LISTEN - The normal Econet station operating mode. The board generates events for broadcast frames or frames targeting the configured local Econet station number. You should normally set the station number before entering this mode: see setEconetStation.

  • MONITOR - The board generates an event for every frame received, regardless of its source or destination (promiscuous mode). Useful for capturing traffic between other stations like the BBC NETMON utility. A code example is provided for how to build such a utility.

Parameters

Name Type Description
mode "MONITOR" | "STOP" | "LISTEN" The new operating mode.

Returns

Promise<void>

Defined in

driver/index.ts:124

transmit

▸ transmit(station, network, controlByte, port, data, extraScoutData?): Promise<TxResultEvent>

Implements an Econet TRANSMIT operation.

This consists of a "four-way handshake":

  1. A "scout" frame sent from the board to the destination station. This includes a controlByte and port which are used by the receiver to identify the type of data being sent.
  2. Assuming the receiver is (a) connected to the network and listening for traffic and (b) is configured to handle the controlByte/port, it responds with a "scout ack" frame instructing the caller to proceed.
  3. The board sends a frame containing the payload data to the destination station.
  4. The receiver responds with a "data ack" frame confirming receipt of the data.

Parameters

Name Type Description
station number Destination Econet station number (integer in range 1-254, inclusive).
network number Destination Econet network number (0 for local network; only use other values if you have an appropriately configured Econet bridge).
controlByte number Econet control byte (integer in range 0-255, inclusive).
port number Econet port number (integer in range 0-255, inclusive).
data Buffer Buffer containing binary payload data to send.
extraScoutData? Buffer Optional extra data to include in the scout frame. This is useful for a small number of special operations such as NOTIFY.

Returns

Promise<TxResultEvent>

Describes the result of the operation. If the operation was successful then the success flag is set to true; otherwise the description field describes the error.

Defined in

driver/index.ts:205

waitForEvent

▸ waitForEvent(matcher, timeoutMs): Promise<EconetEvent>

Waits for a matching event with a timeout.

Parameters

Name Type Description
matcher EventMatcher A function that returns true if the passed event matches the required criteria.
timeoutMs number Maximum time to wait for a matching event in milliseconds. If no matching event is found within this period then the promise is rejected.

Returns

Promise<EconetEvent>

The matching event.

Defined in

driver/index.ts:305