PoKeys library PoKeysLib

PoKeys library PoKeysLib

PoKeys library PoKeysLib is a free (open-source) cross-platform library for PoKeys devices that allows the communication with PoKeys devices on various operating systems (including Windows, Linux, UNIX etc.). It even allows the use of PoKeys devices on embedded systems (Raspberry Pi, Beaglebone etc.).

The library is available at PoKeysLib repository at Bitbucket

PoKeys library PoKeysLib usage philosophy

The library was designed to be as portable as possible and uses only basic C language features. It is designed to be used with multiple PoKeys devices at the same time with each device described by a single structure named sPoKeysDevice. All functions in the library are prefixed with PK_ (PoKeys) and usually have the following wording: PK_{peripheral}{setting}{operation}, where {peripheral} can be any of the Device, Pin, DigitalIO, Encoder, PWM, LCD etc., allowing a clear understanding of what each function does.

The structure sPoKeysDevice is created at the moment of establishing a connection with PoKeys device and contains all vital information for communication with the device and device’s settings, values etc. Most functions exchange data between the fields of the sPoKeysDevice structure and PoKeys device directly, while some have additional function parameters that aid in understanding of functions’ operations. In order to communicate with multiple PoKeys devices at a time, a separate sPoKeysDevice structure is created for each device, allowing a very straight-forward (object-oriented-programming-like) approach to addressing multiple devices.

Functionality

The PoKeysLib library contains all major functions supported by PoKeys devices. The library is being actively used and developed by PoLabs, since it is a major part of the PoBlocks graphical programming environment (for the functionality of a Programmable Logic Controller) and PoKeys plugin for Mach4, that allows the PoKeys device to be used as a USB CNC controller or as Ethernet CNC controller (depends on the device type).

Dependencies

The library uses integrated support for communication with PoKeys devices on Windows (via networking, HID and WinUSB drivers) and requires no additional components to be installed. On Linux and UNIX, libusb-1.0 library is used to communicate with USB PoKeys devices.

Installation of PoKeys library PoKeysLib

Using the binaries

Both static (.lib) and dynamic (.dll) precompiled binary files of the library are provided for Windows platform and can be used directly in the target application.

Compiling the library on Windows

The library can be compiled into a static or dynamically linked library format, depending on the requirements of the target application. When compiling, the following libraries must be linked against: setupapi.lib, Ws2_32.lib and iphlpapi.lib with the following linker command -lsetupapi -lWs2_32 -liphlpapi

The PoKeysLib library files can also be included directly as source files in the target application if required.

Compiling the library on Linux

On Linux-based operating systems, libusb-1.0 (package libusb-1.0.0-dev) must be installed prior to compiling the PoKeysLib libraries. To compile the libraries, execute the following command from the terminal

make -f Makefile.noqmake install

This will compile the library and install the library files to the system’s libraries folder (start the command with sudo for the script to be able to copy the files to the destination folder).

When compiling the library or application that uses the library, the libusb-1.0 library must be linked agains by using the linker command -lusb-1.0

The PoKeysLib library files can also be included directly as source files in the target application if required.

Compiling the library on UNIX

On UNIX-based operating systems, libusb-1.0 must also be installed prior to compiling the PoKeysLib libraries. To compile the PoKeysLib library on OS X, execute the following command from the terminal

make -f Makefile.noqmake.osx install

This will compile the library and install the library files to the system’s libraries folder.

When compiling the library or application that uses the library, the libusb-1.0 library must be linked agains by using the linker command -lusb-1.0

The PoKeysLib library files can also be included directly as source files in the target application if required.

Python wrapper

Python logo

Python wrapper for PoKeys PoKeysLib library is available

A Python wrapper is provided in the PoKeysLib repository together with precompiled dynamically linked library for Windows operating system (Microsoft Visual C++ 2010 Redistributable Package (x86) must be installed for the library to function). The wrapper is contained within PoKeys.py file and requires no separate installation.

To use the Python wrapper, import the contents of the PoKeys wrapper first, then initialize the PoKeysDevice class for each device you want to communicate with (in case of multiple PoKeys devices). The initialization of PoKeysDevice class requires the reference to the PoKeysLib DLL file, as shown below. The wrapper contains functions from the PoKeys library PoKeysLib with identical naming convention, as was described above. Some functions were updated for even easier calling from Python (e.g. functions for communication over I2C and SPI interfaces).

from PoKeys import *
# Load PoKeysLib dll library and list all PoKeys devices detected
mydevice = PoKeysDevice("PoKeysLib.dll")
print("List of detected devices:")
mydevice.ShowAllDevices()

# Connect to a specific PoKeys device
print("Connecting to the selected device...")
if mydevice.PK_ConnectToDeviceWSerial(deviceSerial) != 0:
    print("Device not found, quitting!")
    sys.exit(0)

See the Python folder in the PoKeys PoKeysLib library repository at PoKeysLib repository at Bitbucket for more details and examples.