class labterm.dashboard.Dashboard(screen, data_update_interval: float = 0.3, data_update_workers: int = None, cycle: bool = True, header: str = '', show_time: bool = True, show_log: bool = True, show_controls: bool = True, controls_text: list[str] = None, grid_start: tuple[int, int] = (0, 0), max_log_messages: int = 6)

Bases: object

Curses dashboard that displays DashboardItem and polls Instrument.

The Dashboard runs a background thread to periodically call Instrument.update_data() and places new values into an internal queue that the main drawing loop consumes.

Parameters:

• screen – curses screen object supplied by curses.wrapper.

• data_update_interval (float) – In seconds, interval between instrument polls. More precisely, interval between the moment when the last instrument has updated and the next polling starts.

• data_update_workers (int) – The maximum number of instruments updating at the same time. Defaults to the maximum number of workers which can be assigned by the system.

• cycle (bool) – Whether the grid allows cycling, i.e. navigating between the first and the last element of a line/column.

• header (str) – A string continuously printed on the top left of the dashboard.

• show_time (bool) – Whether to show the current time on the top of the dashboard.

• show_log (bool) – Whether to show the last max_log_messages logs at the bottom of the dashboard.

• show_controls (bool) – Whether to show the controls help text (controls_text) in a section of the dashboard.

• controls_text (list[str] | None) – The text detailing the dashboard controls.

• grid_start (tuple[int,int]) – The position the item selector starts in at the launch of the program.

• max_log_messages (int) – Maximum number of log messages to be shown at once.

Variables:

• instruments (dict[int, Instrument]) – Instruments keyed by channel.

• items (list[DashboardItem]) – All dashboard items.

Notes

Threading / lifecycle:

• Dashboard.__init__ starts a daemon thread that runs _update_data_loop.

• run() is the main thread’s drawing loop; it consumes the data queue.

• update_data launches all the instrument data updates at once, and saves in the data queue the updates of each instrument, as they finish.

  Once all the instruments have been updated, after data_update_interval seconds another update is called for all instruments. Exceptions are caught and logged.

Examples

>>> def main(stdscr):
...     dash = Dashboard(stdscr, header="LabTerm example")
...     dash.add_instruments(MyInstrument(channel=0))
...     dash.add_items(MyDashboardItem(...))
...     dash.run()...
... if __name__ == '__main__':
...     import curses
...     curses.wrapper(main)

DEFAULT_CONTROLS = ['↑/↓/←/→ - Navigate items               i - Invert colors', 'Enter - Toggle switch / Edit value     Numbers - Enter values (when editing)', 'Esc - Cancel edit                      q - Quit']

add_instruments(*instruments: Instrument) → None

Add one or more instruments to the dashboard.

Each instrument is connected to the dashboard’s logger and registered by its channel ID. Instruments with duplicate channel IDs will overwrite previous ones.

Parameters:

*instruments – Variable number of Instrument instances to add.

add_items(*items: DashboardItem) → None

Add one or more dashboard items to the display.

Items are drawn in the order they are added. Navigable items form a grid based on their xgrid and ygrid coordinates.

Parameters:

*items – Variable number of DashboardItem instances to add.

cycle(cycle: bool = True)

Sets whether to cycle when at the end of the navigable grid or not.

run()

Main dashboard loop:

1 - Checks if the data queue contains updates for the values of the dashboard items, and applies the updates 2 - Clears the window 3 - Draws all the items, the decorators (header + instructions) and the logs 4 - Handles user input, separating between editing and navigation

set_header(header: str) → None

Sets the program header, printed on the top left.

set_max_logs(max_number: int) → None

Sets the maximum number of log messages displayed at once at the bottom of the screen

set_update_interval(interval: float) → None

Set every how many seconds the program gathers data from the instruments to update the dashboard

show_controls(show: bool) → None

Sets whether the dashboard controls are printed or not on the dashboard.

show_log(show: bool) → None

Sets whether the log messages are printed or not on the dashboard.