Class Reference

This page documents all of the attributes and functions of the pfxbrick module classes organized hierarchically.

PFxBrick

class PFxBrick(serial_no=None)

Top level PFx Brick object class.

This class is used to initialize and maintain a communication session with a USB connected PFx Brick. Many convenient methods are provided to perform tasks such as changing configuration, accessing the file system, initiating actions, and more.

Attributes:

product_id (str): product ID code reported by the PFx Brick (e.g. ‘A204’)

serial_no (str): serial number reported by the PFx Brick, usually 8 digit hexadecimal

product_desc (str): product descriptor reported by the PFx Brick

firmware_ver (str): firmware version number reported, 4-digit hex BCD, e.g. ‘0134’ represents v.1.34

firmware_build (str): firmware build number reported, 4-digit hex BCD

icd_rev (str): ICD revision number reported, 4-digit hex BCD, e.g. ‘0336’ represents v.3.36 status (int): status code reported, distinguishes normal and service/recovery mode

error (int): error code reported

usb_vid (int): fixed to PFX_USB_VENDOR_ID representing the official USB VID assigned to the PFx Brick

usb_pid (int): fixed to PFX_USB_PRODUCT_ID representing the official USB PID assigned to the PFx Brick

usb_manu_str (str): the manufacturer string reported to the host USB interface

usb_prod_str (str): the product descriptor string reported to the host USB interface

usb_serno_str (str): the product serial number string reported to the host USB interface

dev (device): a device handle to the HIDAPI cdef class device

is_open (boolean): a flag indicating connected session status

name (str): user defined name of the PFx Brick

config (PFxConfig): child class to store configuration and settings

filedir (PFxDir): child class to store the file system directory

open(ser_no=None)

Opens a USB communication session with a PFx Brick. If multiple PFx Bricks are connected, then a serial number must be specified to connect to a unique PFx Brick.

Parameters

ser_no – optional serial number to specify a particular PFx Brick if multiple connected

Returns

boolean indicating open session result

close()

Closes a USB communication session with a PFx Brick.

get_icd_rev(silent=False)

Requests the version of Interface Control Document (ICD) the connected PFx Brick supports using the PFX_CMD_GET_ICD_REV ICD message. The resulting version number is stored in this class and also returned.

Parameters

silent (boolean) – flag to optionally silence the status LED blink

Returns

str ICD version, e.g. “3.38”

get_status()

Requests the top level operational status of the PFx Brick

Summary operating status is obtained from the PFx Brick using the PFX_CMD_GET_STATUS ICD message. The resulting status data is stored in this class and can be queried with class member access methods such as status_str.

Returns

None

status_str()

Returns a summary status string of the PFx Brick

A human readable string of PFx Brick basic identification and and operating status. A call to the get_status method is recommended to ensure that the status information is recent.

Returns

str status string

print_status()

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

get_config()

Retrieves configuration settings from the PFx Brick using the PFX_CMD_GET_CONFIG ICD message. The configuration data is stored in the PFxBrick.config class member variable.

print_config()

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

set_config()

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

It is recommended that the configuration be read from the PFx Brick (using get_config) before any changes are made to the configuration and written back. This ensures that any configuration settings which are not desired to be changed are left in the same state.

reset_factory_config()

Resets the PFx Brick configuration settings to factory defaults.

get_name()

Retrieves the user defined name of the PFx Brick using the PFX_CMD_GET_NAME ICD message. The name is stored in the name class variable as a UTF-8 string.

Returns

str user defined name

set_name(name)

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

Parameters

name – str new name to set (up to 24 character bytes, UTF-8)

get_action_by_address(address)

Retrieves a stored action indexed by address rather than a combination of eventID and IR channel. The address is converted into a [eventID, IR channel] pair and the get_action method is called with this function as a convenient wrapper.

Parameters

address – int event/action LUT address (0 - 0x7F)

Returns

PFxAction class filled with retrieved LUT data

get_action(evtID, ch)

Retrieves the stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• channel – int channel index LUT address component (0 - 3)

Returns

PFxAction class filled with retrieved LUT data

set_action_by_address(address, action)

Sets a new stored action in the event/action LUT at the address specified. The address is converted into a [eventID, IR channel] pair and the set_action method is called with this function as a convenient wrapper.

Parameters

• address – int event/action LUT address (0 - 0x7F)

• action – PFxAction action data structure class

