PFx Brick API Reference

The PFx Brick API has a top level PFxBrick class object. An instance of PFxBrick is used to open, maintain, and close an operating session with a PFx Brick. This class internally contains several supporting child classes used as convenient containers for related data. In particular, it contains a PFxConfig and PFxDir class which store configuration and file system data respectively.

The PFxAction class is used to specify actions the PFx Brick can perform including motor control, lighting effects, and sound effects. It has many supporting methods to conveniently specify popular actions. A host application can also directly modify the field attributes of a PFxAction instance to specify a detailed action description. Details of specifying these fields can be found in the PFx Brick Interface Control Document (ICD).

This page summarizes the main functional groups of functionality contained in this API in sections that follow.

Connection USB

Functions to establish a USB connected session with a PFx Brick.

find_bricks([show_list])

Enumerate and optionally print a list PFx Bricks currently connected to the USB bus.

PFxBrick.open([ser_no])

Opens a USB communication session with a PFx Brick.

PFxBrick.close()

Closes a USB communication session with a PFx Brick.

find_bricks(show_list=False)[source]

Enumerate and optionally print a list PFx Bricks currently connected to the USB bus.

Parameters

show_list (boolean) – optionally print a list of enumerated PFx Bricks

Returns

[str] a list of PFx Brick serial numbers

Connection BLE

Functions to establish a BLE connected session with a PFx Brick.

ble_device_scanner([scan_time, min_devices, ...])

Performs a Bluetooth scan for available peripheral devices which advertise themselves as PFx Bricks.

find_ble_pfxbricks(devices[, ...])

Resolves a list of scanned candidate Bluetooth devices into valid PFx Brick devices.

PFxBrickBLE.open([timeout])

Opens a BLE communication session with a PFx Brick.

PFxBrickBLE.close()

Closes a BLE communication session with a PFx Brick.

async ble_device_scanner(scan_time=3.0, min_devices=1, scan_timeout=30.0, filters=None, silent=False, verbose=False)[source]

Performs a Bluetooth scan for available peripheral devices which advertise themselves as PFx Bricks.

This coroutine will search for the required number of devices in scan_time chunks up until the scan_timeout interval has elapsed.

Parameters
  • scan_timefloat scan time interval to look for devices

  • min_devicesint minimum number of devices to look for before returning

  • scan_timeoutfloat timeout interval for finding the required min_devices

  • filterslist or str optional device name filters, e.g. “16 MB”

  • silentboolean a flag to disable printing of status

  • verboseboolean a flag to print a verbose list of advertising devices

Returns

[BLEDevice] a list of PFx Brick device objects described in a Bleak BLEDevice class.

async find_ble_pfxbricks(devices, connect_interval=5.0, timeout=30.0, silent=False)[source]

Resolves a list of scanned candidate Bluetooth devices into valid PFx Brick devices.

Parameters
  • devices – [BLEDevice] a list of candidate PFx Brick device objects

  • connect_intervalfloat time interval to wait for connection

  • timeoutfloat timeout interval for attempting a device connection

  • silentboolean a flag to disable printing of status

Returns

[dict] a list of dictionary objects for each PFx Brick verified by connection. The dictionary contains keys for “address”, “serial_no” and “name”.

Information

Functions to get information and status from the PFx Brick.

PFxBrick.get_icd_rev([silent])

Requests the version of Interface Control Document (ICD) the connected PFx Brick supports using the PFX_CMD_GET_ICD_REV ICD message.

PFxBrick.get_status()

Requests the top level operational status of the PFx Brick

PFxBrick.print_status()

Prints the top level operational status information retrieved by a previous call to the get_status method.

PFxBrick.get_name()

Retrieves the user defined name of the PFx Brick using the PFX_CMD_GET_NAME ICD message.

PFxBrick.set_name(name)

Sets the user defined name of the PFx Brick using the PFX_CMD_SET_NAME ICD message.

PFxBrick.get_current_state()

Returns the current state of the PFx Brick operating parameters.

PFxBrick.get_fs_state()

Returns the current state of the PFx Brick file system.

PFxBrick.get_bt_state()

Returns the current state of the PFx Brick Bluetooth radio module.

Configuration

Functions which query and modify PFx Brick configuration and settings.

PFxBrick.get_config()

Retrieves configuration settings from the PFx Brick using the PFX_CMD_GET_CONFIG ICD message.

PFxBrick.set_config()

Writes the contents of the PFxConfig data structure class to the PFx Brick using the PFX_CMD_SET_CONFIG ICD message.

PFxBrick.print_config()

Prints a summary representation of the PFx Brick configuration settings which were retrieved by a previous call to get_config.

