Class Reference

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

PFxBrick

std::vector<std::string> find_bricks(bool show_list = false)

Enumerates all attached PFx Bricks.

This function finds all PFx Bricks attached to the current host’s USB subsystem. Since all PFx Bricks have unique serial number, this function returns a vector string array of the serial numbers of discovered PFx Bricks.

Parameters

• show_list: optionally specifies that a listing of found PFx Bricks be printed to the console

class PFxBrick

PFx Brick top level 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.

Public Functions

bool open(std::string ser_no)

Open a session with a PFx Brick.

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.

Return

boolean indicating open session result

Parameters

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

bool open(void)

Opens a USB communication session with a single PFx Brick. This is a convenience method for quickly connecting to the only PFx Brick that is currently connected to the host.

Return

boolean indicating open session result

void close()

Closes a session with a PFx Brick.

Closes a USB communication session with a PFx Brick.

void get_icd_rev(bool silent = false)

Gets the revision number of ICD the PFx Brick supports.

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: flag to optionally silence the status LED blink

void get_status()

Gets identity and status info from the PFx Brick.

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.

void print_status()

Prints the status info retrieved by get_status.

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

void get_config()

Gets PFx Brick configuration.

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.

void print_config()

Prints the configuration retrieved by get_config.

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

void set_config()

Writes new configuration to the PFx Brick.

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.

void get_name()

Gets the user defined name of the PFx Brick.

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.

Return

a string with the user defined name

void set_name(std::string name)

Sets a new user define PFx Brick name.

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

Parameters

• name: new name to set (up to 24 character bytes, UTF-8)

PFxAction &get_action_by_address(int address, PFxAction &action)

Gets an action data structure by 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.

Return

PFxAction class filled with retrieved LUT data

Parameters

• address: event/action LUT address (0 - 0x7F)

PFxAction &get_action(int evtID, int ch, PFxAction &action)

Gets an action data structure by event ID.

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

Return

PFxAction class filled with retrieved LUT data

Parameters

• evtID: event ID LUT address component (0 - 0x20)
• channel: channel index LUT address component (0 - 3)

void set_action_by_address(int address, const PFxAction &action)

Sets an a new action in the event/action LUT by address.

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: event/action LUT address (0 - 0x7F)
• action: PFxAction action data structure class

void set_action(int evtID, int ch, const PFxAction &action)

Sets a new action in the event/action LUT by event ID.

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: event ID LUT address component (0 - 0x20)
• ch: channel index LUT address component (0 - 3)
• action: PFxAction action data structure class

void test_action(const PFxAction &action)

Executes a passed action data structure.

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

void refresh_file_dir()

Reads the PFx Brick file system directory.

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.

void put_file(int fileID, std::string fn, bool show_progress = true)

Copies a file to the PFx Brick.

Copies a file from the host to the PFx Brick.

Parameters

• fileID: the unique file ID to assign the copied file in the file system
• fn: the filename (optionally including the path) of the file to copy
• show_progress: a flag to show the progress bar indicator during transfer.

void get_file(int fileID, std::string fn, bool show_progress = true)

Copies a file from the PFx Brick.

Copies a file from the PFx Brick to the host.

Parameters

• fileID: the file ID of the file to copy
• fn: optional override for the filename when copied into the host
• show_progress: a flag to show the progress bar indicator during transfer.

void remove_file(int fileID)

Deletes a file on the PFx Brick file system.

Removes a file from the PFx Brick file system.

Parameters

• fileID: the file ID of the file to remove

void format_fs(bool quick = false)

Format the PFx Brick file system.

Formats the PFx Brick file system, erasing all files.

Parameters

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

void reset_factory_config()

Reset PFx Brick to factory default configuration.

Resets the PFx Brick configuration settings to factory defaults.

Public Members

PFxDev dev

a child class to hold the device handle and data buffers

PFxConfig config

child class to store configuration and settings

PFxDir filedir

child class to store the file system directory

std::string product_id

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

std::string serial_no

serial number reported by the PFx Brick, usually 8 digit hexadecimal

