fw Module

Main Module for interacting with a FreeWili.

fw Module API

For Interfacing to Free-Wili Devices.

class freewili.fw.FileMap(extension: str, processor: FreeWiliProcessorType, directory: str, description: str)

Bases: object

Map file extension to processor type and location.

description: str

directory: str

extension: str

classmethod from_ext(ext: str) → Self

Creates a FileMap from a file extension.

Parameters:

ext: str

File extension (ie. “.wasm”). Not case sensitive.

Returns:

FileMap

Raises:

ValueError:

If the extension isn’t known.

classmethod from_fname(file_name: str) → Self

Creates a FileMap from a file path.

Parameters:

file_name: str

File name (ie. “myfile.wasm”). Not case sensitive. Can contain paths.

Returns:

FileMap

Raises:

ValueError:

If the extension isn’t known.

processor: FreeWiliProcessorType

to_path(file_name: str) → str

Creates a file path from the file_name to upload to the FreeWili.

Parameters:

file_name: str

File name (ie. “myfile.wasm”). Not case sensitive. Can contain paths.

Returns:

str

Full file path intended to be uploaded to a FreeWili

Raises:

ValueError:

If the extension isn’t known.

class freewili.fw.FreeWili(device: FreeWiliDevice)

Bases: object

Free-Wili device used to access FTDI and serial functionality.

close(restore_menu: bool = True) → None

Close the serial port. Use in conjunction with stay_open.

Arguments:

restore_menu: bool

Restore the menu functionality before close

Returns:

None

property display: None | USBDevice

Get Display processor.

property display_serial: None | FreeWiliSerial

Get Display FreeWiliSerial.

Arguments:

None

Returns:

None | FreeWiliSerial:

FreeWiliSerial on success, None otherwise.

property esp32: None | USBDevice

Get Display processor.

classmethod find_all() → tuple[Self, ...]

Find all Free-Wili devices attached to the host.

Parameters:

None

Returns:

tuple[FreeWili, …]:

Tuple of FreeWili devices.

Raises:

None

classmethod find_first() → Ok[Self] | Err[str]

Find first Free-Wili device attached to the host.

Parameters:

None

Returns:

Result[FreeWili, str]:

Ok(FreeWili) if successful, Err(str) otherwise.

Raises:

None

property ftdi: None | USBDevice

Get FTDI processor.

get_file(source_file: str, destination_path: str | Path, processor: FreeWiliProcessorType | None = None, event_cb: Callable | None = None) → Ok[str] | Err[str]

Send a file to the FreeWili.

Arguments:

source_file: pathlib.Path

Path to the file to be sent.

destination_path: pathlib.Path

file path to save on the PC

processor: None | FreeWiliProcessorType

Processor to upload the file to. If None, will be determined automatically based on the filename.

event_cb: Callable | None

event callback function. Takes one argument of a string.

def user_callback(msg: str) -> None

Returns:

Result[str, str]:

Returns Ok(str) if the command was sent successfully, Err(str) if not.

