class pybela.Watcher.Watcher(ip='192.168.7.2', port=5555, data_add='gui_data', control_add='gui_control')

Bases: object

connect()

Attempts to establish a WebSocket connection and prints a message indicating success or failure.

get_buffer_size(var_type, timestamp_mode)

Returns the buffer size in bytes for buffers stored in a log file. This is the size of the buffer that is sent over websockets.

Parameters:

• var_type (str) – Variable type

• timestamp_mode (str) – Timestamp mode

Returns:

Buffer size in bytes

Return type:

int

get_data_byte_size(var_type)

Returns the byte size of the data type

Parameters:

var_type (str) – Variable type

Returns:

byte size of the variable type

Return type:

int

get_data_length(var_type, timestamp_mode)

Data length in the buffer

Parameters:

• var_type (str) – Variable type

• timestamp_mode (str) – Timestamp mode

Returns:

Data length in the buffer (number of elements)

Return type:

int

get_latest_timestamp()

get_prop_of_var(var_name, prop)

Get property of variable. Properties: name, type, timestamp_mode, log_filename, data_length

Parameters:

• var_name (str) – Variable name

• prop (str) – Requested property

Returns:

Requested property

Return type:

(type depending on prop)

is_connected()

list()

Asks the watcher for the list of variables and their properties and returns it

property sample_rate

send_ctrl_msg(msg)

Send control message

Parameters:

msg (str) – Message to send to the Bela watcher. Example: {“watcher”: [{“cmd”: “list”}]}

stop()

Closes websockets

property unwatched_vars

Returns a list of the variables in the watcher that are not being watched (i.e., whose data is NOT being sent over websockets for streaming or monitoring)

Returns:

List of unwatched variables

Return type:

list of str

property watched_vars

Returns a list of the variables in the watcher that are being watched (i.e., whose data is being sent over websockets for streaming or monitoring)

Returns:

List of watched variables

Return type:

list of str

property watcher_vars

Returns variables in watcher with their properties (name, type, timestamp_mode, log_filename, data_length)

Returns:

List of variables in watcher and their properties

Return type:

list of dicts

class pybela.Streamer.Streamer(ip='192.168.7.2', port=5555, data_add='gui_data', control_add='gui_control')

Bases: Watcher

async async_stream_n_values(variables=[], periods=[], n_values=1000, saving_enabled=False, saving_filename='var_stream.txt', saving_dir='./', on_buffer_callback=None, on_block_callback=None, callback_args=())

Asynchronous version of stream_n_values(). Usage:

stream_task = asyncio.create_task(streamer.async_stream_n_values(variables, n_values, saving_enabled, saving_filename))

and retrieve the streaming buffer using:

streaming_buffers_queue = await stream_task

Parameters:

• variables (list, optional) – List of variables to be streamed. Defaults to [].

• periods (list, optional) – List of streaming periods. Streaming periods are used by the monitor and will be ignored if in streaming mode. Defaults to [].

• n_values (int, optional) – Number of values to stream for each variable. Defaults to 1000.

• saving_enabled (bool, optional) – Enables/disables saving streamed data to local file. Defaults to False.

• saving_filename (str, optional)

• saving_dir (str, optional) – Directory for saving the streamed data. Defaults to “./”.

• on_buffer_callback (function, optional). Callback function that is called every time a buffer is received. The callback function should take a single argument, the buffer. Accepts asynchronous functions (defined with async def)

• on_block_callback (function, optional). Callback function that is called every time a block of buffers is received. A block of buffers is a list of buffers, one for each streamed variable. The callback function should take a single argument, a list of buffers. Accepts asynchronous functions (defined with async def)

• callback_args (tuple, optional) – Arguments to pass to the callback functions. Defaults to ().

Returns:

Streaming buffers queue

Return type:

deque

flush_queue()

Flushes the streaming buffers queue. The queue is emptied and the insertion counts are reset to 0.

is_streaming()

Returns True if the streamer is currently streaming, False otherwise.

Returns:

Streaming status bool

Return type:

bool

load_data_from_file(filename)