std::string product_desc

product descriptor reported by the PFx Brick

std::string firmware_ver

firmware version number reported 4-digit hex BCD, e.g. ‘0134’ represents v.1.34

std::string firmware_build

firmware build number reported, 4-digit hex BCD

std::string icd_rev

ICD revision number reported 4-digit hex BCD, e.g. ‘0336’ represents v.3.36

int status

status code reported, distinguishes normal and service/recovery mode

int error

error code reported

int usb_vid

fixed to PFX_USB_VENDOR_ID representing the official USB VID assigned to the PFx Brick

int usb_pid

fixed to PFX_USB_PRODUCT_ID representing the official USB PID assigned to the PFx Brick

std::string usb_manu_str

the manufacturer string reported to the host USB interface

std::string usb_prod_str

the product descriptor string reported to the host USB interface

std::string usb_serno_str

the product serial number string reported to the host USB interface

bool is_open

a flag indicating connected session status

std::string name

user defined name of the PFx Brick

PFxConfig

class PFxConfig

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

Public Functions

void from_bytes(unsigned char *msg)

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

Parameters

• msg: pointer to message bytes array

void to_bytes(unsigned char *msg)

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

Parameters

• msg: pointer to message bytes array

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

PFxSettings settings

container for general settings

PFxLights lights

container for default brightness settings

PFxAudio audio

container for audio related settings

PFxMotor motors[PFX_MOTOR_CHANNELS_MAX]

an array of up to 4 containers for motor settings

PFxSettings

class PFxSettings

General settings container class. A member of PFxConfig

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

Public Functions

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

int statusLED

status LED mode

int volumeBeep

volume beep mode

int autoPowerDown

auto power down mode

int lockoutMode

IR lockout activation mode

int irAutoOff

auto IR disable mode

int bleAutoOff

auto BLE disable mode

int bleMotorWhenDisconnect

behaviour of motors on BLE disconnect

int bleAdvertPower

BLE RF power during advertising

int bleSessionPower

BLE RF power during connected session

int notchCount

number of motor index speed notches

int notchBounds[8]

list of monotonic increasing speed notch boundaries

PFxMotor

class PFxMotor

Motor settings container class. This class contains motor configuration data for one motor channel.

Public Functions

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

bool invert

invert the definition of forward/reverse

bool torqueComp

activate low speed torque compensation with low frequency PWM

bool tlgMode

enable LEGO® Power Functions compatible PWM mode

int accel

acceleration factor (0 - 15 max)

int decel

deceleration factor (0 - 15 max)

int vmin

speed curve minimum mapped speed (0 -> vmid-1)

int vmid

speed curve midpoint speed (vmin+1 -> vmax-1)

int vmax

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).

Public Functions

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

int defaultBrightness

default global brightness, if 0, then individual brightness is used

int startupBrightness[PFX_LIGHT_PORTS]

list of 8 individual startup brightness values for each light output

int pfBrightnessA

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

int pfBrightnessB

startup brightness of PF channel B

int pfBrightnessC

startup brightness of PF channel C

int pfBrightnessD

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.

Public Functions

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

bool audioDRC

enable auto Dynamic Range Control

int bass

startup bass EQ (-20 to 20 dB)

int treble

startup treble EQ (-20 to 20 dB)

int defaultVolume

startup volume (0 min - 255 max)

PFxDir

class PFxDir

File directory container class.

This class contains PFx file system directory.

Public Functions

PFxFile *get_file_dir_entry(int fid)

Returns a file directory entry containined in a PFxFile class.

Return

a pointer to a PFxFile directory entry

Parameters

• fid: the unique file ID of desired directory entry

void Clear()

Clear the file directory array PFxFile *files

void Reallocate(int newLength)

Reallocate the file directory array of PFxFile *files

Parameters

• newLength: the new size of the file directory

void Resize(int newLength)

Resize the file directory array of PFxFile *files

Parameters

• newLength: the new size of the file directory

void InsertBefore(const PFxFile &withFile, int atIdx)

