`plover.machine` – Steno machine protocols#

This module provides functionality for interacting with steno machines and keyboards.

class plover.machine.base.StenotypeBase#

The base class for all steno machines. Do not use this directly; instead subclass either ThreadedStenotypeBase or SerialStenotypeBase depending on the type of protocol you want to implement.

New machine implementations must define KEYS_LAYOUT and ACTIONS.

KEYS_LAYOUT: str#

A human-readable representation of the arrangement of physical keys on the machine. For example, a conventional steno machine supporting exactly 23 keys should show key labels arranged in the standard steno layout:

#  #  #  #  #  #  #  #  #  #
S- T- P- H- * -F -P -L -T -D
S- K- W- R- * -R -B -G -S -Z
      A- O-   -E -U

Key labels may appear more than once within this string, since these are automatically removed when the keymap is created.

ACTIONS: Tuple[str]#

Any actions that this machine implements, in addition to the keys shown above. For example, the Keyboard machine supports the arpeggiate action to handle arpeggiating.

Do not include no-op as an action – this is automatically added.

KEYMAP_MACHINE_TYPE: str | None#

A fallback machine type to use for finding a compatible keymap if one is not already available for this machine type.

For example, a standard steno machine layout with one S- key and one * key may choose to fall back on the TX Bolt protocol for a keymap, since the layout is identical, so we would write TX Bolt here.

classmethod get_keys() → Tuple[str]#: Returns the keys this machine supports.

classmethod get_actions() → Tuple[str]#: Returns the non-key actions this machine supports.

keymap: plover.machine.keymap.Keymap#: The active keymap on this machine, which binds physical keys from KEYS_LAYOUT and actions from ACTIONS to steno keys in the current steno system.

set_keymap(keymap: plover.machine.keymap.Keymap)#: Sets the active keymap to keymap.

state: str#: The current connection state of the machine. This starts at STATE_STOPPED at initialization, but may transition into any of the other states throughout the lifetime of the machine.

add_state_callback(callback: Function[str])#: Adds callback to the list of functions called when the machine’s state changes. The state is passed in as one of the possible state values.

remove_state_callback(callback: Function[str])#: Removes callback from the list of functions called when the machine’s state changes.

add_stroke_callback(callback: Function[List[str]])#: Adds callback to the list of functions called when a stroke is sent from the machine. The stroke is represented as a list of the steno key labels from KEYS_LAYOUT.

remove_stroke_callback(callback: Function[List[str]])#: Removes callback from the list of functions called when a stroke is sent.

The following API is provided for machine implementors:

_notify_keys(steno_keys: List[str])#: Notifies the engine that a stroke was sent by the machine. steno_keys is a list of the physical steno keys that were pressed on the machine; this function automatically handles translating the keys to actions using the active keymap.

_notify(steno_keys: List[str])#

Notifies the engine that a stroke was sent by the machine. steno_keys is a list of actions and/or logical steno keys that exist on the steno system.

Deprecated: Use _notify_keys() instead.

_stopped()#: Changes the state of the machine to STATE_STOPPED.

_initializing()#: Changes the state of the machine to STATE_INITIALIZING.

_ready()#: Changes the state of the machine to STATE_RUNNING.

_error()#: Changes the state of the machine to STATE_ERROR.

Machine implementors should also implement the following:

classmethod get_option_info() → Dict[str, T, Function[str, T]]#

Returns a dictionary of configuration options, where the keys are option names, and the values consist of the default value for that option and a function to convert from the string representation to the correct type.

For example, the Boolean option arpeggiate might be represented as:

from plover.misc import boolean

class Keyboard(ThreadedStenotypeBase):
  @classmethod
  def get_option_info(cls):
    return {
      "arpeggiate": (False, boolean),
    }

which sets the default value to False, and uses plover.misc.boolean() to convert from a string to a Boolean value.

start_capture()#: The engine has started – implement this method to attempt to connect to a machine and start capturing strokes.

stop_capture()#: The engine is shutting down – implement this method to stop capturing strokes, and cleanly disconnect from a machine if needed.

plover.machine.base.STATE_STOPPED#: The value of state when the machine is not connected.

plover.machine.base.STATE_INITIALIZING#: The value of state when the machine is attempting to connect.

plover.machine.base.STATE_RUNNING#: The value of state when the machine has successfully connected.

plover.machine.base.STATE_ERROR#: The value of state when there is an error connecting to the machine.

In addition to the StenotypeBase class, this module also provides skeletons for implementing new machine types. Prefer to use these when possible.

class plover.machine.base.ThreadedStenotypeBase#

A machine listener that uses a thread to capture stroke data.

Override start_capture and stop_capture to implement connection and disconnection if needed.

run()#: Implement this method to handle receiving data from the machine, or leave it empty to use your own implementation.

class plover.machine.base.SerialStenotypeBase(serial_params: Dict[str, any])#

A machine listener for supporting machines using serial connections.

Override start_capture and stop_capture to implement connection and disconnection if needed.

SERIAL_PARAMS: Dict[str, any]#: The dictionary of parameters for serial connections and default values for each.

serial_params: Dict[str, any]#: The dictionary of parameters for the current serial connection. Not to be confused with SERIAL_PARAMS, which provides default values.

serial_port: serial.Serial#: A handle to the serial port that this listener is connected to.

run()#: Implement this method to handle receiving data from the machine, or leave it empty to use your own implementation.

The following helpers are also provided for implementing specific serial protocols:

_iter_packets(packet_size: int) → Generator[bytes]#: Yields packets of the specified size until the machine is stopped. Call this method to handle serial protocols with fixed-length packets.

_close_port()#: Closes the connection to the serial port. This is automatically called when stop_capture is called.

plover.machine – Steno machine protocols#

`plover.machine` – Steno machine protocols#