set_action(evtID, ch, action)

Sets a new stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• ch – int channel index LUT address component (0 - 3)

• action – PFxAction action data structure class

test_action(action)

Executes a passed action data structure. This function is used to “test” actions to see how they behave. The passed action is not stored in the event/action LUT.

Parameters

action – PFxAction action data structure class

clear_action_by_address(address)

Clears a stored action in the event/action LUT at the address specified. The address is converted into a [eventID, IR channel] pair and the set_action method is called with this function as a convenient wrapper.

Parameters

address – int event/action LUT address (0 - 0x7F) list,tuple,range specify a list or range of addresses

clear_action(evtID, ch)

Clears a stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• ch – int channel index LUT address component (0 - 3)

find_startup_action(lightfx=None, soundfx=None, motorfx=None)

Finds a startup action with one or more specified light, motor, or sound fx types.

Parameters

• lightfx – int optional lightfx id

• soundfx – int optional soundfx id

• motorfx – int optional motorfx id

Returns

PFxAction action data structure class matching the desired type(s)

set_motor_speed(ch, speed, duration=None)

A convenience wrapper for PFxAction().set_motor_speed

Parameters

• ch – [int] a list of motor channels (1-4)

• speed – int desired motor speed (-100 to +100)

• duration – float optional duration (in seconds) to run motor, runs indefinitely if not specified

If the duration value is specified, it represents the desired motor run time in seconds. Note that this value will be rounded to the nearest fixed interval of the DURATION parameter as defined in the ICD ranging between 16 fixed values from 0.5 sec to 5 min.

stop_motor(ch)

A convenience wrapper for PFxAction().stop_motor

Parameters

ch – [int] a list of motor channels (1-4)

light_on(ch)

A convenience wrapper for PFxAction().light_on

Parameters

ch – [int] a list of light channels (1-8)

light_off(ch)

A convenience wrapper for PFxAction().light_off

Parameters

ch – [int] a list of light channels (1-8)

light_toggle(ch)

A convenience wrapper for PFxAction().light_toggle

Parameters

ch – [int] a list of light channels (1-8)

set_brightness(ch, brightness)

A convenience wrapper for PFxAction().set_brightness

Parameters

• ch – [int] a list of light channels (1-8)

• brightness – int brightness (0 - 255 max)

combo_light_fx(fx, param=[0, 0, 0, 0, 0])

A convenience wrapper for PFxAction().combo_light_fx

Parameters

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

light_fx(ch, fx, param=[0, 0, 0, 0, 0])

A convenience wrapper for PFxAction().light_fx

Parameters

• ch – [int] a list of light channels (1-8)

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

sound_fx(fx, param=[0, 0], fileID=None)

A convenience wrapper for PFxAction().sound_fx

Parameters

• fx – int desired sound action

• param – [int] a list of up to 2 sound parameters

• fileID – int file ID of an audio file in the file system

play_audio_file(fileID)

A convenience wrapper for PFxAction().sound_fx

Parameters

fileID – int or str file ID or filename of an audio file in the file system

stop_audio_file(fileID)

A convenience wrapper for PFxAction().stop_audio_file

Parameters

fileID – int or str file ID or filename of an audio file in the file system

repeat_audio_file(fileID)

A convenience wrapper for PFxAction().repeat_audio_file

Parameters

fileID – int or str file ID or filename of an audio file in the file system

set_volume(volume)

A convenience wrapper for PFxAction().set_volume

Parameters

volume – int desired audio volume (0 - 100%)

refresh_file_dir()

Reads the PFx Brick file system directory. This includes the total storage used as well as the remaining capacity. Individual file directory entries are stored in the PFxBrick.filedir.files class variable.

put_file(fn, fileID=None, show_progress=True)

Copies a file from the host to the PFx Brick.

Parameters

• fn – str the filename (optionally including the path) of the file to copy

• fileID – int the unique file ID to assign the copied file in the file system, can be None for automatic assignment

• show_progress – boolean a flag to show the progress bar indicator during transfer.

get_file(fileID, fn=None, show_progress=True)

Copies a file from the PFx Brick to the host.

Parameters

• fileID – int or str the file ID or filename of the file to copy

• fn – str optional override for the filename when copied into the host

• show_progress – boolean a flag to show the progress bar indicator during transfer.

remove_file(fileID, silent=False)

Removes a file from the PFx Brick file system.