PFxBrick.reset_factory_config()

Resets the PFx Brick configuration settings to factory defaults.

Event/Action LUT

Functions which query and modify the event/action look up table in the PFx Brick.

PFxBrick.get_action(evtID, ch)

Retrieves the stored action associated with a particular [eventID / IR channel] event.

PFxBrick.get_action_by_address(address)

Retrieves a stored action indexed by address rather than a combination of eventID and IR channel.

PFxBrick.set_action(evtID, ch, action)

Sets a new stored action associated with a particular [eventID / IR channel] event.

PFxBrick.set_action_by_address(address, action)

Sets a new stored action in the event/action LUT at the address specified.

File System

Functions which interact with the PFx Brick file system.

PFxBrick.refresh_file_dir()

Reads the PFx Brick file system directory.

PFxBrick.put_file(fn[, fileID, show_progress])

Copies a file from the host to the PFx Brick.

PFxBrick.get_file(fileID[, fn, show_progress])

Copies a file from the PFx Brick to the host.

PFxBrick.remove_file(fileID[, silent])

Removes a file from the PFx Brick file system.

PFxBrick.format_fs([quick])

Formats the PFx Brick file system, erasing all files.

PFxBrick.rename_file(fileID, new_name)

Renames a file on the file system.

PFxBrick.set_file_attributes(fileID, attr[, ...])

Sets the upper 8-bit attribute field of a file's directory entry.

PFxBrick.file_id_from_str_or_int(filespec)

Returns a numeric file ID from either a string filename or integer file ID.

Actions

Functions which specify and perform common actions.

PFxBrick.test_action(action)

Executes a passed action data structure.

Motor Actions

PFxBrick.set_motor_speed(ch, speed[, duration])

A convenience wrapper for PFxAction().set_motor_speed

PFxBrick.stop_motor(ch)

A convenience wrapper for PFxAction().stop_motor

PFxAction.set_motor_speed(ch, speed[, duration])

Populates an action to set the speed of specified motor channel(s).

PFxAction.stop_motor(ch)

Populates an action to stop the specifed motor channel(s).

Light Actions

PFxBrick.light_on(ch)

A convenience wrapper for PFxAction().light_on

PFxBrick.light_off(ch)

A convenience wrapper for PFxAction().light_off

PFxBrick.light_toggle(ch)

A convenience wrapper for PFxAction().light_toggle

PFxBrick.set_brightness(ch, brightness)

A convenience wrapper for PFxAction().set_brightness

PFxBrick.light_fx(ch, fx[, param])

A convenience wrapper for PFxAction().light_fx

PFxBrick.combo_light_fx(fx[, param])

A convenience wrapper for PFxAction().combo_light_fx

PFxAction.light_on(ch)

Populates an action to turn on selected light outputs.

PFxAction.light_off(ch)

Populates an action to turn off selected light outputs.

PFxAction.light_toggle(ch)

Populates an action to toggle the state of selected light outputs.

PFxAction.set_brightness(ch, brightness)

Populates an action to set the brightness of selected light outputs.

PFxAction.light_fx(ch, fx[, param])

Populates an action with a user specified light effect and associated parameters.

PFxAction.combo_light_fx(fx[, param])

Populates an action with a user specified combination light effect and associated parameters.

Sound Actions

PFxBrick.play_audio_file(fileID)

A convenience wrapper for PFxAction().sound_fx

PFxBrick.repeat_audio_file(fileID)

A convenience wrapper for PFxAction().repeat_audio_file

PFxBrick.stop_audio_file(fileID)

A convenience wrapper for PFxAction().stop_audio_file

PFxBrick.set_volume(volume)

A convenience wrapper for PFxAction().set_volume

PFxBrick.sound_fx(fx[, param, fileID])

A convenience wrapper for PFxAction().sound_fx

PFxAction.play_audio_file(fileID)

Populates an action to play an audio file once.

PFxAction.repeat_audio_file(fileID)

Populates an action for repeated playback of an audio file.

PFxAction.stop_audio_file(fileID)

Populates an action to stop playback of an audio file.

PFxAction.set_volume(volume)

Populates an action to set the audio volume.

PFxAction.sound_fx(fx[, param, fileID])

Populates an action with a user specified sound effect and associated parameters.

Running scripts

PFxBrick.run_script(scriptfile)

Runs a specified script file on the PFx Brick filesystem.

PFxBrick.stop_script()

Stops all script execution.

BLE Notifications

PFxBrickBLE.set_notifications(events)

Enables user selected notifications to be sent asynchronously from the PFx Brick.

PFxBrickBLE.disable_notifications()

Disables asynchronous notifications sent from the PFx Brick.