A python API for host control of USB connected PFx Bricks.
Project description
PFx Brick Python API
This repository contains a python package API for developing python scripts and applications which communicate with the PFx Brick. This package supports both USB and Bluetooth LE connections to the PFx Brick and is supported for Windows, macOS and linux.
Getting Started
OS Requirements
- Supports Windows 10, version 16299 (Fall Creators Update) or greater
- Supports Linux distributions with BlueZ >= 5.43
- OS X/macOS support via Core Bluetooth API, from at least OS X version 10.11
Installation
Pre-install System requirements for linux
The pfxbrick package will require some packages to be installed suport access to USB and Bluetooth hardware drivers. Use your preferred package manager to install these packages:
- libhidapi-dev
- libudev-dev
- libusb-1.0-0-dev
- bluez
- bluetooth
- libbluetooth-dev
Pre-install System requirements for macOS
It is recommended to use the brew package manager to install the packages for USB hardware access. (Hardware support for Bluetooth will automatically be installed with pfxbrick setup.py
install script which installs the bleak package with its dependency to pyobjc-framework-CoreBluetooth
).
$ brew install hidapi
Installation with pip
The pfxbrick package can be installed with pip:
$ pip install pfxbrick
Install from source
Install directly from the source code with the setup.py
script:
$ git clone https://github.com/fx-bricks/pfx-brick-py.git
$ cd pfx-brick-py
$ python setup.py install
Conda Virtual Environment
You can also use the package in a standalone conda virtual environment. To create a conda environment named pfxtest
:
$ git clone https://github.com/fx-bricks/pfx-brick-py.git
$ cd pfx-brick-py
$ conda env create -f environment.yml
$ conda activate pfxtest
$ pip install -r requirements.txt
$ python setup.py install
Basic Usage
After installation, the package can imported:
$ python >>> import pfxbrick >>> pfxbrick.__version__
An example of the package can be seen below
import time from pfxbrick import * # Open a PFx Brick session instance brick = PFxBrick() brick.open() # Get the PFx Brick configuration settings brick.get_config() brick.print_config() # Get the user defined name of the PFx Brick brick.get_name() print(brick.name) # Change the user defined name brick.set_name('My Cool Brick') # Turn on some lights for 5 sec brick.light_on([1, 2, 7, 8]) time.sleep(5) brick.light_off([1, 2, 7, 8]) # Set motor channel A to 50% speed gradually for speed in range(50): brick.set_motor_speed([1], speed) time.sleep(0.1) brick.stop_motor([1]) # Play an audio file with indefinite repeat brick.repeat_audio_file("LongBeep1") time.sleep(5) brick.stop_audio_file("LongBeep1") # End the session brick.close()
Utility Scripts
The pfxbrick package will install some useful command line script applications in your python environment’s path. These include:
pfxcat
- dumps the raw contents of a file on the PFx Brick to your console.pfxdir
- shows the directory listing of the PFx Brick file systempfxget
- gets a file from the PFx Brickpfxput
- copies a local host file on to the PFx Brickpfxrm
- delete a file from the PFx Brickpfxrename
- renames a file on the PFx Brickpfxdump
- dumps raw contents of PFx Brick flash memorypfxinfo
- discovers and shows information on all attached PFx Brickspfxmonitor
- shows real time operational status of a PFx Brickpfxtest
- PFx Brick self test utilitypfxplay
- plays an audio file on the PFx Brickpfxrun
- runs a script a file on the PFx Brickpfxscan
- scans for Bluetooth PFx Bricks and shows each brick’s information
After installing the pfxbrick package, you should be able to use any of these utilities directly from the command line as follows:
$ pfxinfo ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ A216 PFx Brick 16 MB ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ Serial Number : AF716069 │ │ ICD Version : 03.38 │ │ Firmware Version : 01.50 build 0555 │ │ USB vendor ID : 0x04D8 │ │ USB product ID : 0xEF74 │ │ Status : 0x00 Normal │ │ Errors : 0x00 None │ │ Name : My PFx Brick │ └──────────────────────────────────────────────────────────────────────────┘ $ pfxdir ID Name Size Attr User1 User2 CRC32 0 sin150Hz.wav 132.3 kB 0000 000204CE 0000002C A712A54E 1 pink6dB.wav 132.3 kB 0000 000204CE 0000002C E6AACE61 2 files, 270.3 kB used, 16490.5 kB remaining
To find out more information on how to use each utility, use without arguments or with the -h
argument.
$ pfxinfo -h usage: pfxinfo [-h] [-c] Show information for all attached PFx Bricks optional arguments: -h, --help show this help message and exit -c, --config Show configuration details
Documentation
- PFx Brick Interface Control Document (ICD) v.3.39 describes details of PFx Brick operation and communication protocol
- Python API Reference Documentation
If you want to learn more about PFx Brick, check out our website.
Change Log
v.0.8.6
- improved Bluetooth scanning and device discovery (thanks to a PR from @aholzel)
- added new pfxscan command line utility
v.0.8.5
- support for new ICD revision v.3.39
- updates to the scripts and documentation
v.0.8.4
- updated command line scripts to use argparse
- added new GitHub test actions
v.0.8.3
- updated command line scripts to install using setuptools console_scripts for better platform compatibility
v.0.8.1
- bug fixes
v.0.8.0
- all new support added for v.3.38 of ICD
- support for v.1.50+ firmware which conforms to v.3.38 ICD
- added command line utility scripts which are installed into the python path
- revised documentation
v.0.7.1
- revised documentation
- improved BLE notifcation callbacks
v.0.7.0
- added Bluetooth LE connection access with same functionality as USB
- added convenience methods to PFxBrick class to execute actions directly
- added support for running scripts on PFx Brick
v.0.6.2
- fixed error reporting for file system access methods
- fixed file directory refresh to ignore empty directory entries
v.0.6.1
- changed the USB write function to ensure consistent cross-platform compatibility
v.0.6.0
- finished implementing missing functionality
- finished documentation
- first public announced release
v.0.5.1
- Added CHANGELOG.rst to project manifest
v.0.5.0
- Initial release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.