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
orSerialStenotypeBase
depending on the type of protocol you want to implement.New machine implementations must define
KEYS_LAYOUT
andACTIONS
.- 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 thearpeggiate
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 writeTX 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 fromACTIONS
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 fromKEYS_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(steno_keys: List[str])#
Notifies the engine that a stroke was sent by the machine.
- _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 usesplover.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_INITIALIZING#
The value of
state
when the machine is attempting to connect.
- 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
andstop_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
andstop_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.