Device driver development kit (DDK)¶
This is where the classes for the device driver development kit are defined. Parameters relative to every command are stored in Command (read-only, read-write, or write-only; mnemonic; maximum and minimum value, for example)
Then, the Commands are organized in Subsystems. The Subsystems may be nested, which is useful to organize large drivers or SCPI drivers.
A Protocol may be set on a Subsystem. The Protocol will handle the command, like, for example, formatting and sending a request to the hardware; parse the results; and send it back.
A simplified UML representation of a driver using the classes in this module is
- exception pyhard2.driver.HardwareError¶
Exception upon error returned from the hardware.
Use this exception for errors documented in the hardware manual.
- exception pyhard2.driver.DriverError¶
Exception occuring after an error in the software.
- class pyhard2.driver.Context(command, value=None, node=None)¶
Request to pass to a Protocol.
- reader¶
The value stored in command.reader.
- writer¶
The value stored in command.writer.
- value¶
The value to write, or None.
- node¶
The node on which to read or write, or None.
- subsystem¶
The Subsystem on which the command is defined.
- path¶
[Subsystem]
The list of subsystem traversed until the Protocol.
- append(subsystem)¶
Append to the path.
- class pyhard2.driver.Access¶
Enum for read-only, read-write, and write-only access.
- RO, WO, RW
- class pyhard2.driver.Command(reader, writer=None, minimum=None, maximum=None, access='Access.RW', rfunc=None, wfunc=None, doc=None)¶
Store information related to a Command.
Parameters: - reader (str or callable) – Mnemonic or command to read.
- writer (str or callable, optional) – Mnemonic or command to write. Default to reader.
- minimum (number, optional) – Minimum value used for data validation.
- maximum (number, optional) – Maximum value used for data validation. Values passed to the parameter exceeding minimum or maximum will be silently coerced to avoid hardware errors.
- rfunc (function, optional) – Convert on read.
- wfunc (function, optional) – Convert on write. These functions can be used either for type conversion (i.e., str to int) or for pretty printing. Do nothing by default.
- doc – docstring
- signal¶
value, node
Emit the value returned by read() and the node.
- Context¶
class Context
Nested Context class.
- class Context(command, value=None, node=None)
Context nested in Command to make derivable.
See Context.
- Command.read(node=None)¶
Request reading a value from node.
Returns: The value. Raises: DriverError – if trying to read a write-only command.
- Command.write(value=None, node=None)¶
Request writing value in node.
Raises: DriverError – when writing a read-only command or when the value is None for a write-only command.
- class pyhard2.driver.Subsystem(parent=None)¶
A logical group of one or more commands.
- __setattr__(name, value)¶
The subsystem takes the ownership of commands.
- protocol()¶
Return the protocol if one has been set.
- setProtocol(protocol)¶
Set the protocol to protocol.
- read(context)¶
Forward the read request.
Forward to the request to the Protocol if one has been set or to the Subsystem‘s parent otherwise.
Raises: AttributeError – if the Subsystem has neither parent nor Protocol.
- write(context)¶
Forward the write request.
Forward the request to the Protocol if one has been set or to the Subsystem‘s parent otherwise.
Raises: AttributeError – if the Subsystem has neither parent nor Protocol.
- class pyhard2.driver.Protocol(parent=None)¶
Protocols should derive this class.
- read(context)¶
Handle the read request.
- write(context)¶
Handle the write request.
- class pyhard2.driver.CommandCallerProtocol(parent=None)¶
Handle Commands with functions for reader and writer.
Example
>>> class Handled(object): ... ... def __init__(self): ... self._value = 0 ... ... def get_value(self): ... return self._value ... ... def set_value(self, value): ... self._value = value ... >>> handled = Handled() >>> driver = Subsystem() >>> driver.measure = Command(handled.get_value, handled.set_value) >>> driver.setProtocol(CommandCallerProtocol()) >>> driver.measure.read() # read handled._value 0 >>> driver.measure.write(10) # write handled._value = 10 >>> driver.measure.read() # read new handled._value 10 >>> handled._value # handled._value has changed 10
- read(context)¶
Return context.reader().
- write(context)¶
Call context.writer(context.value).
- class pyhard2.driver.ObjectWrapperProtocol(wrapped_obj, parent=None)¶
Get and set attributes on python objects.
Parameters: wrapped_obj – The nodes are copies of wrapped_obj. Note
The protocol makes one copy of wrapped_obj per node.
Example
>>> class Handled(object): ... ... def __init__(self): ... self.value = 0 ... >>> handled = Handled() >>> protocol = ObjectWrapperProtocol(handled) >>> driver = Subsystem() >>> driver.measure = Command("value") # reader is the attribute name >>> driver.setProtocol(protocol) >>> driver.measure.read(1) # read handled.value at node 1 0 >>> driver.measure.write(10, 1) # write handled.value = 10 >>> driver.measure.read(1) # read new handled.value 10 >>> protocol.node(1).value # read value directly 10
- node(node=None)¶
Return the actual object at node.
- read(context)¶
Get the attribute named context.reader at context.node.
- write(context)¶
Set the attribute named context.writer at context.node to context.value.
- class pyhard2.driver.CommunicationProtocol(socket, parent=None)¶
Protocols that communicate via a socket should derive this class and implement the read() and write() methods.
- pyhard2.driver.splitlines(txt, sep='\n')¶
Return a list of the lines in txt, breaking at sep.
- class pyhard2.driver.TesterSocket(*args, **kwargs)¶
A fake socket with canned responses, used for testing.
- msg¶
dict
map commands received by the socket to canned answers.
- newline¶
newline character.
- write(message)¶
Buffer the canned answer for message.
- read(n)¶
Return n characters from the buffer.
- readline()¶
Return one line in the buffer.
- inWaiting()¶
Return True is the buffer is not empty.