Insert a new PFxFile entry into the directory

Parameters

• withFile: a PFxFile entry to insert
• atIdx: the index where the new entry is inserted

void Remove(int atIdx)

Remove the specified PFxFile entry from the directory

Parameters

• atIdx: the index of the PFxFile to remove

void InsertAtBeginning(const PFxFile &withFile)

A convenient wrapper for InsertBefore to add a new PFxFile entry at the beginning of the directory

Parameters

• withFile: the PFxFile entry to insert

void InsertAtEnd(const PFxFile &withFile)

A convenient wrapper for InsertBefore to add a new PFxFile entry at the end of the directory

Parameters

• withFile: the PFxFile entry to insert

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

unsigned int numFiles

number of files in the file system

unsigned long bytesUsed

bytes occupied by files

unsigned long bytesLeft

remaining space in bytes

PFxFile *files

a list of PFxFile objects corresponding to directory entries

PFxFile

class PFxFile

File directory entry container class.

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

Public Functions

bool is_audio_file()

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

Return

True if it is valid audio WAV file

void from_bytes(unsigned char *msg)

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

Parameters

• msg: pointer to message bytes array

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

Public Members

unsigned int id

unique file ID

unsigned long size

size in bytes

unsigned int firstSector

the first 4k sector index in flash memory

unsigned int attributes

16-bit attributes field

unsigned long userData1

32-bit user defined data field

unsigned long userData2

32-bit user defined data field

unsigned long crc32

CRC32 hash of the file (auto computed after write)

std::string name

UTF-8 filename up to 32 bytes

bool fs_error_check(int res_code)

Convenience error status lookup function used by other file system functions.

Return

true if there is an error, false on success

Parameters

• res: result status code byte returned by almost all file system ICD messages

void fs_format(PFxDev &dev, bool quick = false)

Sends an ICD message to format the PFx Brick file system.

Parameters

• dev: PFxDev reference containing the USB HID session handle
• quick: If true, only occupied sectors are erased. If false, every sector is erased, i.e. a complete format.

void fs_remove_file(PFxDev &dev, int fid)

Sends an ICD message to remove a file from the PFx Brick file system.

Parameters

• dev: PFxDev reference containing the USB HID session handle
• fid: the file ID of the file to remove

void fs_copy_file_to(PFxDev &dev, int fid, std::string fn, bool show_progress = true)

File copy handler to put a file on the PFx Brick.

This function handles the process of opening and transferring file data from the host to the PFx Brick file system. A copy session may involve many message transactions with the PFx Brick and could be time consuming. Therefore, a progress bar can be optionally shown on the console to monitor the transfer.

Parameters

• dev: PFxDev reference containing the USB HID session handle
• fid: a unique file ID to assign the copied file
• fn: the host filename (optionally including path) to copy
• show_progress: a flag to show the progress bar indicator during transfer

void fs_copy_file_from(PFxDev &dev, const PFxFile &file, std::string fn = "", bool show_progress = true)

File copy handler to get a file from the PFx Brick.

This function handles the process of opening and transferring file data from the PFx Brick file system to the host. A copy session may involve many message transactions with the PFx Brick and could be time consuming. Therefore, a progress bar can be optionally shown on the console to monitor the transfer.

Parameters

• dev: PFxDev reference containing the USB HID session handle
• file: a PFxFile object specifying the file to copy
• fn: optional name to override the filename of the host’s copy
• show_progress: a flag to show the progress bar indicator during transfer

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.

Public Functions

void Print()

Prints the contents of this class in human readable form using formatted printf statements.

PFxAction &set_motor_speed(std::string ch, int speed, double duration)

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.

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.

Return

a PFxAction reference to this instance

Parameters

• ch: a list of motor channels as a string, e.g. “A”, “1, 2”, “AB” are all valid
• speed: desired motor speed (-100 to +100)
• duration: optional duration (in seconds) to run motor, runs indefinitely if set to 0

PFxAction &set_motor_speed(std::string ch, int speed)

Convenience wrapper for set_motor_speed with no duration value specified.