Loads data from a file saved through the saving_enabled function in start_streaming() or stream_n_values(). The file should contain a list of dicts, each dict containing a variable name and a list of values. The list of dicts should be separated by newlines. :param filename: Filename :type filename: str

Returns:

List of values loaded from file

Return type:

list

property monitored_vars

Returns a list of monitored variables. If no variables are monitored, returns an empty list.

Returns:

list of monitored variables

Return type:

list

plot_data(x_var, y_vars, y_range=None, plot_update_delay=100, rollover=500)

Plots a bokeh figure with the streamed data. The plot is updated every plot_update_delay ms. The plot is interactive and can be zoomed in/out, panned, etc. The plot is shown in the notebook.

Parameters:

• x_var (str) – Variable to be plotted on the x axis

• y_vars (list of str) – List of variables to be plotted on the y axis

• y_range (float, float) – Tuple containing the y axis range. Defaults to None. If none is given, the y axis range is automatically resized to fit the data.

• plot_update_delay (int, optional) – Delay between plot updates in ms. Defaults to 100.

• rollover (int, optional) – Number of data points to keep on the plot. Defaults to 1000.

schedule_streaming(variables=[], timestamps=[], durations=[], saving_enabled=False, saving_filename='var_stream.txt', saving_dir='./', on_buffer_callback=None, on_block_callback=None, callback_args=())

Schedule streaming of variables. The streaming session can be stopped with stop_streaming().

Parameters:

• variables (list, optional) – List of variables to be streamed. Defaults to [].

• timestamps (list, optional) – Timestamps to start streaming (one for each variable). Defaults to [].

• durations (list, optional) – Durations to stream for (one for each variable). Defaults to [].

• saving_enabled (bool, optional) – Enables/disables saving streamed data to local file. Defaults to False.

• saving_filename (str, optional)

• saving_dir (str, optional) – Directory for saving the streamed data files. Defaults to “./”.

• on_buffer_callback (function, optional). Callback function that is called every time a buffer is received. The callback function should take a single argument, the buffer. Accepts asynchronous functions (defined with async def)

• on_block_callback (function, optional). Callback function that is called every time a block of buffers is received. A block of buffers is a list of buffers, one for each streamed variable. The callback function should take a single argument, a list of buffers. Accepts asynchronous functions (defined with async def)

• callback_args (tuple, optional) – Arguments to pass to the callback functions. Defaults to ().

send_buffer(buffer_id, buffer_type, buffer_length, data_list, verbose=False)

Sends a buffer to Bela. The buffer is packed into binary format and sent over the websocket.

Parameters:

• buffer_id (int) – Buffer id

• buffer_type (str) – Buffer type. Supported types are ‘i’ (int), ‘f’ (float), ‘j’ (uint), ‘d’ (double), ‘c’ (char).

• buffer_length (int) – Buffer length

• data_list (list) – List of data to be sent

start_streaming(variables=[], periods=[], saving_enabled=False, saving_filename='var_stream.txt', saving_dir='./', on_buffer_callback=None, on_block_callback=None, callback_args=())

Starts the streaming session. The session can be stopped with stop_streaming().

If no variables are specified, all watcher variables are streamed. If saving_enabled is True, the streamed data is saved to a local file. If saving_filename is None, the default filename is used with the variable name appended to its start. The filename is automatically incremented if it already exists.

Parameters:

• variables (list, optional) – List of variables to be streamed. Defaults to [].

• periods (list, optional) – List of streaming periods. Streaming periods are used by the monitor and will be ignored if in streaming mode. Defaults to [].

• saving_enabled (bool, optional) – Enables/disables saving streamed data to local file. Defaults to False.

• saving_filename (str, optional)

• on_buffer_callback (function, optional). Callback function that is called every time a buffer is received. The callback function should take a single argument, the buffer. Accepts asynchronous functions (defined with async def)

• on_block_callback (function, optional). Callback function that is called every time a block of buffers is received. A block of buffers is a list of buffers, one for each streamed variable. The callback function should take a single argument, a list of buffers. Accepts asynchronous functions (defined with async def)

• callback_args (tuple, optional) – Arguments to pass to the callback functions. Defaults to ().