Parameters

• fileID – int or str the file ID or filename of the file to remove

• silent – boolean if True, warnings about missing files are suppressed

format_fs(quick=False)

Formats the PFx Brick file system, erasing all files.

Parameters

quick – boolean If True, only occupied sectors are erased. If False, every sector is erased, i.e. a complete format.

set_file_attributes(fileID, attr, mask=124)

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

Although the file attribute field is actually 16 bits, this function sets the upper 8 bits. The lower 8-bits are reserved for identifying the file type, e.g. text, WAV, etc.

Parameters

• fileID – int or str the file ID or filename of the file to remove

• attr – int the attribute value to set (only the lower 16)

• mask – int an optional bit mask applied to the attributes

rename_file(fileID, new_name)

Renames a file on the file system.

Parameters

• fileID – int or str the file ID or filename of the file to rename

• new_name – str new file name to apply (up to 32 characters UTF-8 encoded)

stop_script()

Stops all script execution.

run_script(scriptfile)

Runs a specified script file on the PFx Brick filesystem.

A file is identified either by its numeric file ID (0 - 254) or alphanumeric filename as a string.

Parameters

scriptfile – int or str file ID or file name string

file_id_from_str_or_int(filespec)

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

A file is identified on the PFx Brick filesystem primarily by its numeric file ID (0 - 254). A file ID of 255 is an invalid or non-existant file. A numeric file ID can be queried using its alphanumeric filename in the filesystem directory. This function performs this lookup if necessary, i.e. if a string filename is provided.

Parameters

filespec – int or str file ID or file name string

Returns

int numeric file ID from PFx Brick filesystem, or 0xFF if not found

get_current_state()

Returns the current state of the PFx Brick operating parameters.

Returns

PFxState a dataclass container with state information

get_fs_state()

Returns the current state of the PFx Brick file system.

Returns

PFxFSState a dataclass container of file system information

get_bt_state()

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

Returns

PFxBTState a dataclass container of Bluetooth module information

send_raw_icd_command(msg)

Sends a raw ICD command message represented as a list of bytes.

Returns

bytes response from the PFx Brick

PFxBrickBLE

class PFxBrickBLE(dev_dict=None, uuid=None, debug=False)

Inherited sub-class of a PFxBrick object class.

This sub-class of PFxBrick is necessary for communicating with a PFx Brick via Bluetooth LE. Since the Bluetooth communication stack is based on the Bleak python module, it runs in an asynchronous context using python’s async/await mechanisms. Since this requires co-routines instead of conventional function methods, this sub-class reimplements many of the parent PFxBrick class methods as asyncronous co-routines.

Almost all class functionality is more or less the same as the USB based PFxBrick class and fortunately some of the utility methods can be reused.

You can initialize a PFxBrickBLE object instance with either a dictionary or a UUID string that specifies which PFx Brick to connect with.

The dictionary describing the desired PFx Brick peripheral device is as follows:

“address”: hardware address of the PFx Brick obtained by a Bluetooth device scan “serial_no”: optional serial number of the PFx Brick obtained by a device scan “name”: optional name of the PFx Brick device obtained by a device scan

Only the “address” key is mandatory, the other keys are provided if desired.

Alternatively, you can simply initialize the PFxBrickBLE class using a UUID string like the following example:

brick = PFxBrickBLE(uuid=”059930E2-BE75-48A4-B193-3AD3F67246E4”)

Unless the Bluetooth hardware address of the PFx Brick is known in advance, then it must be obtained by performing a Bluetooth peripheral device scan to see which Bluetooth devices are currently advertising availability. The Bluetooth hardware address is operating system dependent and must be provided in a UUID form that is compatible with your OS.

for Windows and Linux this is typically in the form of “24:71:89:cc:09:05” and on macOS it is in the form of “B9EA5233-37EF-4DD6-87A8-2A875E821C46”

Attributes:

dev (device): a device handle which is reference to self

is_open (boolean): a flag indicating connected session status

client (BleakClient): Bleak BLE client object reference

callback_audio_done (func): a function callback reference in response to a PFX_NOTIFICATION_AUDIO_PLAY_DONE notification. Must have the call signature func(fileid, filename)

callback_audio_play (func): a function callback reference in response to a PFX_NOTIFICATION_AUDIO_PLAY notification. Must have the call signature func(fileid, filename)

