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_time – float scan time interval to look for devices
min_devices – int minimum number of devices to look for before returning
scan_timeout – float timeout interval for finding the required min_devices
filters – list or str optional device name filters, e.g. “16 MB”
silent – boolean a flag to disable printing of status
verbose – boolean 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_interval – float time interval to wait for connection
timeout – float timeout interval for attempting a device connection
silent – boolean 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.