# BKSTools
BKSTools is a Python package for communicating with newer SCHUNK grippers like EGU and EGK. These grippers are called BKS grippers
since they use the SCHUNK BauKastenSoftware.
The BKSTools provide ready-to-use command line scripts and an API to interact with the BKS grippers from your own Python code.
## Installation
A Python installation of version 3.7 or above is required. The installation of Python itself is not described here, see e.g. https://www.python.org/ for details.
The installation of the bkstools package using pip, the python package manager, is described below.
### Packages
Since version 0.0.2.27_2024-06-18 prebuilt packages for the [pip](https://pypi.org/project/pip/) python package manager can be downloaded automatically from the pypi website.
#### Package generation
Note: package generation is no longer needed, see "Package installation using pip" blow.
If you still want to / have to create packages yourself here is how:
The packages used by pip are called "wheels" and have a *.whl file extension.
For generating the *.whl package file on your own you can download the whole project from https://github.com/SCHUNK-SE-Co-KG/bkstools.git or simply clone it from there.
To clone it use:
```bash
git clone https://github.com/SCHUNK-SE-Co-KG/bkstools.git
```
To generate the package using a python virtual environment you can use:
```bash
cd bkstools
make venv
make bdist_wheel
```
This will generate e.g. `dist/bkstools-0.0.2.25-py3-none-any.whl`.
#### Package installation using pip
Since version 0.0.2.27_2024-06-18 prebuilt packages of the BKSTools are available automatically (internet connection required). This simplifies installation
to a simple:
```bash
pip install bkstools
```
for a new installation. Or for an update to:
```bash
pip install --upgrade bkstools
```
If you still want to / have to install from local package files here is how:
For the following description lets assume that you have something like the following file:
- `PATH_TO/bkstools-0.0.2.25-py3-none-any.whl`
The PATH_TO and the version numbers may of course vary.
### Virtual environment
It is not strictly necessary but still recommended to install the provided packages in a so called "virtual python environment", see e.g. https://docs.python.org/3/library/venv.html
This separates the dependencies of the BKSTools from other python programs on your computer.
To set up the virtual environment in *Linux* use something like the following in a shell:
```bash
mkdir bkstools # create a directory
cd bkstools # enter that directory
python3 -m venv venv # create the virtual environment (mostly empty for now)
source venv/bin/activate # activate the new virtual environment
```
On *Windows* use something like the following in a "cmd" console window:
```bash
md bkstools # create a directory
cd bkstools # enter that directory
python -m venv venv # create the virtual environment (mostly empty for now)
venv\Scripts\activate.bat # activate the new virtual environment
```
### Package installation
To install the actual BKSTools package from the online Python Package Index (PyPI):
```pip install bkstools```
for a new installation, or
```pip install --upgrade bkstools```
for an update
When installing from local package files use:
On Linux:
```pip install PATH_TO/pyschunk-5.3.0.3-py3-none-any.whl PATH_TO/bkstools-0.0.2.24-py3-none-any.whl```
On Windows:
```pip install PATH_TO\pyschunk-5.3.0.3-py3-none-any.whl PATH_TO\bkstools-0.0.2.24-py3-none-any.whl```
Of course you have to adjust the `PATH_TO` parts to point to your downloaded *.whl files.
## Usage
The installation above makes some ready-to-use command line (and GUI) tools available (in the activated virtual environment).
Additionally the bkstools is available as a python import module ready to be used by your own python scripts.
### Background and prerequisites
For communicating with a gripper the BKSTools use one of the following channels:
- Ethernet using the TCP/HTTP/JSON web-interface for grippers with EtherNet/IP, ProfiNet or EtherCAT interface. (For EtherCAT see restrictions below).
- Modbus-RTU for grippers with RS485 / Modbus-RTU interface
The former simply requires a standard ethernet interface on your computer running the BKSTools.
The latter usually requires additional hardware to interface to the physical RS485 interface that is used by the Modbus-RTU gripper. Such hardware can be e.g. a USB to RS485 interface board.
These typically show up as "serial devices", i.e. a "COM" port like "COM1, COM2, ..." on Windows or a "tty" device like "/dev/ttyS0, /dev/ttyUSB0, ..." on Linux.
#### Ethernet based communication
The BKSTools do *not* use the industrial ethernet protocols like Profinet, EtherNet/IP or EtherCAT of a BKS gripper. Instead the BKSTools can use
the additional "Service-Ethernet" communication channel of ethernet based BKS grippers. That means it uses HTTP GET and POST requests
to exchange JSON data with the gripper. This works for SCHUNK BKS grippers with a TCP/IP based Ethernet communication like Profinet and EtherNet/IP.
While EtherCAT still uses Ethernet it does not provide TCP/IP services per se, so the BKSTools can communicate with an EtherCAT SCHUNK gripper only
if it can use Ethernet over EtherCAT (EoE), which must be provided by an additional EtherCAT master (not provided by SCHUNK), usually a PLC.
The HTTP protocol relies on TCP/IP and thus the BKS gripper must already have a valid IP-address in order to be accessed by the BKSTools.
The gripper can be configured to have a fixed IP or it can be configured to use DHCP to get a valid IP-address. See the gripper documentation
on how to configure that.
#### Modbus-RTU communication
For grippers with RS485 / Modbus-RTU interface the BKSTools can use the Modbus-RTU protocol via a "serial port". Here the BKSTools use the "Fieldbus" interface of the gripper.
### Calling convention
If you "installed" the BKSTools package with ```pip``` as described above then wrappers for the original ```*.py``` scripts from the BKSTools package were installed
to the ```PATH``` (in the virtual python environment). The BKSTools scripts are then available without a ```.py``` suffix.
The examples shown below assume that you have installed the packages.
### Getting help
The scripts are directly callable from the command line. All scripts provide an integrated help message which biefly describes their purpose and usage.
That help message can be shown by calling ```SCRIPT_NAME -h```. Example:
```bash
> bks -h
usage: bks.py [-h] [-v] [-H HOST] [--force_reread] [--debug] [--debug_sleep] [--repeat_timeout REPEAT_TIMEOUT]
[--repeat_nb_tries REPEAT_NB_TRIES] [-l] [-p PERIOD] [-D DURATION] [--gpd] [--absolute_time]
[--gpdtitle GPD_TITLE] [-o OUTPUT_FILE_NAME_WITHOUT_SUFFIX] [--separator SEPARATOR] [--use_comma]
[other ...]
Read and/or write parameters of a SCHUNK BKS gripper (like EGI/EGU/EGK) according to the parameters given.
Example usage:
- bks.py -H 10.49.57.13 --list
- bks.py -H 10.49.57.13 actual_pos
- bks.py -H 10.49.57.13 actual_pos set_pos=25.4
- bks.py -H 10.49.57.13 actual_pos plc_sync_output plc_sync_input system_state internal_params.comm_state -D -10.0 --gpd
- bks.py -H COM2 serial_no_num serial_no_num:08x
- bks.py -H COM3,12,19200 set_pos=12.34
- bks.py -H /dev/ttyUSB0 sw_build_date
positional arguments:
other list of space separated firmware parameter names to read and/or write, e.g. 'actual_pos set_pos=4.5'.
For structured parameters you can access a single element for reading or writing by giving the name as
PARAMETERNAME.ELEMENTNAME like in 'plc_sync_input.actual_velocity' or
'plc_sync_output.control_dword=0x1245678'. For structured parameters you can access the whole
parameter for writing by giving the value as a tuple like in 'plc_sync_output="(11,22,33,44)"'. The
number of values in the tuple must match the number of elements in the structured parameter.
By adding ":FORMAT" the output format of a parameter can changed. For example to output a value as hex
with leading zeros add ":04x" to the parametername. The syntax for the FORMAT is the one used for
python f-strings or string.format().
Try option --list to get a list of all parameter names.
options:
-h, --help show this help message and exit
-v, --version Print the version and exit.
-H HOST, --host HOST "The BKS module to connect to.
For modules connected via ethernet this is the name or IP of the host to connect to.
For modules connected via Modbus/RS485 this is a string of the form
"SERIAL_INTERFACE,SLAVE_ID,BAUDRATE,COM_SETTINGS".
SERIAL_INTERFACE is the serial interface to use like "COM1" on Windows or "/dev/ttyUSB0" on Linux
SLAVE_ID is the Modbus slave ID of the module (optional, default used by our modules is 12)
BAUDRATE is the RS485 baudrate in bit/s (optional, default used by our modules is 115200)
COM_SETTINGS must be 8E1 for now (8 data bits, Even parity, 1 stop-bit)
SLAVE_ID, BAUDRATE and COM_SETTINGS may be left out and default to 12, 115200 and 8E1 respectively
then. A SLAVE_ID of 0 means "broadcast" and addresses all slaves. Only valid when writing values.
Example: --host COM6,15,9600
If not given then the value of the BKS_HOST environment variable is considered instead.
...
```
### Specifying communication parameters
All scripts need to know the "host", i.e. the address of the BKS gripper to access. You can provide this via the ```-H``` (capital "H") command line argument.
Pro-Tip: To save you typing this over and over again you can set the `BKS_HOST` environment variable. If no `-H` is given then the value of the `BKS_HOST` environment variable is used.
For Ethernet based grippers the host is an alphanumeric DNS-hostname or an IPv4-address.
For Modbus-RTU based grippers the host is a description of how to access the gripper via a serial interface
#### Ethernet based communication
Assuming that your BKS gripper is available at IP 10.49.57.13:
- On Linux:
```bash
export BKS_HOST=10.49.57.13
```
- On Windows:
```bash
set BKS_HOST=10.49.57.13
```
#### Serial / RS485 / Modbus-RTU based communication
Assuming that your BKS gripper is available via Modbus-RTU/RS485 on /dev/ttyUSB0 (Linux) or COM1 (Windows) as Slave-ID 12 with baudrate 115200 and communication parameters 8E1 (8 data bits, Even parity, 1 stop bit):
- On Linux:
```bash
export BKS_HOST=/dev/ttyUSB0,12,115200,8E1
```
- On Windows:
```bash
set BKS_HOST=COM1,12,115200,8E1
```
If using the default values for slave-ID (12), baudrate (115200) and communication parameters (8E1) then these need not be provided. So the above setting can be shortened to:
- On Linux:
```bash
export BKS_HOST=/dev/ttyUSB0
```
- On Windows:
```bash
set BKS_HOST=COM1
```
### Command line tools
The following scripts do not have a grahpical user interface (GUI).
They just write output to the console on stdout (and sometimes read input from keyboard via stdin).
- General purpose scripts (for interactive use or to be called from other scripts):
- ```bks``` Read and/or write parameters of a BKS gripper. The script can do cyclic reading.
- ```bks_move``` Move a BKS gripper to an absolute or relative position
- ```bks_grip``` Grip (or release) a workpiece with a BKS gripper
- ```bks_get_system_messages``` Get all or selected system messages of a BKS gripper
- Demonstration scripts (for demonstration to show the use of the API mainly):
- ```demo_simple``` Simple basic control (move, grip, release) of a SCHUNK BKS gripper using the basic ```BKSBase``` interface class.
- ```demo_bks_grip_outside_inside``` Perform a cycle of outside-gripping, releasing, inside-gripping, releasing with BKS gripper using the
more advanced ```BKSModule``` interface class
- ```demo_grip_workpiece_with_expected_position``` Perform a cycle of grip and release movements with a BKS gripper using the
more advanced ```BKSModule``` interface class and the additional grip-with-expected-workpiece-positon gripping command.
**WARNING The scripts provided are for demonstration purposes only. The do not include extensive error handling or proper saftey considerations!**
### GUI tools
The following commands do have a GUI. Nonetheless the initial parameters must be provided via command line options.
- ```bks_jog``` Simple interactive moving of a BKS gripper in absolute position, relative position or jog mode.
- ```bks_status``` Simple interactive display of cyclic data of a BKS gripper, including control- and statusword.
### API
There are two interface classes to interact with a BKS gripper:
- ```BKSBase``` Basic interaction, provides all parameters of a BKS gripper as properties of a Python object.
- ```BKSModule``` Advanced interaction which (partly) implements the bit-based protocol for exchanging cyclic data with the BKS gripper like a "regular PLC" would do.
No further examples and descriptions are given here. For more details see the demonstration programs and of course the
doc-strings of the API methods. Use the well commented ```bkstools\demo\demo_simple.py``` as starting point and then the slightly more advanced
```bkstools\demo\demo_grip_workpiece_with_expected_position.py``` for a more realistic example.
## Contributing
Feedback is welcome (on the code as well as on the documentation).
Raw data
{
"_id": null,
"home_page": "https://github.com/SCHUNK-SE-Co-KG/bkstools.git",
"name": "bkstools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "SCHUNK gripper BKS EGI EGU EGK",
"author": "Dirk Osswald",
"author_email": "dirk.osswald@de.schunk.com",
"download_url": "https://files.pythonhosted.org/packages/c1/a0/261b9e71698c5894f449440567fece9a37725f5a736dc173a727ae2f0abd/bkstools-0.0.2.31.tar.gz",
"platform": null,
"description": "# BKSTools\r\n\r\n\r\n\r\nBKSTools is a Python package for communicating with newer SCHUNK grippers like EGU and EGK. These grippers are called BKS grippers\r\n\r\nsince they use the SCHUNK BauKastenSoftware.\r\n\r\nThe BKSTools provide ready-to-use command line scripts and an API to interact with the BKS grippers from your own Python code.\r\n\r\n\r\n\r\n## Installation\r\n\r\n\r\n\r\nA Python installation of version 3.7 or above is required. The installation of Python itself is not described here, see e.g. https://www.python.org/ for details.\r\n\r\n\r\n\r\nThe installation of the bkstools package using pip, the python package manager, is described below.\r\n\r\n\r\n\r\n### Packages\r\n\r\nSince version 0.0.2.27_2024-06-18 prebuilt packages for the [pip](https://pypi.org/project/pip/) python package manager can be downloaded automatically from the pypi website.\r\n\r\n\r\n\r\n#### Package generation\r\n\r\nNote: package generation is no longer needed, see \"Package installation using pip\" blow.\r\n\r\n\r\n\r\n\r\n\r\nIf you still want to / have to create packages yourself here is how:\r\n\r\n\r\n\r\nThe packages used by pip are called \"wheels\" and have a *.whl file extension.\r\n\r\nFor generating the *.whl package file on your own you can download the whole project from https://github.com/SCHUNK-SE-Co-KG/bkstools.git or simply clone it from there.\r\n\r\nTo clone it use:\r\n\r\n```bash\r\n\r\ngit clone https://github.com/SCHUNK-SE-Co-KG/bkstools.git\r\n\r\n```\r\n\r\n\r\n\r\nTo generate the package using a python virtual environment you can use:\r\n\r\n```bash\r\n\r\ncd bkstools\r\n\r\nmake venv\r\n\r\nmake bdist_wheel\r\n\r\n```\r\n\r\nThis will generate e.g. `dist/bkstools-0.0.2.25-py3-none-any.whl`.\r\n\r\n\r\n\r\n#### Package installation using pip\r\n\r\n\r\n\r\nSince version 0.0.2.27_2024-06-18 prebuilt packages of the BKSTools are available automatically (internet connection required). This simplifies installation\r\n\r\nto a simple:\r\n\r\n```bash\r\n\r\npip install bkstools\r\n\r\n```\r\n\r\nfor a new installation. Or for an update to:\r\n\r\n```bash\r\n\r\npip install --upgrade bkstools\r\n\r\n```\r\n\r\n\r\n\r\n\r\n\r\nIf you still want to / have to install from local package files here is how:\r\n\r\n\r\n\r\nFor the following description lets assume that you have something like the following file:\r\n\r\n- `PATH_TO/bkstools-0.0.2.25-py3-none-any.whl`\r\n\r\n\r\n\r\nThe PATH_TO and the version numbers may of course vary.\r\n\r\n\r\n\r\n### Virtual environment\r\n\r\nIt is not strictly necessary but still recommended to install the provided packages in a so called \"virtual python environment\", see e.g. https://docs.python.org/3/library/venv.html\r\n\r\nThis separates the dependencies of the BKSTools from other python programs on your computer.\r\n\r\n\r\n\r\nTo set up the virtual environment in *Linux* use something like the following in a shell:\r\n\r\n```bash\r\n\r\nmkdir bkstools # create a directory\r\n\r\ncd bkstools # enter that directory\r\n\r\npython3 -m venv venv # create the virtual environment (mostly empty for now)\r\n\r\nsource venv/bin/activate # activate the new virtual environment\r\n\r\n```\r\n\r\n\r\n\r\nOn *Windows* use something like the following in a \"cmd\" console window:\r\n\r\n```bash\r\n\r\nmd bkstools # create a directory\r\n\r\ncd bkstools # enter that directory\r\n\r\npython -m venv venv # create the virtual environment (mostly empty for now)\r\n\r\nvenv\\Scripts\\activate.bat # activate the new virtual environment\r\n\r\n```\r\n\r\n\r\n\r\n### Package installation\r\n\r\nTo install the actual BKSTools package from the online Python Package Index (PyPI):\r\n\r\n```pip install bkstools```\r\n\r\nfor a new installation, or\r\n\r\n```pip install --upgrade bkstools```\r\n\r\nfor an update\r\n\r\n\r\n\r\n\r\n\r\nWhen installing from local package files use:\r\n\r\n\r\n\r\nOn Linux:\r\n\r\n```pip install PATH_TO/pyschunk-5.3.0.3-py3-none-any.whl PATH_TO/bkstools-0.0.2.24-py3-none-any.whl```\r\n\r\n\r\n\r\nOn Windows:\r\n\r\n```pip install PATH_TO\\pyschunk-5.3.0.3-py3-none-any.whl PATH_TO\\bkstools-0.0.2.24-py3-none-any.whl```\r\n\r\n\r\n\r\nOf course you have to adjust the `PATH_TO` parts to point to your downloaded *.whl files.\r\n\r\n\r\n\r\n## Usage\r\n\r\nThe installation above makes some ready-to-use command line (and GUI) tools available (in the activated virtual environment).\r\n\r\nAdditionally the bkstools is available as a python import module ready to be used by your own python scripts.\r\n\r\n\r\n\r\n### Background and prerequisites\r\n\r\nFor communicating with a gripper the BKSTools use one of the following channels:\r\n\r\n- Ethernet using the TCP/HTTP/JSON web-interface for grippers with EtherNet/IP, ProfiNet or EtherCAT interface. (For EtherCAT see restrictions below).\r\n\r\n- Modbus-RTU for grippers with RS485 / Modbus-RTU interface\r\n\r\n\r\n\r\nThe former simply requires a standard ethernet interface on your computer running the BKSTools.\r\n\r\nThe latter usually requires additional hardware to interface to the physical RS485 interface that is used by the Modbus-RTU gripper. Such hardware can be e.g. a USB to RS485 interface board.\r\n\r\nThese typically show up as \"serial devices\", i.e. a \"COM\" port like \"COM1, COM2, ...\" on Windows or a \"tty\" device like \"/dev/ttyS0, /dev/ttyUSB0, ...\" on Linux.\r\n\r\n\r\n\r\n#### Ethernet based communication\r\n\r\nThe BKSTools do *not* use the industrial ethernet protocols like Profinet, EtherNet/IP or EtherCAT of a BKS gripper. Instead the BKSTools can use\r\n\r\nthe additional \"Service-Ethernet\" communication channel of ethernet based BKS grippers. That means it uses HTTP GET and POST requests\r\n\r\nto exchange JSON data with the gripper. This works for SCHUNK BKS grippers with a TCP/IP based Ethernet communication like Profinet and EtherNet/IP.\r\n\r\nWhile EtherCAT still uses Ethernet it does not provide TCP/IP services per se, so the BKSTools can communicate with an EtherCAT SCHUNK gripper only\r\n\r\nif it can use Ethernet over EtherCAT (EoE), which must be provided by an additional EtherCAT master (not provided by SCHUNK), usually a PLC.\r\n\r\n\r\n\r\nThe HTTP protocol relies on TCP/IP and thus the BKS gripper must already have a valid IP-address in order to be accessed by the BKSTools.\r\n\r\nThe gripper can be configured to have a fixed IP or it can be configured to use DHCP to get a valid IP-address. See the gripper documentation\r\n\r\non how to configure that.\r\n\r\n\r\n\r\n#### Modbus-RTU communication\r\n\r\nFor grippers with RS485 / Modbus-RTU interface the BKSTools can use the Modbus-RTU protocol via a \"serial port\". Here the BKSTools use the \"Fieldbus\" interface of the gripper.\r\n\r\n\r\n\r\n### Calling convention\r\n\r\n\r\n\r\nIf you \"installed\" the BKSTools package with ```pip``` as described above then wrappers for the original ```*.py``` scripts from the BKSTools package were installed\r\n\r\nto the ```PATH``` (in the virtual python environment). The BKSTools scripts are then available without a ```.py``` suffix.\r\n\r\nThe examples shown below assume that you have installed the packages.\r\n\r\n\r\n\r\n### Getting help\r\n\r\nThe scripts are directly callable from the command line. All scripts provide an integrated help message which biefly describes their purpose and usage.\r\n\r\nThat help message can be shown by calling ```SCRIPT_NAME -h```. Example:\r\n\r\n```bash\r\n\r\n> bks -h\r\n\r\nusage: bks.py [-h] [-v] [-H HOST] [--force_reread] [--debug] [--debug_sleep] [--repeat_timeout REPEAT_TIMEOUT]\r\n\r\n [--repeat_nb_tries REPEAT_NB_TRIES] [-l] [-p PERIOD] [-D DURATION] [--gpd] [--absolute_time]\r\n\r\n [--gpdtitle GPD_TITLE] [-o OUTPUT_FILE_NAME_WITHOUT_SUFFIX] [--separator SEPARATOR] [--use_comma]\r\n\r\n [other ...]\r\n\r\n\r\n\r\nRead and/or write parameters of a SCHUNK BKS gripper (like EGI/EGU/EGK) according to the parameters given.\r\n\r\n\r\n\r\nExample usage:\r\n\r\n- bks.py -H 10.49.57.13 --list\r\n\r\n- bks.py -H 10.49.57.13 actual_pos\r\n\r\n- bks.py -H 10.49.57.13 actual_pos set_pos=25.4\r\n\r\n- bks.py -H 10.49.57.13 actual_pos plc_sync_output plc_sync_input system_state internal_params.comm_state -D -10.0 --gpd\r\n\r\n- bks.py -H COM2 serial_no_num serial_no_num:08x\r\n\r\n- bks.py -H COM3,12,19200 set_pos=12.34\r\n\r\n- bks.py -H /dev/ttyUSB0 sw_build_date\r\n\r\n\r\n\r\npositional arguments:\r\n\r\n other list of space separated firmware parameter names to read and/or write, e.g. 'actual_pos set_pos=4.5'.\r\n\r\n For structured parameters you can access a single element for reading or writing by giving the name as\r\n\r\n PARAMETERNAME.ELEMENTNAME like in 'plc_sync_input.actual_velocity' or\r\n\r\n 'plc_sync_output.control_dword=0x1245678'. For structured parameters you can access the whole\r\n\r\n parameter for writing by giving the value as a tuple like in 'plc_sync_output=\"(11,22,33,44)\"'. The\r\n\r\n number of values in the tuple must match the number of elements in the structured parameter.\r\n\r\n By adding \":FORMAT\" the output format of a parameter can changed. For example to output a value as hex\r\n\r\n with leading zeros add \":04x\" to the parametername. The syntax for the FORMAT is the one used for\r\n\r\n python f-strings or string.format().\r\n\r\n Try option --list to get a list of all parameter names.\r\n\r\n\r\n\r\noptions:\r\n\r\n -h, --help show this help message and exit\r\n\r\n -v, --version Print the version and exit.\r\n\r\n -H HOST, --host HOST \"The BKS module to connect to.\r\n\r\n For modules connected via ethernet this is the name or IP of the host to connect to.\r\n\r\n For modules connected via Modbus/RS485 this is a string of the form\r\n\r\n \"SERIAL_INTERFACE,SLAVE_ID,BAUDRATE,COM_SETTINGS\".\r\n\r\n SERIAL_INTERFACE is the serial interface to use like \"COM1\" on Windows or \"/dev/ttyUSB0\" on Linux\r\n\r\n SLAVE_ID is the Modbus slave ID of the module (optional, default used by our modules is 12)\r\n\r\n BAUDRATE is the RS485 baudrate in bit/s (optional, default used by our modules is 115200)\r\n\r\n COM_SETTINGS must be 8E1 for now (8 data bits, Even parity, 1 stop-bit)\r\n\r\n SLAVE_ID, BAUDRATE and COM_SETTINGS may be left out and default to 12, 115200 and 8E1 respectively\r\n\r\n then. A SLAVE_ID of 0 means \"broadcast\" and addresses all slaves. Only valid when writing values.\r\n\r\n Example: --host COM6,15,9600\r\n\r\n If not given then the value of the BKS_HOST environment variable is considered instead.\r\n\r\n...\r\n\r\n ```\r\n\r\n\r\n\r\n### Specifying communication parameters\r\n\r\n\r\n\r\nAll scripts need to know the \"host\", i.e. the address of the BKS gripper to access. You can provide this via the ```-H``` (capital \"H\") command line argument.\r\n\r\nPro-Tip: To save you typing this over and over again you can set the `BKS_HOST` environment variable. If no `-H` is given then the value of the `BKS_HOST` environment variable is used.\r\n\r\nFor Ethernet based grippers the host is an alphanumeric DNS-hostname or an IPv4-address.\r\n\r\nFor Modbus-RTU based grippers the host is a description of how to access the gripper via a serial interface\r\n\r\n\r\n\r\n\r\n\r\n#### Ethernet based communication\r\n\r\n\r\n\r\nAssuming that your BKS gripper is available at IP 10.49.57.13:\r\n\r\n- On Linux:\r\n\r\n ```bash\r\n\r\n export BKS_HOST=10.49.57.13\r\n\r\n ```\r\n\r\n- On Windows:\r\n\r\n ```bash\r\n\r\n set BKS_HOST=10.49.57.13\r\n\r\n ```\r\n\r\n\r\n\r\n\r\n\r\n#### Serial / RS485 / Modbus-RTU based communication\r\n\r\n\r\n\r\nAssuming that your BKS gripper is available via Modbus-RTU/RS485 on /dev/ttyUSB0 (Linux) or COM1 (Windows) as Slave-ID 12 with baudrate 115200 and communication parameters 8E1 (8 data bits, Even parity, 1 stop bit):\r\n\r\n- On Linux:\r\n\r\n ```bash\r\n\r\n export BKS_HOST=/dev/ttyUSB0,12,115200,8E1\r\n\r\n ```\r\n\r\n- On Windows:\r\n\r\n ```bash\r\n\r\n set BKS_HOST=COM1,12,115200,8E1\r\n\r\n ```\r\n\r\n\r\n\r\nIf using the default values for slave-ID (12), baudrate (115200) and communication parameters (8E1) then these need not be provided. So the above setting can be shortened to:\r\n\r\n\r\n\r\n- On Linux:\r\n\r\n ```bash\r\n\r\n export BKS_HOST=/dev/ttyUSB0\r\n\r\n ```\r\n\r\n- On Windows:\r\n\r\n ```bash\r\n\r\n set BKS_HOST=COM1\r\n\r\n ```\r\n\r\n\r\n\r\n\r\n\r\n### Command line tools\r\n\r\nThe following scripts do not have a grahpical user interface (GUI).\r\n\r\nThey just write output to the console on stdout (and sometimes read input from keyboard via stdin).\r\n\r\n\r\n\r\n- General purpose scripts (for interactive use or to be called from other scripts):\r\n\r\n - ```bks``` Read and/or write parameters of a BKS gripper. The script can do cyclic reading.\r\n\r\n - ```bks_move``` Move a BKS gripper to an absolute or relative position\r\n\r\n - ```bks_grip``` Grip (or release) a workpiece with a BKS gripper\r\n\r\n - ```bks_get_system_messages``` Get all or selected system messages of a BKS gripper\r\n\r\n\r\n\r\n\r\n\r\n- Demonstration scripts (for demonstration to show the use of the API mainly):\r\n\r\n - ```demo_simple``` Simple basic control (move, grip, release) of a SCHUNK BKS gripper using the basic ```BKSBase``` interface class.\r\n\r\n - ```demo_bks_grip_outside_inside``` Perform a cycle of outside-gripping, releasing, inside-gripping, releasing with BKS gripper using the\r\n\r\n more advanced ```BKSModule``` interface class\r\n\r\n - ```demo_grip_workpiece_with_expected_position``` Perform a cycle of grip and release movements with a BKS gripper using the\r\n\r\n more advanced ```BKSModule``` interface class and the additional grip-with-expected-workpiece-positon gripping command.\r\n\r\n\r\n\r\n\r\n\r\n**WARNING The scripts provided are for demonstration purposes only. The do not include extensive error handling or proper saftey considerations!**\r\n\r\n\r\n\r\n\r\n\r\n### GUI tools\r\n\r\nThe following commands do have a GUI. Nonetheless the initial parameters must be provided via command line options.\r\n\r\n\r\n\r\n- ```bks_jog``` Simple interactive moving of a BKS gripper in absolute position, relative position or jog mode.\r\n\r\n- ```bks_status``` Simple interactive display of cyclic data of a BKS gripper, including control- and statusword.\r\n\r\n\r\n\r\n### API\r\n\r\n\r\n\r\nThere are two interface classes to interact with a BKS gripper:\r\n\r\n- ```BKSBase``` Basic interaction, provides all parameters of a BKS gripper as properties of a Python object.\r\n\r\n- ```BKSModule``` Advanced interaction which (partly) implements the bit-based protocol for exchanging cyclic data with the BKS gripper like a \"regular PLC\" would do.\r\n\r\n\r\n\r\nNo further examples and descriptions are given here. For more details see the demonstration programs and of course the\r\n\r\ndoc-strings of the API methods. Use the well commented ```bkstools\\demo\\demo_simple.py``` as starting point and then the slightly more advanced\r\n\r\n```bkstools\\demo\\demo_grip_workpiece_with_expected_position.py``` for a more realistic example.\r\n\r\n\r\n\r\n\r\n\r\n## Contributing\r\n\r\nFeedback is welcome (on the code as well as on the documentation).\r\n\r\n",
"bugtrack_url": null,
"license": "GPL v3",
"summary": "bkstools: Tools to interact with SCHUNK BKS grippers via the HTTP/JSON webinterface or Modbus-RTU",
"version": "0.0.2.31",
"project_urls": {
"Download": "https://github.com/SCHUNK-SE-Co-KG/bkstools/archive/refs/tags/0.0.2.31_2024-06-24.tar.gz",
"Homepage": "https://github.com/SCHUNK-SE-Co-KG/bkstools.git"
},
"split_keywords": [
"schunk",
"gripper",
"bks",
"egi",
"egu",
"egk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f9203c35e99764070e0a50045afba8443b2f26a819a6760bd5711dc18d6dbeb4",
"md5": "a3d29559ce3a36fa35bf72627eaf65c8",
"sha256": "21bdc417e7c63a1028844ff18277a6949bb70847b0318a7c98f9aeaa34f594e9"
},
"downloads": -1,
"filename": "bkstools-0.0.2.31-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3d29559ce3a36fa35bf72627eaf65c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 200006,
"upload_time": "2024-06-24T13:46:39",
"upload_time_iso_8601": "2024-06-24T13:46:39.854374Z",
"url": "https://files.pythonhosted.org/packages/f9/20/3c35e99764070e0a50045afba8443b2f26a819a6760bd5711dc18d6dbeb4/bkstools-0.0.2.31-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1a0261b9e71698c5894f449440567fece9a37725f5a736dc173a727ae2f0abd",
"md5": "0714adcda3eeb3aa25ba11c67e467242",
"sha256": "ae151c7b5fc31ae76e6fece6a2dc7e80faf260bdf79050029e867bc48f095bf6"
},
"downloads": -1,
"filename": "bkstools-0.0.2.31.tar.gz",
"has_sig": false,
"md5_digest": "0714adcda3eeb3aa25ba11c67e467242",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 166664,
"upload_time": "2024-06-24T13:46:42",
"upload_time_iso_8601": "2024-06-24T13:46:42.041751Z",
"url": "https://files.pythonhosted.org/packages/c1/a0/261b9e71698c5894f449440567fece9a37725f5a736dc173a727ae2f0abd/bkstools-0.0.2.31.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-24 13:46:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SCHUNK-SE-Co-KG",
"github_project": "bkstools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bkstools"
}
JSON