callback_motora_stop (func): a function callback reference in response to a PFX_NOTIFICATION_MOTORA_STOP notification. Must have the call signature func()

callback_motora_speed (func): a function callback reference in response to a PFX_NOTIFICATION_MOTORA_CURR_SPD notification. Must have the call signature func(speed)

callback_motorb_stop (func): a function callback reference in response to a PFX_NOTIFICATION_MOTORB_STOP notification. Must have the call signature func()

callback_motorb_speed (func): a function callback reference in response to a PFX_NOTIFICATION_MOTORB_CURR_SPD notification. Must have the call signature func(speed)

Parameters

• dev_dict – dict a dictionary describing the PFx Brick device to connect. Must have the key “address” with the Bluetooth MAC address of the PFx Brick. Optional keys “name” and “serial_no” can be provided.

• uuid – str a string representing the UUID/address of the PFx Brick device. This is an alternative to using the dev_dict argument to specify the PFx Brick.

• debug – boolean a flag to enable low level debug logging of Bluetooth session activity

async open(timeout=10)

Opens a BLE communication session with a PFx Brick.

This method is called after this instance has been initialized with a valid Bluetooth address.

Parameters

timeout – float timeout interval (seconds) to wait for an open connection

async close()

Closes a BLE communication session with a PFx Brick.

async get_rssi()

Get a recent measurement of RSSI (received signal strength)

Returns

int or None of signal strength in dBm

async ble_transaction(msg)

Wraps and sends an ICD message via Bluetooth and waits for and returns a corresponding response from the PFx Brick.

Parameters

msg – [int] ICD message to send as an integeter list of bytes

Returns

[int] returned message in a byte array list

async get_icd_rev(silent=False)

Requests the version of Interface Control Document (ICD) the connected PFx Brick supports using the PFX_CMD_GET_ICD_REV ICD message. The resulting version number is stored in this class and also returned.

Parameters

silent (boolean) – flag to optionally silence the status LED blink

Returns

str ICD version, e.g. “3.38”

async get_status()

Requests the top level operational status of the PFx Brick using the PFX_CMD_GET_STATUS ICD message. The resulting status data is stored in this class and can be queried with typical class member access methods or the print_status method.

async get_config()

Retrieves configuration settings from the PFx Brick using the PFX_CMD_GET_CONFIG ICD message. The configuration data is stored in the PFxBrick.config class member variable.

async set_config()

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

It is recommended that the configuration be read from the PFx Brick (using get_config) before any changes are made to the configuration and written back. This ensures that any configuration settings which are not desired to be changed are left in the same state.

async reset_factory_config()

Resets the PFx Brick configuration settings to factory defaults.

async get_name()

Retrieves the user defined name of the PFx Brick using the PFX_CMD_GET_NAME ICD message. The name is stored in the name class variable as a UTF-8 string.

Returns

str user defined name

async set_name(name)

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

Parameters

name – str new name to set (up to 24 character bytes, UTF-8)

async get_action_by_address(address)

Retrieves a stored action indexed by address rather than a combination of eventID and IR channel. The address is converted into a [eventID, IR channel] pair and the get_action method is called with this function as a convenient wrapper.

Parameters

address – int event/action LUT address (0 - 0x7F)

Returns

PFxAction class filled with retrieved LUT data

async get_action(evtID, ch)

Retrieves the stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• channel – int channel index LUT address component (0 - 3)

Returns

PFxAction class filled with retrieved LUT data

async set_action_by_address(address, action)

Sets a new stored action in the event/action LUT at the address specified. The address is converted into a [eventID, IR channel] pair and the set_action method is called with this function as a convenient wrapper.

Parameters

• address – int event/action LUT address (0 - 0x7F)

• action – PFxAction action data structure class

async set_action(evtID, ch, action)

Sets a new stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• ch – int channel index LUT address component (0 - 3)

• action – PFxAction action data structure class

async test_action(action)

Executes a passed action data structure. This function is used to “test” actions to see how they behave. The passed action is not stored in the event/action LUT.

Parameters

action – PFxAction action data structure class

async clear_action_by_address(address)

Clears a stored action in the event/action LUT at the address specified. The address is converted into a [eventID, IR channel] pair and the set_action method is called with this function as a convenient wrapper.

Parameters

address – int event/action LUT address (0 - 0x7F) list,tuple,range specify a list or range of addresses

async clear_action(evtID, ch)