get_io(processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[tuple[int, ...]] | Err[str]

Get all the IO values.

Parameters:

processor: FreeWiliProcessorType

Processor to set IO on.

Returns:

Result[tuple[int], str]:

Ok(tuple[int]) if the command was sent successfully, Err(str) if not.

get_serial_from(processor_type: FreeWiliProcessorType) → Ok[FreeWiliSerial] | Err[str]

Get FreeWiliSerial from processor type.

Arguments:

processor_type: FreeWiliProcessorType

Processor type to get serial port for.

Returns:

Result[FreeWiliSerial, str]:

Ok(FreeWiliSerial) on success, Err(str) otherwise.

get_usb_device(processor_type: FreeWiliProcessorType) → None | USBDevice

Get the USBDevice by ProcessorType.

Parameters:

processor_type: FreeWiliProcessorType

Type of processor to get.

Returns:

None | fwf.USBDevice:

fwf.USBDevice if successful, None otherwise.

Raises:

None

property main: None | USBDevice

Get Main processor.

property main_serial: None | FreeWiliSerial

Get Main FreeWiliSerial.

Arguments:

None

Returns:

None | FreeWiliSerial:

FreeWiliSerial on success, None otherwise.

open(block: bool = True, timeout_sec: float = 6.0) → Ok[None] | Err[str]

Open the serial port. Use in conjunction with stay_open.

Arguments:

block: bool:

If True, block until the serial port is opened.

timeout_sec: float:

number of seconds to wait when blocking.

Returns:

Result[None, str]:

Ok(None) if successful, Err(str) otherwise.

poll_i2c(processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[ResponseFrame] | Err[str]

Write I2C data.

Parameters:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

read_all_buttons(processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[dict[ButtonColor, bool]] | Err[str]

Read all the buttons.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[dict[ButtonColor, bool], str]:

Ok(dict[ButtonColor, bool]) if the command was sent successfully, Err(str) if not.

read_i2c(address: int, register: int, data_size: int, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[ResponseFrame] | Err[str]

Write I2C data.

Parameters:

addressint

The address to write to.

registerint

The register to write to.

data_sizeint

The number of bytes to read.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

reset_display(processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[ResponseFrame] | Err[str]

Reset the display back to the main menu.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

reset_to_uf2_bootloader(processor: FreeWiliProcessorType) → Ok[None] | Err[str]

Reset the FreeWili to the uf2 bootloader.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[None, str]:

Returns Ok(None) if the command was sent successfully, Err(str) if not.

run_script(file_name: str, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Run a script on the FreeWili.

Arguments:

file_name: str

Name of the file in the FreeWili. 8.3 filename limit exists as of V12

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

Ok(str) if the command was sent successfully, Err(str) if not.

send_file(source_file: str | Path, target_name: None | str = None, processor: FreeWiliProcessorType | None = None, event_cb: Callable | None = None, chunk_size: int = 0) → Ok[str] | Err[str]

Send a file to the FreeWili.

Arguments:

source_file: pathlib.Path

Path to the file to be sent.

target_name: None | str

Name of the file in the FreeWili. If None, will be determined automatically based on the filename.

processor: None | FreeWiliProcessorType

Processor to upload the file to. If None, will be determined automatically based on the filename.

event_cb: Callable | None

event callback function. Takes one argument of a string.

def user_callback(msg: str) -> None

chunk_size: int

Size of the chunks to send in bytes. Typically this should be left at the default value.

Returns:

Result[str, str]:

Returns Ok(str) if the command was sent successfully, Err(str) if not.

set_board_leds(io: int, red: int, green: int, blue: int, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[ResponseFrame] | Err[str]

Set the GUI RGB LEDs.

Parameters:

ioint

The number of the IO pin to set.

redint

Red Color 0-255

greenint

Green Color 0-255

blueint

Blue Color 0-255

processor: FreeWiliProcessorType

Processor to set LEDs on.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

set_io(io: int, menu_cmd: IOMenuCommand, pwm_freq: None | int = None, pwm_duty: None | int = None, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Set the state of an IO pin to high or low.

Parameters:

ioint

The number of the IO pin to set.

menu_cmdIOMenuCommand

Whether to set the pin to high, low, toggle, or pwm.

pwm_freq: None | int

PWM frequency in Hertz

pwm_duty: None | int

PWM Duty cycle (0-100)

processor: FreeWiliProcessorType

Processor to set IO on.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

show_gui_image(fwi_path: str, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[ResponseFrame] | Err[str]

Show a fwi image on the display.

Arguments:

fwi_path: str

path to the fwi image

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

show_text_display(text: str, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[ResponseFrame] | Err[str]

Show text on the display.

Arguments:

text: str

text to display on screen.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.

property stay_open: bool

Keep serial port open, if True.

Returns:

bool

property usb_devices: List[USBDevice]

Grab all the USB devices attached to the FreeWili.

write_i2c(address: int, register: int, data: bytes, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[ResponseFrame] | Err[str]

Write I2C data.

Parameters:

addressint

The address to write to.

registerint

The register to write to.

databytes

The data to write.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[ResponseFrame, str]:

Ok(ResponseFrame) if the command was sent successfully, Err(str) if not.