PdClient¶
The PdClient class provides access to the low-level RPC calls that can be made to the pdserver gateway.
Accessing unimplemented RPC methods¶
The purpledrop driver is under active development, and there may be RPC calls available which have not yet been added to the client, and are therefor not documented here. The client attribute on the PdClient object can be used to make arbitrary RPC calls by method name. For example, to call the RPC method named my_test_method with two arguments (a string and an int):
c = pdclient.PdClient(RPC_URL)
return_value = c.client.my_test_method('argument1', 2)
A full list of the available rpc methods can be seen by accessing the /rpc/map route on a running pdserver instance.
API Reference¶
-
class
pdclient.PdClient(host: str)[source]¶ A PdClient object provides the interface for accessing PurpleDrop via RPC calls
-
bulk_capacitance() → List[float][source]¶ Get the most recent scan of electrode capacitance
This function is deprecated, and may be removed in a future version. Use get_scan_capacitance instead.
-
calibrate_capacitance_offset()[source]¶ Trigger the re-calibration of the capacitance sense amplifier offset
Note: This calibrates for the zero-input integrator ramp rate. It is not a per-electrode offset calibration.
-
enable_pins(pins: Sequence[int], group_id: int = 0, duty_cycle: int = 255)[source]¶ Enable the specified set of electrodes by pin number
PurpleDrop supports two drive groups which can be driven independently, with different duty cycles. Adjusting the duty cycle is primarily used for feedback control performed on the device, but can be set remotely via RPC calls.
For most use cases, drive group 0 can be used exclusively. But when using feedback control, e.g. for drop splitting, pins for drive group 0 and drive group 1 must be setup prior to enabling feedback control.
Unused drive groups should be disabled by setting an empty pin list.
Parameters: - pins (-) – List of integers, giving pin numbers to enable
- group_id (-) – Drive group index
- duty_cycle (-) – On duty cycle to drive (0-255), 255 being max duty cycle, and 0 min
-
enable_positions(positions)[source]¶ Enable the specified set of electrodes by grid location
positions: List of 2-tuples of (x, y) electrode grid coordinates, e.g. [(0, 0), (0, 1), (1, 0), (1, 1)]
-
get_grid_location(pin: int) → Optional[Tuple[Tuple, int]][source]¶ Get the grid location for a pin number
Returns: ((x, y), grid_idx) if the pin is located, or None if the pin is not found in the grid definition
-
get_pin(location: Sequence[int], grid: int = 0) → int[source]¶ Get the electrode pin number from a grid location using the layout
location: (x, y) coordinate of the electrode to lookup grid: Index indicating which grid is to be used for a board with
multiple grids
-
grid(idx: int = 0) → pdclient.api_types.Grid[source]¶ Get one grid object from the electrode board definition
idx: Index indicating which grid to return for board with multiple grids
-
group_capacitance() → Dict[str, List[T]][source]¶ Get the most recent group capacitance measurements
Returns: dict containins the raw and calibrated values for all capacitance groups.
Example
- {
- “raw”: [10, 11, 400, 10, 9], “calibrated”: [0.0, 0.0, 2.9, 0.0, 0.0],
}
-
hv_supply_voltage() → float[source]¶ Get the latest voltage measurement for the high voltage supply rail
Returns a float, in volts.
-
move_drop(start: Sequence[int], size: Sequence[int], dir: str) → dict[source]¶ Executes a device controlled drop movement sequence
DEPECRATED: This method has been replaced buy the move_drops method, and may be removed in the future. Consider using the new method instead.
Parameters: - start – The x,y location of the drop initial position (e.g. [2, 3])
- size – The width and height of the drop (e.g. [2, 2])
- dir – One of [‘up’, ‘down’, ‘left’, ‘right’]
Returns: A dict containing the results of the drop movement, including a success flag and a time series of capacitance data captured during the move.
The return dict is of the form:
- {
“success”: bool, “closed_loop”: bool, “closed_loop_result”: {
”pre_capacitance”: float, “post_capacitance”: float, “time_series”: List[float], “capacitance_series”: List[float]
}
}
closed_loop_result is only present when “closed_loop” is true. It will always be true for devices that support capacitance sensing, but is present to allow devices without sensing to implement an open-loop move_drop function.
-
move_drops(move_commands: Sequence[Union[Dict[KT, VT], pdclient.api_types.MoveCommand]]) → List[dict][source]¶ Executes a device controlled move of drops
This command supports movement of up to 5 drops at a time – limited by the number of capacitance groups supported on the PurpleDrop – using capacitance feedback to determine when a move is completed.
Parameters: move_commands – A list of MoveCommand objects, one for each drop movement. Alternatively, a dict with the proper fields is accepted. Returns: A list of dict obections containing the results of each move command, including a success flag, and a time series of the capacitance data captured during the move which can be used to measure movement velocity. Each result object is of the form:
- {
- “success”: bool,
“closed_loop”: bool,
“closed_loop_result”: {”pre_capacitance”: float, “post_capacitance”: float, “time_series”: List[float], “capacitance_series”: List[float]
}
}
-
parameter_definitions() → dict[source]¶ Get the list of all parameters which can be set in the firmware
-
scan_capacitance() → Dict[str, List[T]][source]¶ Get the most recent capacitance scan result
Returns: capacitance scan data for all electrodes in the form of a dict containing two lists.
- {
- “raw”: List[float], “calibrated”: List[float]
}
-
set_capacitance_group(pins: Sequence[int], group_id: int, setting: int)[source]¶ Set configuration for a capacitance group
Purpledrop support 5 different group scans. Each group defines a set of electrodes which are measured together after each AC drive cycle. To disable a group, set the pins to an empty list.
Parameters: - pins (-) – A list of pins included in the group (may be empty to disable the group)
- group_id (-) – The group number to set (0-4)
- setting (-) – 0 - high gain, 1 - low gain
-
set_feedback_command(target, mode, input_groups_p_mask, input_groups_n_mask, baseline)[source]¶ Update feedback control settings
When enabled, the purpledrop controller will adjust the duty cycle of electrode drive groups based on capacitance measurements.
Parameters: - target (-) – The controller target in counts
- mode (-) –
- 0: Disabled
- 1: Normal
- 2: Differential
- input_groups_p_mask (-) – Bit mask indicating which capacitance groups to sum for positive input (e.g. for groups 0 and 2: 5)
- input_groups_n_mask (-) – Bit mask for negative input groups (used in differential mode)
- baseline (-) – The duty cycle to apply to both drive groups when no error signal is present (0-255)
-