Clears a stored action associated with a particular [eventID / IR channel] event. The eventID and channel value form a composite address pointer into the event/action LUT in the PFx Brick. The address to the LUT is formed as:

Address[5:2] = event ID Address[1:0] = channel

Parameters

• evtID – int event ID LUT address component (0 - 0x20)

• ch – int channel index LUT address component (0 - 3)

async find_startup_action(lightfx=None, soundfx=None, motorfx=None)

Finds a startup action with one or more specified light, motor, or sound fx types.

Parameters

• lightfx – int optional lightfx id

• soundfx – int optional soundfx id

• motorfx – int optional motorfx id

Returns

PFxAction action data structure class matching the desired type(s)

async set_motor_speed(ch, speed, duration=None)

A convenience wrapper for PFxAction().set_motor_speed

Parameters

• ch – [int] a list of motor channels (1-4)

• speed – int desired motor speed (-100 to +100)

• duration – float optional duration (in seconds) to run motor, runs indefinitely if not specified

If the duration value is specified, it represents the desired motor run time in seconds. Note that this value will be rounded to the nearest fixed interval of the DURATION parameter as defined in the ICD ranging between 16 fixed values from 0.5 sec to 5 min.

async stop_motor(ch)

A convenience wrapper for PFxAction().stop_motor

Parameters

ch – [int] a list of motor channels (1-4)

async light_on(ch)

A convenience wrapper for PFxAction().light_on

Parameters

ch – [int] a list of light channels (1-8)

async light_off(ch)

A convenience wrapper for PFxAction().light_off

Parameters

ch – [int] a list of light channels (1-8)

async light_toggle(ch)

A convenience wrapper for PFxAction().light_toggle

Parameters

ch – [int] a list of light channels (1-8)

async set_brightness(ch, brightness)

A convenience wrapper for PFxAction().set_brightness

Parameters

• ch – [int] a list of light channels (1-8)

• brightness – int brightness (0 - 255 max)

async combo_light_fx(fx, param=[0, 0, 0, 0, 0])

A convenience wrapper for PFxAction().combo_light_fx

Parameters

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

async light_fx(ch, fx, param=[0, 0, 0, 0, 0])

A convenience wrapper for PFxAction().light_fx

Parameters

• ch – [int] a list of light channels (1-8)

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

async sound_fx(fx, param=[0, 0], fileID=None)

A convenience wrapper for PFxAction().sound_fx

Parameters

• fx – int desired sound action

• param – [int] a list of up to 2 sound parameters

• fileID – int file ID of an audio file in the file system

async play_audio_file(fileID)

A convenience wrapper for PFxAction().sound_fx

Parameters

fileID – int or str file ID or filename of an audio file in the file system

async stop_audio_file(fileID)

A convenience wrapper for PFxAction().stop_audio_file

Parameters

fileID – int or str file ID or filename of an audio file in the file system

async repeat_audio_file(fileID)

A convenience wrapper for PFxAction().repeat_audio_file

Parameters

fileID – int or str file ID or filename of an audio file in the file system

async set_volume(volume)

A convenience wrapper for PFxAction().set_volume

Parameters

volume – int desired audio volume (0 - 100%)

async refresh_file_dir()

Reads the PFx Brick file system directory. This includes the total storage used as well as the remaining capacity. Individual file directory entries are stored in the PFxBrick.filedir.files class variable.

async put_file(fileID, fn, show_progress=True)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async get_file(fileID, fn=None, show_progress=True)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async remove_file(fileID)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async format_fs(quick=False)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async set_file_attributes(fileID, attr, mask=124)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async rename_file(fileID, new_name)

PFx Brick file system operations not supported over Bluetooth raises NotImplementedError

async stop_script()

Stops all script execution.

async run_script(scriptfile)

Runs a specified script file on the PFx Brick filesystem.

A file is identified either by its numeric file ID (0 - 254) or alphanumeric filename as a string.

Parameters

scriptfile – int or str file ID or file name string

async file_id_from_str_or_int(filespec)

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

A file is identified on the PFx Brick filesystem primarily by its numeric file ID (0 - 254). A file ID of 255 is an invalid or non-existant file. A numeric file ID can be queried using its alphanumeric filename in the filesystem directory. This function performs this lookup if necessary, i.e. if a string filename is provided.

Parameters

filespec – int or str file ID or file name string

Returns

