pyopticon.dashboard module

class pyopticon.dashboard.PyOpticonDashboard(dashboard_name, **kwargs)

Bases: object

A Dashboard is our term for a GUI window containing various ‘widgets’. A standalone program should initialize, configure, and run each dashboard. One dashboard may contain many widgets, each representing a physical device or some other functionality.

See the tutorials for examples of initializing and populating a dashboard. Generally, the workflow is to:

  • Initialize a dashboard

  • Initialize widgets and add them to the dashboard

  • Define any desired interlocks and add them to the dashboard

  • Launch the dashboard

Parameters:

  • dashboard_name (str) – The name of the dashboard, which appears in any data logging files that the dashboard creates.

  • offline_mode (bool, optional) – Defaults to False. If True, doesn’t attempt to build any serial.Serial objects, and widgets may also check to behave differently.

  • polling_interval_ms (int, optional) – The interval for polling all connected devices, in milliseconds. Defaults to 1000. You may want to use a larger interval if certain devices are slow to poll, or polling them involves blocking code (not recommended).

  • window_resizeable (bool, optional) – Whether or not you can manually resize the dashboard by dragging and dropping the corner. Defaults to false. If True, the window is resizeable, but the widgets don’t scale or center themselves.

  • persistent_console_logfile (bool, optional) – Whether or not to log console events to a persistent file (same throughout multiple dashboard relaunches) in the same directory as the dashboard initialization script.

  • print_stacktraces (bool, optional) – If true, exception stack traces are printed to console; if false, only to the logfile. Exception names are printed regardless.

  • x_pad (int, optional) – The horizontal pad between widgets, in pixels.

  • y_pad (int, optional) – The vertical pad between widgets, in pixels.

  • socket_ports (list, optional) – A list of integer ports on which to open sockets for client connections. Defaults to [12345].

  • include_auto_widget (bool, optional) – Whether or not to display an automation widget on the dashboard.

  • include_socket_widget (bool, optional) – Whether or not to display a socket widget on the dashboard.

add_widget(widget, row, column)

Add a widget to the dashboard at the specified row and column, each indexed from 0. Note that rows 0-3 in column 0 are reserved for the four dashboard control widgets. If the specified grid coordinates are already occupied, add_widget hides the widget that was there before. It warns to console if the widget added shares a name or nickname with an existing widget.

Parameters:
add_interlock(fn)

Add an interlock function that will be called once every polling cycle.

You’ll probably want to define such a function in the same file where the dashboard is constructed. You can use the dashboard’s get_field and/or get_widgets_by_nickname methods to check whether the system state violates a certain interlock condition (e.g., a certain temperature reading is too high), and then respond accordingly (e.g., use the dashboard’s set_field method to shut off the flow of reactive gases, or use the gmail_helper module to email or text the operator that something has gone wrong).

Parameters:

fn (function) – The interlock function to add. Should take no arguments and return nothing.

start()

Launch the dashboard, including all necessary threads.

exc_handler(exc, source='system', widget=None)

Handle an exception according to the protocol configured when the dashboard was launched. Generate a message about what subprocess raised the exception.

Parameters:

  • exc (Exception) – The Exception being raised

  • source (str, optional) – The source of the exception according to a scheme outlined in the if-statement in the function definition. Defaults to ‘system’.

  • widget (str, optional) – The nickname of the widget that raised the exception, if applicable

check_offline_mode()

Check whether dashboard is in offline mode.

Returns:

Whether the dashboard is in offline mode.

Return type:

bool

return self.offline_mode

check_serial_connected()

Check whether serial is currently connected

Returns:

Whether the dashboard’s serial is connected.

Return type:

bool

get_field(target_widget_nickname, target_field)

Get the current value of a certain field of a certain widget. The field must have been created with the add_field method of the GenericWidget class. To access an instance variable of a widget, use get_widget_by_nickname instead. To see a list of widgets’ nicknames and fields, run the dashboard and use the ‘automation help’ button.

Parameters:

  • target_widget_nickname (str) – The nickname of the widget

  • target_field (str) – The name of the field to read

Returns:

The value of the field that you queried

Return type:

str

set_field(target_widget_nickname, target_field, new_value, confirm=True)

Set the value of a certain field of a certain widget and, optionally, execute the widget’s confirm function. The field must have been created with the add_field method of the GenericWidget class. To modify an instance variable of a widget, use get_widget_by_nickname instead. To see a list of widgets’ nicknames and fields, run the dashboard and use the ‘automation help’ button.

Parameters:

  • target_widget_nickname (str) – The nickname of the widget

  • target_field (str) – The name of the field to modify

  • new_value (str) – The new value for the field. Fields’ values are always stored as strings, even if they represent numbers.

  • confirm (bool) – Whether or not to execute the widget’s confirm function, which usually sends a command to the physical device based on the newly updated field.

get_widget_by_nickname(nickname)

Get a certain widget based on its nickname. To see a list of widgets’ nicknames and fields, run the dashboard and use the ‘automation help’ button.

Parameters:

target_widget_nickname (str) – The nickname of the widget

Returns:

The corresponding widget

Return type:

pyopticon.generic_widget.GenericWidget or pyopticon.minimal_widget.MinimalWidget

get_widgets_by_nickname()

Get a dict that maps widgets’ nicknames to the corresponding widget objects. Widgets that were added with no or None nicknames are excluded.

Returns:

A dict mapping nicknames (str) to widgets (GenericWidget)

Return type:

dict

get_tkinter_object()

Get the dashboard’s Tkinter frame object, through which Tkinter functions like after() can be accessed.

Returns:

The dashboard’s Tkinter frame object.

Return type:

tkinter.Tk

scale_all_text(scale_factor)

Go through all the widgets and scale the font on any tkinter Label, Text, OptionMenu, or Button objects. Meant as a quick fix for using dashboards on smaller or larger screems.

Parameters:

scale_factor (float) – A factor by which to scale text, e.g. 1.2. Values are calculated in font units and are rounded to the nearest int.