PFxAction &stop_motor(std::string ch)

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

Return

a PFxAction reference to this instance

Parameters

• ch: a list of motor channels as a string, e.g. “A”, “1, 2”, “AB” are all valid

PFxAction &light_on(std::string ch)

Populates an action to turn on selected light outputs.

Return

a PFxAction reference to this instance

Parameters

• ch: a list of light channels as a string, e.g. “1”, “3, 6”, “4567” are all valid

PFxAction &light_off(std::string ch)

Populates an action to turn off selected light outputs.

Return

a PFxAction reference to this instance

Parameters

• ch: a list of light channels as a string, e.g. “1”, “3, 6”, “4567” are all valid

PFxAction &light_toggle(std::string ch)

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

Return

a PFxAction reference to this instance

Parameters

• ch: a list of light channels as a string, e.g. “1”, “3, 6”, “4567” are all valid

PFxAction &set_brightness(std::string ch, int brightness)

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

Return

a PFxAction reference to this instance

Parameters

• brightness: desired brightness (0 - 255 max)

PFxAction &combo_light_fx(int fx, std::vector<int> param)

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

Return

a PFxAction reference to this instance

Parameters

• fx: desired light effect
• param: a vector of up to 5 light parameters

PFxAction &light_fx(std::string ch, int fx, std::vector<int> param)

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

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

Return

a PFxAction reference to this instance

Parameters

• ch: a list of light channels as a string, e.g. “1”, “3, 6”, “4567” are all valid
• fx: desired light effect
• param: a vector of up to 5 light parameters

An example of using this method is as follows::

std::vector<int> p(4);    
p[0] = EVT_PERIOD_1S;
p[1] = EVT_DUTYCY_10;
p[2] = EVT_BURST_COUNT_2;
p[3] = EVT_TRANSITION_TOGGLE;
PFxAction 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.

PFxAction &sound_fx(int fx, std::vector<int> param, int fileID)

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

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

Return

a PFxAction reference to this instance

Parameters

• fx: desired sound action
• param: a vector of up to 2 sound parameters
• fileID: file ID of an audio file in the file system

An example of using this method is as follows::

std::vector<int> p(1);    
p[0] = EVT_SOUND_DUR_10S;
PFxAction 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.

PFxAction &play_audio_file(int fileID)

Populates an action to play an audio file once.

This is a convenience wrapper for the sound_fx method.

Return

a PFxAction reference to this instance

Parameters

• fileID: file ID of an audio file in the file system

PFxAction &stop_audio_file(int fileID)

Populates an action to stop playback of an audio file.

This is a convenience wrapper for the sound_fx method.

Return

a PFxAction reference to this instance

Parameters

• fileID: file ID of an audio file in the file system

PFxAction &repeat_audio_file(int fileID)

Populates an action for repeated playback of an audio file.

This is a convenience wrapper for the sound_fx method.

Return

a PFxAction reference to this instance

Parameters

• fileID: file ID of an audio file in the file system

PFxAction &set_volume(int volume)

Populates an action to set the audio volume.

This is a convenience wrapper for the sound_fx method.

Return

a PFxAction reference to this instance

Parameters

• volume: desired audio volume (0 - 100%)

void to_bytes(unsigned char *msg) const

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

Parameters

• msg: pointer to message bytes array

void from_bytes(unsigned char *msg)

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

Public Members

int command

Command byte

int motorActionId

Motor action ID and motor channel mask byte

int motorParam1

Motor parameter 1

int motorParam2

Motor parameter 2

int lightFxId

Light Fx ID byte

int lightOutputMask

Light channel output mask

int lightPFOutputMask

Light channel on PF output mask

int lightParam1

Lighting parameter 1

int lightParam2

Lighting parameter 2

int lightParam3

Lighting parameter 3

int lightParam4

Lighting parameter 4

int lightParam5

Lighting parameter 5

int soundFxId

Sound Fx ID byte

int soundFileId

Sound file ID

int soundParam1

Sound parameter 1

int soundParam2

Sound parameter 2