int numeric file ID from PFx Brick filesystem, or 0xFF if not found

async get_current_state()

Returns the current state of the PFx Brick operating parameters.

Returns

PFxState a dataclass container with state information

async get_fs_state()

PFx Brick operation not supported over Bluetooth raises NotImplementedError

async get_bt_state()

PFx Brick operation not supported over Bluetooth raises NotImplementedError

async send_raw_icd_command(msg)

Sends a raw ICD command message represented as a list of bytes.

Returns

bytes response from the PFx Brick

async set_notifications(events)

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

Parameters

events – int a bitwise OR of notification flags:

• PFX_NOTIFICATION_AUDIO_PLAY_DONE = 0x01

• PFX_NOTIFICATION_AUDIO_PLAY = 0x02

• PFX_NOTIFICATION_MOTORA_CURR_SPD = 0x04

• PFX_NOTIFICATION_MOTORA_STOP = 0x08

• PFX_NOTIFICATION_MOTORB_CURR_SPD = 0x10

• PFX_NOTIFICATION_MOTORB_STOP = 0x20

• PFX_NOTIFICATION_TO_USB = 0x80

• PFX_NOTIFICATION_TO_BLE = 0x40

Note that PFX_NOTIFICATION_TO_BLE is automatically set and does not need to be specified.

async disable_notifications()

Disables asynchronous notifications sent from the PFx Brick.

PFxConfig

class PFxConfig(icd_rev=None)

Top level configuration data container class.

This class contains catergorized container classes for groups of related settings. To change a configuration setting, simply access the setting value using a dotted path type notation, e.g. config.lights.startupBrightness[2] = 100

Attributes:

settings (PFxSettings): container for general settings.

motors ([PFxMotor]): list of 4 containers for motor settings

lights (PFxLights): container for default brightness settings

audio (PFxAudio): container for audio related settings

from_bytes(msg)

Converts the message string bytes read from the PFx Brick into the corresponding data members of this class.

to_bytes()

Converts the data members of this class to the message string bytes which can be sent to the PFx Brick.

PFxSettings

class PFxSettings

General settings container class. A member of PFxConfig

This class contains miscellaneous user preference settings such as power saving modes.

Attributes:

statusLED (int): status LED mode

volumeBeep (int): volume beep mode

autoPowerDown (int): auto power down mode

lockoutMode (int): IR lockout activation mode

irAutoOff (int): auto IR disable mode

bleAutoOff (int): auto BLE disable mode

bleMotorWhenDisconnect (int): behaviour of motors on BLE disconnect

bleAdvertPower (int): BLE RF power during advertising

bleSessionPower (int): BLE RF power during connected session

notchCount (int): number of motor index speed notches

notchBounds ([int]): list of monotonic increasing speed notch boundaries

PFxMotor

class PFxMotor

Motor settings container class.

This class contains motor configuration data for one motor channel.

Attributes:

invert (boolean): invert the definition of forward/reverse

torqueComp (boolean): activate low speed torque compensation with low frequency PWM

tlgMode (boolean): enable LEGO® Power Functions compatible PWM mode

accel (int): acceleration factor (0 - 15 max)

decel (int): deceleration factor (0 - 15 max)

vmin (int): speed curve minimum mapped speed (0 -> vmid-1)

vmid (int): speed curve midpoint speed (vmin+1 -> vmax-1)

vmax (int): speed curve maximum mapped speed (vmid+1 -> 255)

PFxLights

class PFxLights

Light settings container class.

This class contains default startup brightness data for every light channel. All brightness values range from 0 (minimum) to 255 (maximum).

Attributes:

defaultBrightness (int): default global brightness, if 0, then individual brightness is used

startupBrightness ([int]): list of 8 individual startup brightness values for each light output

pfBrightnessA (int): startup brightness of PF channel A (when used for lights)

pfBrightnessB (int): startup brightness of PF channel B

pfBrightnessC (int): startup brightness of PF channel C

pfBrightnessD (int): startup brightness of PF channel D

PFxAudio

class PFxAudio

Audio settings container class.

This class contains audio configuration data such as default volume, bass, treble, etc.

Attributes:

audioDRC (boolean): auto Dynamic Range Control (True/False)

bass (int): startup bass EQ (-20 to 20 dB)

treble (int): startup treble EQ (-20 to 20 dB)

defaultVolume (int): startup volume (0 min - 255 max)

PFxDir

