fw

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.

change_directory(directory: str, processor: FreeWiliProcessorType) → Ok[str] | Err[str]

Change the current directory for file operations.

Arguments:

directory: str

The directory to change to.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

create_blank_file(name: str, processor: FreeWiliProcessorType) → Ok[str] | Err[str]

Create a blank file on the FreeWili.

Arguments:

name: str

The name of the file to create.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

create_directory(directory: str, processor: FreeWiliProcessorType) → Ok[str] | Err[str]

Create a new directory on the FreeWili.

Arguments:

directory: str

The directory to create.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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.

enable_accel_events(enable: bool, interval_ms: int | None = None, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Enable or disable acceleration events.

Arguments:

enable: bool

Whether to enable or disable acceleration events.

interval_ms: int | None

The interval in milliseconds for accelerometer events. If None, the default value will be used.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_audio_events(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Enable or disable audio events.

Arguments:

enable: bool

Whether to enable or disable audio events.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_battery_events(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Enable or disable battery events.

Arguments:

enable: bool

Whether to enable or disable battery events.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_button_events(enable: bool, interval_ms: int | None = None, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Enable or disable acceleration events.

Arguments:

enable: bool

Whether to enable or disable acceleration events.

interval_ms: int | None

The interval in milliseconds for accelerometer events. If None, the default value will be used.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_gpio_events(enable: bool, interval_ms: int | None = None, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Enable or disable GPIO events.

Arguments:

enable: bool

Whether to enable or disable GPIO events.

interval_ms: int | None

The interval in milliseconds for GPIO events. If None, the default value will be used.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_ir_events(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Enable or disable infrared events.

Arguments:

enable: bool

Whether to enable or disable infrared events.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_radio_events(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Enable or disable radio events on currently selected radio.

Arguments:

enable: bool

Whether to enable or disable radio events.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

enable_uart_events(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Enable or disable UART events.

Arguments:

enable: bool

Whether to enable or disable UART events.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

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

Format the filesystem on the FreeWili.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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_rtc(processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[tuple[datetime, int]] | Err[str]

Get the RTC (Real-Time Clock) from the FreeWili.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[tuple[datetime.datetime, int], str]:

Ok(tuple[datetime.datetime, 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

list_current_directory(processor: FreeWiliProcessorType) → Ok[FileSystemContents] | Err[str]

List the contents of the current directory on the FreeWili.

Note: This API is currently considered experimental and may change in the future.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[FileSystemContents, str]:

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

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

Load FPGA from file.

Arguments:

file_name: str

Name of the file in the FreeWili. 8.3 filename limit exists as of V12 ‘spi’,’uart’,’i2c’ or a filename name with extension.

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

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

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.

move_directory_or_file(original_name: str, new_name: str, processor: FreeWiliProcessorType) → Ok[str] | Err[str]

Move a directory or file on the FreeWili.

Arguments:

original_name: str

The original name of the directory or file to move.

new_name: str

The new name of the directory or file.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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.

play_audio_asset(asset_value: str | int, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Play an audio asset on the FreeWili.

Arguments:

asset_value: str | int

The asset value to play.

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

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

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

Play an audio file 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.

play_audio_number_as_speech(value: int, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Play an audio number as speech on the FreeWili.

Arguments:

value: int

The audio number to play.

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

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

play_audio_tone(frequency_hz: int, duration_sec: float, amplitude: float, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Play an audio tone on the FreeWili.

Arguments:

frequency_hz: int

The frequency of the tone in Hertz.

duration_sec: float

The duration of the tone in seconds.

amplitude: float

The amplitude of the tone (0.0 to 1.0).

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

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

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

Poll I2C data.

Parameters:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[tuple[int, …], str]:

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

process_events() → None

Process any events that have been received.

This is typically called in a loop to process events as they come in.

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[bytes] | 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[bytes, str]:

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

read_write_spi_data(data: bytes, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Read and Write SPI data.

Parameters:

databytes

The data to write.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

Ok(str) if the command was sent successfully, Err(str) if not. The str is the response from the device, typically “OK”.

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

Record audio on the FreeWili.

Arguments:

file_name: str

Name of the file in the FreeWili. (ie. “/sounds/test.wav”)

processor: FreeWiliProcessorType

Processor to upload the file to.

Returns:

Result[str, str]:

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

remove_directory_or_file(dir_or_filename: str, processor: FreeWiliProcessorType) → Ok[str] | Err[str]

Remove a directory or file on the FreeWili.

Arguments:

dir_or_filename: str

The directory or file to remove.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

Reset the display back to the main menu.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

Ok(str) 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.

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

Select the radio to use for events.

Arguments:

radio_index: int

Index of the radio to select. 1 or 2 typically.

processor: FreeWiliProcessorType

Processor to use.

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.

send_ir(data: bytes, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Send IR data.

Notes: v54 firmware uses NEC format and is converted to an 32-bit integer.

Parameters:

databytes

The data to send. The first 4 bytes are used as the command.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[bytes, str]:

Ok(bytes) 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[str] | 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[str, str]:

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

set_event_callback(event_cb: None | Callable[[EventType, ResponseFrame, Any], None]) → None

Set the event callback for the FreeWili.

Parameters:

event_cb: Callable[[EventType, ResponseFrame, Any], None]

Callback function to be called when an event occurs. The function should accept three arguments: the event type, the response frame, and any additional data. Set to None to disable the callback.

set_io(io: int, menu_cmd: IOMenuCommand, pwm_freq: int | None = None, pwm_duty: int | None = 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[str, str]:

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

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

Set the RSSI threshold for radio events.

Arguments:

rssi: int

RSSI threshold value to set.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

Set the sample window (ms) for the specified radio.

Arguments:

sample_window_ms: int

Sample window value to set.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

set_rtc(dt: datetime, trim: int | None = None, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Set the RTC (Real-Time Clock) on the FreeWili.

Arguments:

dt: datetime

The datetime to set the RTC to.

trim: int | None

The trim value to set. (-127 - 127). If None, no trim is set.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

Set the settings as startup on the FreeWili.

Notes: Settings are unstable as of v54 firmware. Subject to change in future firmware versions.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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

Set the settings to default on the FreeWili.

Notes: Settings are unstable as of v54 firmware. Subject to change in future firmware versions.

Arguments:

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

set_system_sounds(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | Err[str]

Set the system sounds on the FreeWili.

Arguments:

enable: bool

Whether to enable or disable system sounds.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

show_gui_image(fwi_path: str, processor: FreeWiliProcessorType = FreeWiliProcessorType.Display) → Ok[str] | 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[str, str]:

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

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

Show text on the display.

Arguments:

text: str

text to display on screen.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

property stay_open: bool

Keep serial port open, if True.

Returns:

bool

toggle_high_speed_io(enable: bool, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Toggle the high-speed Bidirectional IO.

Parameters:

enable: bool

Whether to enable or disable high-speed IO.

Returns:

Result[str, str]:

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

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

Transmit a subfile to the specified radio.

Arguments:

sub_fname: str

Name of the subfile to transmit. This should be the filename with the extension.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

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[str] | 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[str, str]:

Ok(str) if the command was sent successfully, Err(str) if not. The str is the response from the device, typically “OK”.

write_radio(data: bytes, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Write radio data.

Arguments:

data: bytes

Data to transmit.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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

write_uart(data: bytes | str, processor: FreeWiliProcessorType = FreeWiliProcessorType.Main) → Ok[str] | Err[str]

Write uart data.

Arguments:

data: bytes

Data to transmit.

processor: FreeWiliProcessorType

Processor to use.

Returns:

Result[str, str]:

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