mwings.utils Module

mwings.utils

Contains general-purpose utility functions.

src/mwings/utils.py

`ask_user()`

ask_user(prompt, regex, on_error, ex_verifier=None, max_attempts=None)

Gets input from the user via the console.

Arguments

Name	Type	Description
`prompt`	`str`	Message displayed in the prompt
`regex`	`str`	Regular expression to validate user input
`on_error`	`str`	Message displayed when user input is invalid
`ex_verifier`	`optional Callable[[str], bool]`	Function to further validate input string beyond regex
`max_attempts`	`optional int`	Number of retry attempts. `None` means unlimited

Returns

Type	Value	Description
`str`	-	Validated user input string

`ask_user_for_port()`

ask_user_for_port()

Prompts the user to select a port to use.

Arguments

None

Returns

Type	Value	Description
`str`	-	Selected port name

`byte_count_from()`

byte_count_from(character_count)

Converts the length of a byte sequence represented as an ASCII string to the length of its binary representation.

Arguments

Name	Type	Description
`character_count`	`int`	Length of the ASCII representation of the byte sequence

Returns

Type	Value	Description
`int`	-	Length of the byte sequence in binary form

`character_from()`

character_from(hexvalue)

Converts a number from 0x0 to 0xF to its hexadecimal character representation.

Arguments

Name	Type	Description
`hexvalue`	`int`	Number

Returns

Type	Value	Description
`int`	-	ASCII code of character

`find_ascii()`

find_ascii(port, data, timeout, debugging=False)

Waits to receive the specified ASCII string.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`str`	ASCII string
`timeout`	`int`	Timeout (seconds)
`debugging`	`bool`	Debug output

Returns

Type	Value	Description
`bool`	`True`	Reception confirmed
`bool`	`False`	Reception not confirmed

`find_binary()`

find_binary(port, data, timeout, debugging=False)

Waits to receive the specified byte sequence.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`str`	Byte sequence
`with_terminal`	`bool`	Whether to use terminal data
`terminal`	`int`	Data to treat as terminal
`timeout`	`int`	Timeout (seconds)
`debugging`	`bool`	Debug output

Returns

Type	Value	Description
`bool`	`True`	Reception confirmed
`bool`	`False`	Reception not confirmed

`flush_rx_buffer()`

flush_rx_buffer(port)

Clears the receive buffer.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

None

`flush_tx_buffer()`

flush_tx_buffer(port)

Clears the transmit buffer.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

None

`get_ports()`

get_ports()

Retrieves a list of available serial ports.

Arguments

None

Returns

Type	Value	Description
`list[str]`	-	List of port names

`hex_from()`

hex_from(character)

Converts an ASCII character representing a hexadecimal digit to its numeric value. The result is undefined for characters other than 0-9 and A-F.

Arguments

Name	Type	Description
`character`	`int`	ASCII code of the character

Returns

Type	Value	Description
`int`	-	Numeric value

`is_initialized()`

is_initialized(port)

Checks whether the serial port is initialized.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Initialized
	`False`	Not initialized

`is_readable()`

is_readable(port)

Checks whether data can be read from the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Data available in receive buffer
	`False`	Not readable

`is_there_some_ports()`

is_there_some_ports()

Checks whether any serial ports are available.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Serial ports exist
	`False`	None available

`is_writable()`

is_writable(port)

Checks whether data can be written to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Writable
	`False`	Not writable

`lrc8()`

lrc8(data)

Calculates the 8-bit LRC.

Arguments

Name	Type	Description
`data`	`bytes`	Byte sequence to calculate

Returns

Type	Value	Description
`int`	-	LRC8 value

`millis()`

millis()

Gets the current system time in milliseconds.

Arguments

None

Returns

Type	Value	Description
`int`	-	System time (ms)

`open_on_system()`

open_on_system(path)

Opens the specified file path with the system’s default application.

Arguments

Name	Type	Description
`path`	`Path`	File path

Returns

None

`write_binary()`

write_binary(port, data)

Sends a byte sequence to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`int`	Data to send
	`bytes`	Sequence of data to send

Returns

None

`write_in_ascii()`

write_in_ascii(port, data)

Sends an ASCII representation of a byte sequence to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`int`	Character to send
	`bytes`	String to send

Returns

None