class PFxDir

File directory container class.

This class contains PFx file system directory.

Attributes:

numFiles (int): number of files in the file system

files ([PFxFile]): a list of PFxFile objects corresponding to directory entries

bytesUsed (int): bytes occupied by files

bytesLeft (int): remaining space in bytes

get_file_dir_entry(fid)

Returns a file directory entry containined in a PFxFile class.

Parameters

fid (int) – the unique file ID of desired directory entry

Returns

PFxFile directory entry

get_filename(fid)

Returns a filename with a numeric file ID

Parameters

fid (int) – the unique file ID of desired directory entry

Returns

str filename of file ID, or None

find_available_file_id()

Returns the next available unique file ID from the file system.

The directory is scanned for all currently used file ID values and returns an un-used/available file ID value.

Returns

int next available file ID value, or None

has_file(fileID)

Determines if a specified file is on the PFx Brick file system either by filename or numeric file ID.

Returns

boolean True or False if the file is found

__str__()

Convenient human readable string of the file directory. This allows a PFxDir object to be used with str and print methods.

colour_dir()

Convenient human readable string of the file directory with colour.

PFxFile

class PFxFile

File directory entry container class.

This class contains directory entry data for a file on the PFx file system.

Attributes:

id (int): unique file ID

size (int): size in bytes

firstSector (int): the first 4k sector index in flash memory

attributes (int): 16-bit attributes field

userData1 (int): 32-bit user defined data field

userData2 (int): 32-bit user defined data field

crc32 (int): CRC32 hash of the file (auto computed after write)

name (str): UTF-8 filename up to 32 bytes

is_audio_file()

Checks the file attributes to see if this file is a valid audio WAV file.

Returns

True if it is valid audio WAV file

is_script_file()

Checks the file attributes to see if this file is a valid script file.

Returns

True if it is valid script file

has_same_crc32_as_file(other)

Checks if the CRC32 of this file is the same as a specified file on the local filesystem

Returns

True if CRC32 hash codes match

from_bytes(msg)

Converts the message string bytes read from the PFx Brick into the corresponding data members of this class.

__str__()

Convenient human readable string of a file directory entry. This allows a PFxFile object to be used with str and print methods.

colour_str()

Convenient human readable colour string of a file directory entry.

PFxAction

class PFxAction

Action data structure class.

This class reflects the 16 byte data structure used internally by the PFx Brick to execute a composite action of motor, lighting, and sound effects.

Attributes:

command (int): Command byte

motorActionId (int): Motor action ID and motor channel mask byte

motorParam1 (int): Motor parameter 1

motorParam2 (int): Motor parameter 2

lightFxId (int): Light Fx ID byte

lightOutputMask (int): Light channel output mask

lightPFOutputMask (int): Light channel on PF output mask

lightParam1 (int): Lighting parameter 1

lightParam2 (int): Lighting parameter 2

lightParam3 (int): Lighting parameter 3

lightParam4 (int): Lighting parameter 4

lightParam5 (int): Lighting parameter 5

soundFxId (int): Sound Fx ID byte

soundFileId (int): Sound file ID

soundParam1 (int): Sound parameter 1

soundParam2 (int): Sound parameter 2

all_off()

Populates an action to turn off all motors, lights, and sound.

set_motor_speed(ch, speed, duration=None)

Populates an action to set the speed of specified motor channel(s). The motor speed is specified between -100% and +100% where negative values are in the reverse direction and positive values are in the forward direction.

Parameters

• ch – [int] a list of motor channels (1-4)

• speed – int desired motor speed (-100 to +100)

• duration – float optional duration (in seconds) to run motor, runs indefinitely if not specified

Returns

PFxAction self

If the duration value is specified, it represents the desired motor run time in seconds. Note that this value will be rounded to the nearest fixed interval of the DURATION parameter as defined in the ICD ranging between 16 fixed values from 0.5 sec to 5 min.

stop_motor(ch)

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

Parameters

ch – [int] a list of motor channels (1-4)

Returns

PFxAction self

light_on(ch)

Populates an action to turn on selected light outputs.

Parameters

ch – [int] a list of light channels (1-8)

Returns

PFxAction self

light_off(ch)

Populates an action to turn off selected light outputs.

Parameters

ch – [int] a list of light channels (1-8)

Returns

PFxAction self

light_toggle(ch)

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

Parameters