stop_streaming(variables=[])

Stops the current streaming session for the given variables. If no variables are passed, the streaming of all variables is interrupted.

Parameters:

variables (list, optional) – List of variables to stop streaming. Defaults to [].

Returns:

Dict containing the streaming buffers for each streamed variable.

Return type:

streaming_buffers_queue (dict)

stream_n_values(variables=[], periods=[], n_values=1000, saving_enabled=False, saving_filename=None, saving_dir='./', on_buffer_callback=None, on_block_callback=None, callback_args=())

Streams a given number of values. Since the data comes in buffers of a predefined size, always an extra number of frames will be streamed (unless the number of frames is a multiple of the buffer size).

Note: This function will block the main thread until n_values have been streamed. Since the streamed values come in blocks, the actual number of returned frames streamed may be higher than n_values, unless n_values is a multiple of the block size (streamer._streaming_block_size).

To avoid blocking, use the async version of this function:

stream_task = asyncio.create_task(streamer.async_stream_n_values(variables, n_values, periods, saving_enabled, saving_filename))

and retrieve the streaming buffer using:

streaming_buffers_queue = await stream_task

Parameters:

• variables (list, optional) – List of variables to be streamed. Defaults to [].

• periods (list, optional) – List of streaming periods. Streaming periods are used by the monitor and will be ignored if in streaming mode. Defaults to [].

• n_values (int, optional) – Number of values to stream for each variable. Defaults to 1000.

• delay (int, optional) – _description_. Defaults to 0.

• saving_enabled (bool, optional) – Enables/disables saving streamed data to local file. Defaults to False.

• saving_filename (str, optional)

• saving_dir (str, optional) – Directory for saving the streamed data. Defaults to “./”.

• on_buffer_callback (function, optional). Callback function that is called every time a buffer is received. The callback function should take a single argument, the buffer. Accepts asynchronous functions (defined with async def)

• on_block_callback (function, optional). Callback function that is called every time a block of buffers is received. A block of buffers is a list of buffers, one for each streamed variable. The callback function should take a single argument, a list of buffers. Accepts asynchronous functions (defined with async def)

• callback_args (tuple, optional) – Arguments to pass to the callback functions. Defaults to ().

Returns:

Dict containing the streaming buffers for each streamed variable.

Return type:

streaming_buffers_queue (dict)

property streaming_buffers_data

Returns a dict where each key corresponds to a variable and each value to a flat list of the streamed values. Does not return timestamps of each datapoint since that depends on how often the variables are reassigned in the Bela code. :returns: Dict of flat lists of streamed values. :rtype: dict

property streaming_buffers_queue

{“var1”: [val1, val2, …], “var2”: [val1, val2, …], …} }

Returns:

streaming buffers queue

Return type:

dict

Type:

Returns a dict where each key corresponds to a variable and each item to the variable’s buffer queue. The queue has maximum length determined by streamer.streaming_buffers_queue_length. Each item of the queue is a received buffer of the form {“frame

Type:

int, “data”

property streaming_buffers_queue_length

Returns: int: maximum number of streaming buffers allowed in self.streaming_buffers_queue

class pybela.Logger.Logger(ip='192.168.7.2', port=5555, data_add='gui_data', control_add='gui_control')

Bases: Watcher

connect_ssh()

Connects to Bela via ssh to transfer log files.

copy_all_bin_files_in_project(dir='./', verbose=True)

Copies all .bin files in the specified remote directory using SFTP.

Parameters:

• dir (str, optional) – Path to the local directory where the files are copied to. Defaults to “./”.

• verbose (bool, optional) – Show info messages. Defaults to True.

copy_file_from_bela(remote_path, local_path, verbose=True)

Copy a file from Bela onto the local machine.

Parameters:

• remote_path (str) – Path to the remote file to be copied.

• local_path (str) – Path to the local file (where the file is copied to)

• verbose (bool, optional) – Show info messages. Defaults to True.

delete_all_bin_files_in_project(verbose=True)

Deletes all .bin files in the specified remote directory using SFTP.

delete_file_from_bela(remote_path, verbose=True)

Deletes a file from the remote path in Bela.

Parameters:

remote_path (str) – Path to the remote file to be deleted.

disconnect_ssh()

Disconnects from Bela via ssh.

finish_copying_file(remote_path, local_path)

Finish copying file if it was interrupted. This function is used to copy the remaining part of a file that was interrupted during the copy process.

Parameters:

remote_path (str) – Path to the file in Bela. local_path (str): Path to the file in the local machine (where the file is copied to)

is_logging()

Returns True if the logger is currently logging, false otherwise.

Returns:

Logger status

Return type:

bool

read_binary_file(file_path, timestamp_mode)

Reads a binary file generated by the logger and returns a dictionary with the file contents.

Parameters:

• file_path (str) – Path of the file to be read.

• timestamp_mode (str) – Timestamp mode of the variable. Can be “dense” or “sparse”.

Returns:

Dictionary with the file contents.

Return type:

dict

schedule_logging(variables=[], timestamps=[], durations=[], transfer=True, logging_dir='./')

Schedule logging session. The session starts at the specified timestamps and lasts for the specified durations. If the timestamp is in the past, the logging will start immediately. The session can be ended by calling stop_logging().

Parameters:

• variables (list, optional) – Variables to be logged. Defaults to [].

• timestamps (list, optional) – Timestamps to start logging (one for each variable). Defaults to [].

• durations (list, optional) – Durations to log for (one for each variable). Defaults to [].

• transfer (bool, optional) – Transfer files to laptop automatically during logging session. Defaults to True.

• logging_dir (str, optional) – Path to store the files. Defaults to “./”.

start_logging(variables=[], transfer=True, logging_dir='./')

Starts logging session. The session can be ended by calling stop_logging().

Parameters:

• variables (list of str, optional) – List of variables to be logged. If no variables are passed, all variables in the watcher are logged. Defaults to [].

• transfer (bool, optional) – If True, the logged files will be transferred automatically during the logging session. Defaults to True.

Returns:

List of local paths to the logged files.

Return type:

list of str

stop_logging(variables=[])

Stops logging session.

Parameters:

variables (list of str, optional) – List of variables to stop logging. If none is passed, logging is stopped for all variables in the watcher. Defaults to [].

class pybela.Monitor.Monitor(ip='192.168.7.2', port=5555, data_add='gui_data', control_add='gui_control')

Bases: Streamer

async async_monitor_n_values(variables=[], periods=[], n_values=1000, saving_enabled=False, saving_filename=None)

Asynchronous version of monitor_n_values(). Usage:

monitor_task = asyncio.create_task(monitor.async_monitor_n_values(variables, periods, n_values, saving_enabled, saving_filename))

and retrieve the monitored buffer using:

monitoring_buffers_queue = await monitor_task

Parameters:

• variables (list, optional) – List of variables to be monitored. Defaults to [].

• periods (list, optional) – List of monitoring period. Defaults to [].

• n_values (int, optional) – Number of values to monitor for each variable. Defaults to 1000.

• saving_enabled (bool, optional) – Enables/disables saving monitored data to local file. Defaults to False.

• saving_filename (_type_, optional)

Returns:

Monitored buffers queue

Return type:

deque

connect()

Attempts to establish a WebSocket connection and prints a message indicating success or failure.

load_data_from_file(filename, flatten=True)

Loads data from a file saved through the saving_enabled function in start_monitoring() or monitor_n_values(). The file should contain a list of dicts, each dict containing a variable name and a list of values. The list of dicts should be separated by newlines. :param filename: Filename :type filename: str :param flatten: If True, the returned list of values is flattened. Defaults to True. :type flatten: bool, optional

Returns:

Dict with “timestamps” and “values” list if flatten is True, otherwise a list of dicts with “timestamp” and “value” keys.

Return type:

dict of lists

monitor_n_values(variables=[], periods=[], n_values=1000, saving_enabled=False, saving_filename='monitor.txt')

Monitors a given number of values. Since the data comes in buffers of a predefined size, always an extra number of frames will be monitored (unless the number of frames is a multiple of the buffer size).

Note: This function will block the main thread until n_values have been monitored. Since the monitored values come in blocks, the actual number of returned frames monitored may be higher than n_values, unless n_values is a multiple of the block size (monitor._streaming_block_size).

To avoid blocking, use the async version of this function:

monitor_task = asyncio.create_task(monitor.async_monitor_n_values(variables, n_values, periods, saving_enabled, saving_filename))

and retrieve the monitored buffer using:

monitored_buffers_queue = await monitor_task

Parameters:

• variables (list, optional) – List of variables to be monitored. Defaults to [].

• periods (list, optional) – List of monitoring periods. Defaults to [].

• n_values (int, optional) – Number of values to monitor for each variable. Defaults to 1000.

• delay (int, optional) – _description_. Defaults to 0.

• saving_enabled (bool, optional) – Enables/disables saving monitored data to local file. Defaults to False.

• saving_filename (_type_, optional)

Returns:

Dict containing the monitored buffers for each streamed variable.

Return type:

monitored_buffers_queue (dict)

peek(variables=[])

Peek at variables

Parameters:

variables (list, optional) – List of variables to peek at. If no variables are specified, stream all watcher variables (default).

Returns:

Dictionary of variables with their values

Return type:

dict

start_monitoring(variables=[], periods=[], saving_enabled=False, saving_filename='monitor.txt', saving_dir='/.')

Starts the monitoring session. The session can be stopped with stop_monitoring().

If no variables are specified, all watcher variables are monitored. If saving_enabled is True, the monitored data is saved to a local file. If saving_filename is None, the default filename is used with the variable name appended to its start. The filename is automatically incremented if it already exists.

Parameters:

• variables (list, optional) – List of variables to be streamed. Defaults to [].

• periods (list, optional) – List of monitoring periods. Defaults to [].

• saving_enabled (bool, optional) – Enables/disables saving monitored data to local file. Defaults to False.

• saving_filename (str, optional)

• saving_dir (str, optional) – Directory for saving the monitored data. Defaults to “/.”.

stop_monitoring(variables=[])

Stops the current monitoring session for the given variables. If no variables are passed, the monitoring of all variables is interrupted.

Parameters:

variables (list, optional) – List of variables to stop monitoring. Defaults to [].

Returns:

Dict containing the monitored buffers for each monitored variable

Return type:

dict of dicts of lists

property values

Get monitored values from last monitoring session

Returns:

Dict containing the monitored buffers for each variable in the watcher

Return type:

dict of dicts of list

class pybela.Controller.Controller(ip='192.168.7.2', port=5555, data_add='gui_data', control_add='gui_control')

Bases: Watcher

get_controlled_status(variables=[])

Gets the controlled status (controlled or uncontrolled) of the variables

Parameters:

variables (list of str, optional) – List of variables to check. Defaults to all variables in the watcher.

Returns:

List of controlled status of the variables

Return type:

list of str

get_value(variables=[])

Gets the value of the variables

Parameters:

variables (list of str, optional) – List of variables to get the value from. Defaults to all variables in the watcher.

Returns:

List of controlled values of the variables

Return type:

list of numbers

send_value(variables, values)

Send a value to the given variables. Note: All values set with this function will be only visible through the “get_value()” method, or the “value” field in the list() function. Values streamed with the streamer, logger or monitor classes will not be affected.

Parameters:

• variables (list, required) – List of variables to control.

• values (list, required) – Values to be set for each variable.

start_controlling(variables=[])

Starts controlling given variables. This function will block until all requested variables are set to ‘controlled’ in the list. Note: All values set with the controller class will be only visible through the “get_value()” method, or the “value” field in the list() function. Values streamed with the streamer, logger or monitor classes will not be affected.

Parameters:

variables (list, optional) – List of variables to control. If no variables are specified, stream all watcher variables (default).

stop_controlling(variables=[])

Stops controlling given variables. This function will block until all requested variables are set to ‘uncontrolled’ in the list. Note: All values set with the controller class will be only visible through the “get_value()” method, or the “value” field in the list() function.

Parameters:

variables (list, optional) – List of variables to control. If no variables are specified, stream all watcher variables (default).