To learn to write software for the Barrett Hand, Barrett recommends the following course.
Additional documentation that the user should find helpful:
This documentation applies to both the 262 and 280 hand.
The BarrettHand API consists of a C++ class that provides the user with a convenient program interface to the BarrettHand. It is a typical C++ library, providing a class BHand, from which an application may instantiate BHand objects. This instantiated object will make Supervisory and RealTime control methods available for your particular hand that is connected to your PC. Serial supports communication with multiple hands although with CAN only one of the newer BH8-280 hands may be controlled at a time due to limitations of the newer drivers.
Users are encouraged to become familiar with the API in order, starting with
The API uses a multithreaded mechanism that allows Supervisory commands to run with non-blocking method calls. Calls to non-blocking methods run asynchronous and always return immediately. The default behavior of the API is to have commands execute synchronously or one after another. This mode means that calls to commands will block until they are complete. Blocking calls to commands are simpler to use so they are recommended but they will often take time away from the running thread. This can cause the application to have higher response times.
Supervisory commands are the general name for sequentially run hand communication methods. Examples of these are methods such as the high-level open and close commands, which belong to the set of motor movement commands. There are initialization commands, property Get/Set commands, and some miscillaneous commands. One of the miscillaneous commands is able to execute commands from the GCL (grasper common language) that takes an input string and may fill a character buffer with a command result depending on the command executed. This special command is not known until Run-Time. The command string is parsed and processed by a 262 hand or by the API for a 280 hand.
Calling supervisory methods asynchronously is possible in the API. This is a feature that makes programming the hand easier for some situations. The intermediate representation for supervisory commands and the multithreaded nature of the API makes this possible. Briefly, the API handles this as described for a few different commands. All data required to execute commands is stored for each API command (e.g. step size for step open/close or positions for a GotoPosition command). A request is made to a high priority communications thread to execute each command. The low-level thread waits for such command requests and then communicates the command to the hand. Results from running previous commands will remain available until after receiving a notification from a callback method or polling to find out if the command is finished. Also, some commands such as init hand take a good deal of time and blocking the application until finished is undesirable.
As expected, a few of the functions and parameters, including those for multithreading, are advanced and segregated in this documentation. While they are documented for completeness, we recommend avoiding use of these commands or changing the parameter defaults. Describing the basics of multithreaded processing is beyond the scope of this documentation. We refer the reader to the extensive documentation provided on the Web with a keyword search like "Multithreaded Programming".
The software architecture is designed with the intention that the user will be using the BHand object almost exclusively. It is highly recommended to stick to using the public methods that the BHand instance offers. The API is structured for BHand and future updates. Keep this in mind if modifying the API. Barrett reserves the right to change the structure internally whenever needed but aims to provide a high level of backwards compatibility as well. With that in mind, we move on to describing the hand software architecture.
The BarrettHand API is able to communicate Supervisory commands to the hand or have RealTime control of the fingers and/or spread. The following is a top-down view of the BHand class, which is useful to understand how the API works. The BHandSupervisoryRealtime class is inheritted by BHand, incorporates the multithreaded mechanism that allows non-blocking supervisory commands in the API, and provides supervisory and RealTime control modes for the hand. The next level down uses an abstract hardware communications interface provided by BHandDriver. There are hardware drivers for both serial and CAN which communicate command requests and receive responses. The hardware drivers are implementations that provide the same interface for running methods and intend to provide as much of the same functionality as possible. Presently, the only hardware communication classes implementing the BHandDriver interface are BHandCANDriver and BHandSerialDriver.
Properties contain values that determine the state of the hand or motor controllers contained in the hand. Earlier documentation called BarrettHand properties parameters instead. In the BH8-262 hand parameters are either "global" or "motor" based. Parameters have been renamed and are now referred to as properties. The 280 hand has only "motor" properties since there is no longer a single processor. Refer to the user manual for information on the feature set of each of the Barrett hands.
Information is stored on the different BarrettHand models such as the known properties. Property values are stored in the hand and are described in the API by attributes. Attributes contain data that is useful such as property names, a description, the range of possible values, etc. It is important to set the correct hardware description before using a BarrettHand instance so that the min/max range attributes may be used to validate values for certain commands. The hand has static methods available to be able to query how many hardware descriptions there are and obtain pointers to them. The user has to set the hardware description for each hand instance. The example programs that are installed as part of the BarrettHand SDK show how to do this. Refer to the README file to compile and run these example programs.
Many functions in the API return an integer status code. If the BarrettHand command needs to return a value and a status code then the API function will require a pointer to the return value passed as a parameter. Commands that do not pass status codes are identified in their descriptions. A return value of zero indicates successful completion. Positive status codes are sent by the firmware; the API generates negative status codes. See Status and Error Codes for more information on status codes. Note that, most supervisory methods and the main RTUpdate for the BH8-280 hand do not return useful error codes, however, it is recommended to get in the habbit of checking for success noted by zero and failure as non-zero. Users are urged to check documentation for particalular methods and beware that asynchronous mode changes status codes. Supervisory methods may return BHERR_PENDING, a negative API error code, because commands have not been completed yet.
The BarrettHand API is organized into three layers of processing: low, intermediate, and high-level:
The design goal behind this layered organization is the following:
Low-level processing allows the hardware communication to have priority over all other tasks, such as refreshing windows, disk read/write, or other user program processing. Delays are minimized and no characters are lost between the host computer and the BarrettHand. At the same time we do not want the user program to run with high priority, because it will execute many other operations unrelated to hardware communication, running all of them with high priority. This would significantly increase the response time of the operating system. Note that some programs should be given the RealTime process priority to ensure that the low-level thread is scheduled to run with more deterministic behavior. Options to increase process priority are found in Windows task manager.
The intermediate-level processing provides both synchronous and asynchronous communication modes for user programs, allowing you to send commands to the BarrettHand and have the option to wait for a response or continue with the program. The multithreaded mechanism allows the user to select between having either blocking or non-blocking API commands. This is not possible with most APIs since they usually focus on one or the other exclusively. The amount of complexity with providing non-blocking initialization and for supervisory commands is justified to provide the programmer with a simpler means to develop applications without using multithreading themselves.
The high-level processing uses the functionality of both the low-level and intermediate-level processing. This approach allows completely different low-level hardware communication implementations, it reuses the intermediate-level processing with device independent supervisory command representation and multithreaded mechanism, and provides functionality through the same high-level interface.
The remaining part of this section describes the three levels in bottom-up order. It closely follows the structure of the BHandSupervisoryRealtime class declaration.
Low-level processing performs the communication between the BarrettHand and the host computer. This level is transparent, but is included so that you can better understand the API. This process runs in a separate thread and is given the highest priority. The following function performs low-level hand communication.
void run()
The BHandSupervisoryRealtime class implements the POCO Runnable interface that provides an entry point for a BarrettHand thread. See POCO C++ Libraries for more information on the POCO library. This thread is started during the contruction of the BHandSupervisoryRealtime object and contains a single loop, which detects communication requests and executes them. The synchronization between the low-level and the user program thread (containing the two higher levels) is accomplished using the POCO Events requestPending and requestComplete. Briefly, the thread function is blocked until the user program signals requestPending, at which point the thread function sends a command to the hand and waits for a response. The expected response is determined by the request type (one of BHREQ_REALTIME, BHREQ_SUPERVISE, BHREQ_EXIT, or BHREQ_CLEAR). When request processing is finished, the thread function signals requestComplete and blocks its execution until the next request is detected.
Immediately before the end of processing the request, the thread function calls an optional user-supplied callback function, which can perform a desired periodic activity. Keep in mind that the callback function is executed with high priority and it should not be computationally intensive. To specify a callback function, set the pCallback pointer to its address.
The CTB library supports timeouts and these are utilized by the low-level serial communication methods in the BHandSerialDriver class for sending and receiving bytes. Timeout parameters may be set (in milliseconds) that determine how long serial port functions should wait before returning with a timeout error. These parameters are set to default values during the initialization of the API but can be changed later by using the (intermediate-level) function ComSetTimeouts.
The PCAN library is used for sending and receiving CAN messages that the BHandCANDriver relies on. Messages that are sent and received are wrapped in Set/Get property methods with error codes. These are the main means used to communicate with the Puck 2. There is a timeout value used for getting Puck 2 property values. For this timeout it spins in a loop, polls for new messages, and delays a little before checking for new messages. The reason for this loop is to guarantee that Get property methods will always return. Status codes returned are usually zero even if a timeout occurs although more non-zero status codes may be returned in the future to identify problems encounted when running commands.
Note that the timeout values affect the behavior of the low-level processing thread only. The high-level user functions provide a separate timeout mechanism specifying how long the user program (in synchronous mode) should wait for the low-level thread before it resumes execution.
The intermediate-level processing allows you to control the host computer more closely. This level of processing contains the common code used to implement the multithreaded mechanism. It includes the mechanisms to be able to make command requests, detect when commands are completed, and wait for commands to complete, and hold return values in a datastructure determined by the command that is run.
The BHandDriver contains the intermediate-level methods that are called with supervisory commands formed in the BHandSupervisoryRealtime module. Each of these commands shares the common pattern of making a call to the important runSupervisoryCommand method to begin running the command and also check for pending communication before storing the desired command return values. An outside call from higher-level processing will be made from to begin running particular Supervisory commands, runSupervisoryCommand method will start running the command in the low-level thread, and optionally wait to store return values. When the low-level thread desires hardware communication for a command a call to ExecuteSupervisory call will call the blocking version of the hardware communication method that must be implemented by the particular BarrettHand hardware driver.
Programs are able to control the synchronous or asynchronous call behavior with the low-level thread through higher-level processing methods described in the next subsection. See below for more information on how high-level functions and variables that affect intermediate-level processing.
The remaining functions are the high-level functions called in the user program to control the hand. The functions in this section have a common structure. The command is prepared by calling a command constructor for the desired command. A command request is placed to the low-level communications thread with a call to the method of the particular BHandDriver implementation. If a value from running a command is returned, the output from the hand is interpreted accordingly. Results will be returned or return values passed by a pointer will be set in synchronous mode. In asynchronous mode, the results from a get-based command will need to be queried using GetResult(). In this mode error codes or status codes may be obtained using the ComGetError method.
High-level processing allows you to control the hand via a set of standard functions. These functions perform the following:
The execution of all functions is affected by the three variables: syncMode, requestTimeout, and pCallback. See BarrettHand API Variables for more information on these variables. The timeout settings for serial communication can affect high-level functions if motion commands take more time than the read timeout constant allows. For instance, slow open/close commands or the long running Hand-Initialize command may cause a read timeout because it takes too long for an acknowledgement.
It is possible to use the high-level commands synchronously or asynchronously by setting the variable syncMode. During synchronous mode, the program will not regain control until the BarrettHand has finished executing the command or the timeout limit has been reached. During asynchronous mode, all user functions will return immediately with result BHERR_PENDING. You can check if the processing has been completed using BHandSupervisoryRealtime::ComIsPending(), or wait for the processing to complete using BHandSupervisoryRealtime::ComWaitForCompletion().
The BarrettHand CAN driver communicates with the with the Puck2. There is one Puck 2 that controls each motor and the API provides the functionality as close as possible as the 262 hand. All Pucks in the hand are connected on a common CAN bus. The API contains all CAN communication code in the driver so that it is not necessary for the user to send or receive CAN messages. The rest of the section provides more information on what the CAN driver is doing.
Puck control is property based and Puck 2 CAN frames are constructed and sent over the CAN bus to get or set properties. Properties may be 8, 16, or 32 bits. Control over communication is by the PC and a get message must be sent in order to receive a property value.
There are objects created for each Puck and a manager to keep track of whether they are woken up or not. Each Puck is woken up after the CAN driver is opened and a reset command is sent to the hand. Supervisory commands are prefixed with Hand that typically call BPuck2 methods Get/Set property methods. For example, BHandCANDriver implements HandInit, HandClose, HandGotoPosition, etc. Some commands may just set Puck properties and others may need to poll to find out when commands finish such as with movement commands. At this level, there is only synchronous communication.
The BarrettHand API is written in C++ and this section describes how to use that API. Many applications will use just the main class named BHand. Define an object of that class, and use it for all hand control. Make sure the object does not go out of scope (i.e. define it as either a global variable, a member of another class, or in the main function).
The BarrettHand API uses third party libraries that let it be used in Windows and Linux. See Third Party Dependencies for more information on including these to be able to use the BarrettHand API. The rest of this section assumes that the headers and libraries for BarrettHand depenencies are set up correctly. It is probably easiest to get started by modifying one of the demos or examples since these have both the code and cross-platform compatible Makefiles for small BarrettHand programs.
Here is an example of a simple program that initializes a hand on COM1, and closes all fingers (in practice you should check for status codes):
#include <BHand.h> void main() { BHand bh; // Declare BHand object, bh char grasp[] = "G"; // Defines grasp as "G" char all[] = ""; // Defines all as "" bh.InitSoftware(1); // Initialize the Library, use COM 1 bh.InitHand(all); // Initialize the BarrettHand bh.Close(grasp); // Close the Grasp }
All example code in this documentation assume an object named bh of class BHand and a status code of type int named err were previously defined. More example code can be found in the documentation for the supervisory commands contained in the BHandSupervisoryRealtime class.
See the included README file for installing the BarrettHand GUI, API, examples, and demos on your platform. Also included are instructions on building these from the sources.
Supervisory mode allows control of the hand at a high-level, allowing you to command individual or multiple motors to close, open, and move to specific positions. This set of commands is used for most grasping situations. For the 262 hand, this mode takes advantage of the supervisory capabilities of the Motorola 68HC11. The Motorola 68HC11 controls the hand motion by supervising four HCTL-1100 motion-control microprocessors, one for each motor. With the 280 hand, the Supervisory commands will be running on the Puck 2 motor controllers. If "real-time" control of the motor position, velocity, or strain is needed, then use the RealTime control mode described below in the RealTime Mode section. The following table is a summary of the different supervisory commands divided into a few categories.
Category | Commands |
Init, Calibration, Reset, etc. | InitHand, Reset |
Motor Movement | Close, Open, GoToDefault, GoToDifferentPositions, GoToHome, GoToPosition, StepClose, StepOpen, TorqueClose, TorqueOpen |
Property Get/Set | Get, Set, PGet, PSet, Default, Load, Save, Temperature |
Misc. | Command, Delay, StopMotor, Baud |
In the default Supervisory mode, the Hand accepts a command from one of the functions in the API and will not return control of the Hand until the command is finished processing. When the Hand completes its command, it may return a status code. See Status and Error Codes for more detailed information on status codes. Look at the BHandSupervisoryRealtime class to view documentation for all supervisory mode commands. The next table shows methods to call to obtain command results, which are necessary only when running commands asynchronously. Use this table as a reference when searching for return values from non-blocking versions of these commands. Note that there are the usual means of returning values if running commands synchronously by return value or through passing the address of a datatype that holds the return value.
Command | Type | Get Method(s) |
Reset | bool responseReceived() | |
Get | int getResult(unsigned int i), unsigned int getNumResults() | |
PGet | int getResult() | |
Temperature | int getTemperature() | |
Command | const char * getReceive() |
RealTime mode allows users to write custom control laws that can be computed by a powerful host processor. This mode allows the host computer to send low-level control data and receive feedback data from the Hand in real-time.
RealTime mode is implemented in the following sequence:
RealTime properties are either flags or coefficients. RealTime flags determine what data will be sent and received continuously from the hand during RealTime control. RealTime coefficients affect commands that are used during RealTime control but are set once and are not continuously transmitted. You can specify different blocks of information for each motor by setting RealTime flags for each motor. Some properties are only available on the BH8-262 and some are only available on the new BH8-280 hand. You can also set different values for RealTime variables for each motor. The possible control data that can be sent is listed in the RealTime Control Property Tables. See the BH8-Series User Manual for details on these properties.
Parameter | Name | Type | Function | 262 Size (Bytes/type) | 280 Size (Bytes/type,notes) |
LCV | Loop Control Velocity | Flag | If True, RealTime control block will contain control velocity | 1 signed byte | 2 signed bytes |
LCVC | Loop Control Velocity Coefficient | Coefficient (1 to 255) | LCV is multiplied by LCVC to determine control velocity | N/A | not needed |
LCPG | Loop Control Proportional Gain | Flag | If True, RealTime control block will contain proportional gain | 1 unsigned byte | not needed |
LCP | Loop Control Position | Flag | If True, RealTime control block will contain control position | N/A | 4 byte, signed |
LCT | Loop Control Torque | Flag | If True, RealTime control block will contain control torque | 2 signed bytes | 2 signed bytes |
LFAIN | Loop Feedback Analog Input | Flag | If True, RealTime feedback block will contain analog input value | 1 unsigned byte | unused |
LFBP | Loop Feedback Breakaway Position | Flag | If True, RealTime feedback block will contain breakaway position | 2 unsigned bytes | unused |
LFV | Loop Feedback Velocity | Flag | If True, RealTime feedback block will contain feedback velocity | 1 signed byte | 2 signed bytes |
LFVC | Loop Feedback Velocity Coefficient | Coefficient (1 to 255) | Actual velocity is divided by LFVC to get LFV | N/A | unused |
LFS | Loop Feedback Strain | Flag | If True, RealTime feedback block will contain strain information | 1 unsigned byte | 1 unsigned byte (12-bit shifted by 4) |
LFAP | Loop Feedback Absolute Position | Flag | If True, RealTime feedback block will contain absolute position | 2 unsigned bytes | 2 unsigned bytes |
LFDP | Loop Feedback Delta Position | Flag | If True, RealTime feedback block will contain delta position | 1 signed byte | N/A |
LFDPC | Loop Feedback Delta Position Coefficient | Coefficient | The actual delta position is divided by this to get LFDP | N/A | N/A |
LFDPD | Loop Feedback Delta Position Discard | Flag | If True, any delta position overflow is discarded | N/A | N/A |
LFPPS | Loop Feedback Pressure Profile Sensors | Flag | If True, RealTime control block will contain pressure profile sensor data | N/A | 24 readings, 12-bit unsigned |
Parameter | Name | Type | Function | Size (Bytes/type) |
LFT | Loop Feedback Temp. | Flag | If True, RealTime feedback block will contain temperature | 1 unsigned byte |
The serial communication functions allow you to communicate with the hand without ever using the high-level Supervisory or RealTime commands. These serial communication functions allow taking complete advantage of what already exists for BarrettHand API. Using these methods directly would allow building a custom software interface to the BarrettHand, however they are intended to support only the BarrettHand API.
The functions relevant here may be found in the Serial Communications section of the header file, BHandSerialDriver.h. These methods have the "Com" prefix so they can be quickly identified as being part of the serial communications module. The serial communications port needs to be initialized with the desired comport and baud rate. Timeout parameters may be changed from the defaults. Then you may write and read data from the serial port.
The remaining methods such as Buffer and Response provide read-only access of the transmit and receive buffers. These methods are not expected to be used but are public in case an application is trying to observe the contents of these buffers. The remaining variables in the serial driver header file for the hand are for storing serial communication settings, buffering Supervisory commands, and keeping track of RealTime flags as well as the most recent control and feedback data.
These are the public variables in the API:
For all BH8-262 functions that return an integer, the value is determined according to the following rule:
BHERR Status Code | Name | Description |
0 | N/A | Successful completion of function |
-1 | BHERR_BHANDEXISTS | Attempt to initialize a second Bhand object on a com port already running a Bhand object. |
-2 | BHERR_OPENCOMMPORT | Error opening the specified com port |
-3 | BHERR_GETCOMMSTATE | Could not read the state of the com port |
-4 | BHERR_SETCOMMSTATE | Could not set the state of the com port |
-5 | BHERR_SETCOMMTIMEOUT | Could not set the com port timeout parameters |
-6 | BHERR_THREADSTART | Could not start the low-level thread |
-7 | BHERR_THREADPRIORITY | Error setting the thread priority |
-8 | BHERR_WRITECOM | Error writing to the com port (including timeout) |
-9 | BHERR_READCOM | Error reading from the com port (including timeout) |
-10 | BHERR_BADRESPONSE | Hand responded with an incorrect sequence of characters |
-11 | BHERR_CLEARBUFFER | Could not clear com port buffers |
-12 | BHERR_TIMEOUT | Request to low-level thread timed out |
-13 | BHERR_NOTCOMPLETED | Previous request not completed (in ASYNCNOW) |
-14 | BHERR_PENDING | Request is still being processed (normal in ASYNC mode) |
-15 | BHERR_NOTINITIALIZED | A BHand object is not initialized (with InitSoftware) |
-16 | BHERR_BADPARAMETER | The parameter code passed to Get is invalid |
-17 | BHERR_LONGSTRING | Send or receive string exceeds BH_MAXCHAR |
-18 | BHERR_OUTOFRANGE | The parameter is not within a valid range |
-19 | BHERR_MOTORINACTIVE | The motor is not activated |
-20 | BHERR_PORTOUTOFRANGE | The requested serial port is out of range |
Error codes for the BH8-280 hand are in development and return zero on success. Non-zero API return values are subject to change.
The BarrettHand API uses cross-platform compatible libraries that support multithreading and serial communication. They help to simplify the BarrettHand library and ensure that the low-level API provides the same dependability across platforms. However, it is necessary that the programmer include these dependencies to compile their own programs for the BarrettHand.
Instructions for building the third party dependencies for your platform can be found in a README file that will be installed with the BarrettHand software. Programs written for the BarrettHand will need to include headers and libraries for the POCO C++ Libraries and the CTB Library. See the subsections below for details on including these in your programs.
These third party libraries are used primarily for:
The subsections below provide useful information for including the BarrettHand dependencies that is independent of an IDE. Users will have to refer to other sources or the examples to see how headers and libraries are included for their development environment. Barrett has included the source code for these libraries and instructions on how to compile it under Linux (with the GNU C++ Compiler) and Windows (with MinGW). See the demos, examples, and Control GUI that are included with the BarrettHand software. Makefiles are provided that compile the demos and examples. The Control GUI uses the CodeBlocks IDE. These programs illustrate how to compile your own programs for the BarrettHand.
The following is available from "About POCO Libraries" online:
"The POCO C++ Libraries (POCO stands for POrtable COmponents) are open source C++ class libraries that simplify and accelerate the development of network-centric, portable applications in C++. The libraries integrate perfectly with the C++ Standard Library and fill many of the functional gaps left open by it. Their modular and efficient design and implementation makes the POCO C++ Libraries extremely well suited for embedded development, an area where the C++ programming language is becoming increasingly popular, due to its suitability for both low-level (device I/O, interrupt handlers, etc.) and high-level object-oriented development. Of course, the POCO C++ Libraries are also ready for enterprise-level challenges."
Visit http://pocoproject.org/info/ for more information.
The POCO headers and libraries are typically located in these directories under Windows and Linux:
The POCO C++ Libraries contains many components: Foundation, XML, Net, Util, etc. The BarrettHand API only requires the Foundation component. By default POCO will undefine some Windows functions. If applications are not able to compile with functions that are used in Windows.h then you will need to add POCO_NO_UNWINDOWS to the project defines.
The following is available from the IFTOOLS website online:
"CTB was developed to simplify and standardize the communication with other devices through different interfaces (RS232, GPIB). And this is platform independent!"
Visit https://iftools.com/opensource/ctb.en.php for more information.
The CTB library has been integrated into the BarrettHand API so there is no need to specify another dependency. The following information in this subsection will be left here for the time being for reference.
The CTB headers and libraries are typically located in these directories under Windows and Linux:
In Windows there is also the "ctb-0.14.dll" file that will automatically be installed in the Windows system directory. You will need to include it when deploying a BarrettHand application. This DLL is required with applications created with MinGW. If using Visual Studio then this DLL is not required because the CTB library is built as a static library. In the future, the CTB library may be removed from the ThirdParty directory but for now it is left to ensure backwards compatibility with some older versions of the software. However, new users are encouraged to drop the additional CTB include and library dependencies.
The 280 hand depends on the PCAN library from Peak-System Technik GmbH. An actual USB-to-CAN adapter from Peak Systems is required to connect the hand to the PC.
The PCAN headers and libraries are typically located in these directories under Windows:
In Windows there is also the "Pcan_usb.dll" file that will automatically be installed in the Windows system directory. You will need to include it when deploying a BarrettHand application.
There is also the Windows Multimedia library that applications need to link with. This is the winmm.lib for Visual Studio and winmm.a for MinGW. Both of these compilers should not need additional library paths because this is a standard library. The API uses this Windows library for increasing the resolution of timers.
The documentation for this API is for version 4.4.3. It has only been tested with Firmware version 4.4.x so firmware greater than or equal to this version should be installed. The BarrettHand API source files have changed significantly since version 4.3x although the syntax has been kept the same. Software built around the BarrettHand 4.3x C-Function Library should be able to migrate to using the new 4.4.x API without much difficulty.
Version 4.4.x has left out support within BHand.h for version 1.0 compatibility of the C style interface. See Known_Issues.txt for the known limitations of the API.
1.6.1