ch – [int] a list of light channels (1-8)

Returns

PFxAction self

set_brightness(ch, brightness)

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

Parameters

• ch – [int] a list of light channels (1-8)

• brightness – int brightness (0 - 255 max)

Returns

PFxAction self

combo_light_fx(fx, param=[0, 0, 0, 0, 0])

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

Parameters

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

Returns

PFxAction self

light_fx(ch, fx, param=[0, 0, 0, 0, 0])

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

Parameters

• ch – [int] a list of light channels (1-8)

• fx – int desired light effect

• param – [int] a list of up to 5 light parameters

Returns

PFxAction self

The details of specifying the light fx and param items is described in detail in the ICD document. The pfx.py file contains convenient pre-defined constants for all of the light effect types and parameter values.

An example of using this method is as follows:

p = [EVT_PERIOD_1S, EVT_DUTYCY_10, EVT_BURST_COUNT_2, EVT_TRANSITION_TOGGLE]
a = PFxAction().light_fx([1,4], EVT_LIGHTFX_STROBE_P, p)

This specifies a strobe light effect on channels 1 and 4 with a 1 second period, 10% duty cycle, two light pulses and with a toggle activation.

sound_fx(fx, param=[0, 0], fileID=None)

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

Parameters

• fx – int desired sound action

• param – [int] a list of up to 2 sound parameters

• fileID – int file ID of an audio file in the file system

Returns

PFxAction self

The details of specifying the sound fx and param items is described in detail in the ICD document. The pfx.py file contains convenient pre-defined constants for all of the sound effect types and parameter values.

An example of using this method is as follows:

p = [EVT_SOUND_DUR_10S]
a = PFxAction().sound_fx(EVT_SOUND_PLAY_DUR, p, 5)

This specifies an action to playback an audio file with ID=5 for a fixed duration of 10 seconds.

play_audio_file(fileID)

Populates an action to play an audio file once.

Parameters

fileID – int file ID of an audio file in the file system

Returns

PFxAction self

This is a convenience wrapper for the sound_fx method.

stop_audio_file(fileID)

Populates an action to stop playback of an audio file.

Parameters

fileID – int file ID of an audio file in the file system

Returns

PFxAction self

This is a convenience wrapper for the sound_fx method.

repeat_audio_file(fileID)

Populates an action for repeated playback of an audio file.

Parameters

fileID – int file ID of an audio file in the file system

Returns

PFxAction self

This is a convenience wrapper for the sound_fx method.

set_volume(volume)

Populates an action to set the audio volume.

Parameters

volume – int desired audio volume (0 - 100%)

Returns

PFxAction self

This is a convenience wrapper for the sound_fx method.

is_empty()

Determines if the action is clear/undefined

clear()

Sets all the action data in this class to zero.

from_bytes(msg)

Converts the message string bytes read from the PFx Brick into the corresponding data members of this class.

to_bytes()

Converts the data members of this class to the message string bytes which can be sent to the PFx Brick.

verbose_line_str(brick)

Human readable string of action object in single line.

Parameters

brick – PFxBrick reference to a PFx Brick in order to query filename

__str__()

Convenient human readable string of the action data structure. This allows a PFxAction object to be used with str and print methods.

PFxState

class PFxState

PFx Brick internal data state container class.

This class is used to store internal state data obtained with the PFX_CMD_GET_CURRENT_STATE ICD command. This internal state data can be useful for monitoring, debugging, and for building apps which can use this data for enhanced feedback of the PFx Brick runtime state and behaviour.

Attributes:

brightness (int): current global brightness value

volume (int): current audio volume level

millisec_count (int): PFx Brick millisecond counter value

slow_count (int): PFx Brick 1 second counter value

status_latch1 (int): PFx Brick status latch 1 bit flag state

status_latch2 (int): PFx Brick status latch 2 bit flag state

audio_peak (int): current audio peak level based on current playback

audio_notch (int): current motor notch value for indexed audio playback

fs_state (int): PFx Brick file system state flags

script_state (int): PFx Brick script engine state

script_line (int): current running script line pointer

motors ([PFxMotorState]): motor channel runtime state container class

lights ([PFxLightState]): light channel runtime state container class

audio_ch ([PFxAudioChannel]): audio channel runtime state container class

from_bytes(msg)

Converts the message string bytes read from the PFx Brick into the corresponding data members of this class.

__str__()

Return str(self).