mh5_ui reference

Main classes

class MainUI

class main_ui.MainUI

Main UI class that handles the views and switches between them.

The MainUI setups a SnackScreen, determines the size of the available screen and handles the main display loop that processes the hotkeys. An additional hot-key ‘q’ is provided to quit the loop and close the display.

__init__() → None

Initializes the UI. Allocates the SnackScreen, determines the width and height of the screen and initializes the views.

screen: snack.SnackScreen

The main screen of the UI. It is a SnackScreen.

w: int

The width of the screen.

h: int

The height of the screen.

views: Dict[str, snack.Widget]

The views in the UI. You can use add_view() to add them to this dictionary.

current_view: snack.Widget

The current view being shown.

done: bool

Controls the display loop. Will be initialized to False and will only be set to True by pressing the q hot-key.

add_view(view: snack.Widget, hot_key: str, default_view: bool = False) → None

Adds a view (page) to the dictionay of views. Views are held by their hotkey.

Parameters

• view (Widget or subclass) – The view (page) to be added. The view must be fully constructed and view_ui.View.run() must be possible to be executed on that object.

• hot_key (str) – The key associated with the view. The main loop will process keys and if they match one of these it will handle the switch to that particular view.

• default_view (bool, optional) – Marks this view as the default view which means the MainUI will use this to start displaying the interface when executing run() for the first time. When you add views to the MainUI the last one that uses the default_view will overwrite the other ones and that will be the one to be used. If no view is defined as default_view the MainUI will use the first item in the list of hot-keys. Because of the way the dictionaries work in Python this might not be the first view added. By default False

change_view(hotkey: str) → None

Changes a view to the one specified by the hot-key provided.

The method will ask the present view to view_ui.View.finish() then will popWindow() from the screen. It will assign the view represented in the dictionary by the hotkey to the current_view, it will ask to view_ui.View.setup(), and will setup the hot-keys from that view.

Parameters

hotkey (str) – The hot-key identifying that view.

run() → None

Runs the main loop of the UI. It will activate the default_view and then will execute a view_ui.View.run() for that view (which for shack means to wait for a key press) then handle the hotkeys by switching the views if they match the ones associated with the views or finish the loop if ‘q’ was pressed.

Supporting classes

class View

class view_ui.View(screen: snack.SnackScreen, timer: int, title: str)

Base class for a view.

grid: snack.GridForm

The view places all the elements into a snack.GridForm object of size 1 x 1. We use a GridForm because this is handling hotkeys and allows to define an automated timer to trigger the refresh of the content.

content: snack.Widget

Is the actual content of the view that is normally produced by invoking create_content().

__init__(screen: snack.SnackScreen, timer: int, title: str) → None

Initializes a new view.

A view uses a snack.GridForm as a canvas, that is pinned on the screen provided and displays a title.

The constructor only stores the screen, timer and title in the internal variables. You need to specifically call setup() to construct the view. setup() will call create_content() that normally needs to be overridden by subclasses to present a specific content.

Parameters

• screen (snack.SnackScreen) – The screen where the view will be positioned.

• timer (int) – Refresh time for view in milliseconds. This will trigger the update_content().

• title (str) – Title to be presented on the top of the view.

screen: snack.SnackScreen

The main screen where the view will be posted.

timer: int

The refresh timer (in milliseconds) that the view will use to update the content displayed.

title: str

The title of the view. It is diplayed at the top of the screen.

setup() → None

Builds the view content.

Must be called by the MainUi before starting the view. This creates all the objects of the UI and initializes them. Sets-up a GridForm of size 1x1 and calls create_content() to fill the specific content of the view. It also registers the hot keys as are reported by the hotkeys property that must be subclassed if the view needs to handle keys.

create_content() → snack.Widget

Should be implemented in subclasses to produce the desired view output.

Returns

A snack.Widget that will be included in the grid. Note that it should be one element only and if you need a more complex structure you need to use a GridForm or other classes to contain and structure the elements. Have a look at the implementation of RobotStatusView, CommsStatusView and JointView.

Return type

Widget

property hotkeys: List[str]

Returns the keys this view handles. If implemented by subclasses then also process_hotkey should be implemented.

update_content() → None

Handles updates to the content of the view. Normally these are triggered by the elapsed timer set up by the timer property. Should be implemented in the subclass according to the desired behavior.

process_hotkey(key: str) → None

Processes the declared hotkeys. Should be implemented in subclass.

Parameters

key (str) – The key to be processed.

run() → str

Performs a run() of the grid.

First calls the update_content() to trigger updates to the interface and refresh() on the screen object. After that it runs the run() of the grid object followed by process_key() method to process the hotkey pressed (if any) after which it returns the hot key to the caller program (typically the MainUI) so that the loop there can process it’s own hot keys.

Returns

The key pressed for the caller program to handle if necessary

Return type

str

finish() → None

Provides a way for the view to clear resources before being switched from. For instance views that are displaying information from ROS topics have the chance to unsubscribe from the topics here to save resources.

class NameValueScale

class view_ui.NameValueScale(name: str, unit: str, grid: snack.GridForm, row: int, widths: List[int], min_val: float, max_val: float)

A display element that includes a name for the object, a value (+ unit of measure if provided) and a Scale (a horizontal bar graph).

__init__(name: str, unit: str, grid: snack.GridForm, row: int, widths: List[int], min_val: float, max_val: float)

Creates a combined display element in one line with a name, a value and a horizontal bar graph.

Parameters

• name (str) – The name to be shown on the left side of the display.

• unit (str) – A string to be shown after the value to denote the unit of measure.

• grid (GridForm) – The form where the elements are added to

• row (int) – The row number in the form where the elements will be positioned. All elements are on the same row.

• widths (List[int]) – A list of width for the elements (name, value, scale)

• min_val (float) – The minium value that the element will display. Needed to calibrate the bar graph.

• max_val (float) – The maximum value that the element will display. Needed to calibrate the bar graph.

unit: str

String for units of measure.

name: snack.Textbox

A snack.TextBox that will display the name part of the element.

value: snack.Textbox

A snack.TextBox that will display the value part of the element.

min_val: float

The minimum value expected for the element to display.

max_val: float

The maximum value expected for the element to display.

range_val: float

The range of the value expected to be displayed. Calculated as max-val - min_val.

scale: snack.Scale

The snack.Scale that will display the bar graph of the item.

update_value(value: float, format: str = '4.1f') → None

Updates the content of the elements based on the provided value.

Parameters

• value (float) – The new value to be displayed. This will be reflected in the value field as well as in the bar graph.

• format (str, optional) – The format to display the value in the value field, by default ‘4.1f’

class NameStatValue

class view_ui.NameStatValue(name: str, unit: str, grid: snack.GridForm, row: int, widths: List[int])

A display element that includes a name for the object, a status and an additional (optional can be ‘’) text.

__init__(name: str, unit: str, grid: snack.GridForm, row: int, widths: List[int]) → None

Creates a combined display element in one line with a name, a status (+unit of measure if provided) and a value.

Parameters

• name (str) – The name to be shown on the left side of the display.

• unit (str) – [A string to be shown after the value to denote the unit of measure.

• grid (GridForm) – [description]

• row (int) – The row number in the form where the elements will be positioned. All elements are on the same row.

• widths (List[int]) – A list of width for the elements (name, status, value)

unit: str

String for units of measure.

name: snack.Textbox

A snack.TextBox that will display the name part of the element.

stat: snack.Textbox

A snack.TextBox that will display the status part of the element.

value: snack.Textbox

A snack.TextBox that will display the value part of the element.

update_value(stat: str, value: str = '') → None

Updates the content of the elements based on the provided value.

Parameters

• stat (str) – A string showing the status of the element.

• value (str, optional) – An additional value to be shown after the status, by default ‘’.

Views

class RobotStatusView

class status_view.RobotStatusView(screen: snack.SnackScreen, timer: int, title: str = 'Robot Status')

View that presents the overview of robot’s hardware (excluding servos).

This version includes the following information: - battery voltage - voltage for 5V railing - voltage for 3.3V railing - battery statistics (on battery for…, battery remaining…); these are claculated

in the code here and are based on monitoring the discharge of the battery and the last time the battery was changed

• processor temperature

• fan status (on, off)

• CPU frequency

• CPU governor

• CPU load (1 minute, 5 minutes, 15 minutes average)

• memory used (in %)

• WiFi AP status (IP address if on)

• WiFi dongle status (IP address is connected to infrastructure)

• LAN status (IP address is connected to infrastructure)

__init__(screen: snack.SnackScreen, timer: int, title: str = 'Robot Status')

Constructor for the status view.

Initializes the battery statistics.

Parameters

• screen (snack.SnackScreen) – The screen where the display will be made.

• timer (int) – [description]

• title (str, optional) – Title to be printed for the view, by default ‘Robot Status’

batt_last_change: float

Keeps the time that the battery was changed last.

batt_last_change_value: float

The last value for the battery voltage when battery was replaced.

batt_last_value: float

Last read battery voltage.

batt_last_estimate: float

Time when the latest estimate about battery life was done.

on_batt_str: str

mm time on battery from last change (or start).

Type

String showing hh

rem_batt_str: str

mm time remaining on battery based on last estimate.

Type

String showing hh

create_content() → snack.Grid

Creates a snack.Grid that contains the items to be displayed and initializes the values for these elements.

Returns

The initialized Grid to be used by MainUI.

Return type

snack.Grid

shell_cmd(command: str) → str

Convenience function for running a Shell command an returning the result.

Parameters

command (str) – Command to be execcuted (ex. ifconfig wlan0 | grep "inet ").

Returns

The result of running the command or empty string is errors occurred.

Return type

str

read_sysfs(file: str) → str

Reads the content of a sysfs parameter and returns the value stripped.

The method is provided as a faster alternative to using the shell_cmd`() because no shell will need to be spun.

Parameters

file (str) – The sysfs access (ex. /sys/class/thermal/thermal_zone0/temp). Please note that the function does not handle any exceptions, so if the file does not exist or the user does not have authorization to read the value an exception will be raised and needs to be handled by the calling program.

Returns

The result of reading that sysfs parameter.

Return type

str

get_interf_status(interf: str) → Tuple[str, str]

Convenience function for getting the status and the IP address of an interface.

Parameters

interf (str) – The name of the interface (ex. wlan0)

Returns

Returns the status of the interface in the first string as “On” or “Off” and the IP address in the second string if connected or empty string if not connected.

Return type

tuple(str, str)

update_content() → None

Reads the information for each of the elements in the screen and updates their content.

This is triggered by the timer that is setup by the view_ui.View class.

class JointView