# PbnTools - help

This is a shortened help. Full version available in Polish.

## Contents

- 1 Introduction
- 2 License
  - 2.1 Attached software
- 3 Functionality
  - 3.1 Download Kops
  - 3.2 Download Pary
  - 3.3 Download Bbo
  - 3.4 Download Tournament Calculator
  - 3.5 Deal cards
  - 3.6 Converting LIN to PBN
  - 3.7 Configuration
  - 3.8 Command line
  - 3.9 Options through Java parameters
- 4 Requirements
- 5 Download
  - 5.1 Installable versions
  - 5.2 Source code
  - 5.3 Installation
- 6 Development
  - 6.1 Build requirements
- 7 Version history
- 8 Ending

# 1 Introduction

PbnTools is intended as a toolkit for files containing bridge deals. Most popular format for these is PBN.

Currently PbnTools has following funcionalities:

Download Kops
  Downloads tournaments in Kops format and saves it as PBN files.
Download Pary
  Downloads tournaments in Pary format and saves it as PBN files.
Download Bbo
  Downloads tournaments or hands records from BBO server and saves it as PBN files.
Download Tournament Calculator
  Downloads hands records from Polish Tournament Calculator system.
Deal cards
  Help in manual duplication of bridge boards from pbn files. Requires an internet camera and barcoded playing cards.

Program is started with the file PbnTools.exe (Windows) or pbntools (linux).

# 2 License

The program is distributed together with source code under GNU GPL license, version 3 or later. Some individual files are licensed with more permissive MIT License, but this regards only to files that contain MIT License header.

## 2.1 Attached software

The program uses following software:

Apache HttpClient
  Apache HttpClient is a http client library.

JLayer
  JLayer is a JAVATM library that decodes, converts and plays MP3 files in real-time. Distributed under LGPL license. See files jlayer_LICENSE.txt and jlayer_README.txt in program directory.

JSoup
  JSoup jsoup is a Java library for working with real-world HTML. It provides a very convenient API for extracting and manipulating data, using the best of DOM, CSS, and jquery-like methods. Distributed under MIT license. See jsoup_LICENSE.txt in program directory.

Kotlin
  Programming language originated from Java.

Logback and SLF4J
  Logback SLF4J Libraries generating program logs.

ZBar
  ZBar (or its clone ZBarW) is an open source software suite for reading bar codes from various sources, such as video streams, image files and raw intensity sensors. Distributed under LGPL 2.1 (or later) license. Here is applied a limited version reading pictures from a video camera. A license file: zbar_LICENSE.txt

Windows version uses also:

wget
  wget for windows, belonging to Msys2, is a tool for recursive download of web pages, together with all needed files. License files: wget_COPYING.txt, wget_README.txt. binaries and dependencies,

This html document was generated using the LaTeX2HTML translator.

Source codes are available in section Download (5.2).

# 3 Functionality

##
3.1 Download Kops

Polish tournaments published in Kops format can be found on pages of Polish Contract Bridge Association (PZBS). Here are sample results. The best tournaments are labeled Chorzďż˝w.

Program requires a link to a tournament. It should be a link labeled Wyniki, leading to a screen consisting of 2 frames: results and boards. Generated files are inserted into working directory (Configuration), in a subdirectory kops. Subdirectory is generated automatically.

##
3.2 Download Pary

Polish tournaments published in Pary format can be found on page warsbrydz, Wyniki, WOB, Stare.

##
3.3 Download Bbo

Tournaments or hand records may be downloaded.

The PBN file obtained with this download contains also bidding and play information.

Download process doesn't overload the server much, just like viewing all travellers.

### 3.3.1 Tournament download

Use option Download hands / Hands type: Bbo.

The link that should be pasted into Download hands dialog should be obtained from Bridge Base Online , then Hand Records, results of recent tournaments, Pairs. The right link is under Show boards label.

### 3.3.2 Hands history download

Use option Download hands / Hands type: Bbo Hand records.

Hands history link should be used, obtained from Hand records screen by Get hands button. Example link:

    https://www.bridgebase.com/myhands/hands.php?username=playersnick&start_time=1617573600&end_time=1617746400

##
3.4 Download Tournament Calculator

Tournament Calculator is current software used in Polish tournaments, like MZBS. It replaced Kops and Pary. For download use the main link for results, e.g. 260330.

##
3.5 Deal cards

Dealing cards is done by showing cards to an internet camera, which "finds" the card in a given board and points to whom it should be dealt. Pointing is done by displaying player's sign and speaking it through the speaker. Currently Polish words are used: jeden, dwa, trzy, cztery, respectively for N, E, S, W.

### 3.5.1 Requirements

Internet video camera
  The best in this case are cameras with manual focus adjustment (with a knob). Autofocus cameras also work, including those built in laptops.

Barcoded cards
  Two formats of barcodes are recognized:

  PCard
    Also known as WIN. You can recognize it by black narrow stripes surrounding the code. The number of stripes varies, but it's always more than 3.

  PCard2
    Currently, that is in 2026, it's the only standard possible to obtain. Every code consists of 4 stripes of width 1 or 2. You can buy it in Bridgepol .

## 3.6 Converting LIN to PBN

Lin to Pbn conversion may be performed using GUI or command line interface.

##
3.7 Configuration

Working directory
Zbarcam options
  Additional options passed to zbarcam. A video device may be specified this way as e.g. `/dev/video1`. Default (first) device has number 0.

  To select which cards to use, you should disable the ones you don't have. Initially both PCard and PCard2 is enabled. You can add for example `-Spcard.disable`, then only PCard2 will be active.

  Full options list is available in file zbarcam.html.

User agent
  User agent parameter for www requests. An empty string is equivalent of PbnTools/version.
www delay
  A delay between consecutive www requests, in seconds. Minimum: 1. For Bbo the value of 4 is suggested, otherwise 503 errors may appear in download log.

##
3.8 Command line

Part of the program functionality is available through command line interface. For example downloading tournaments.

        pbntools -dtk http://www.strona-turniejow.pl/turniej999/index.html

Command line options may also be applied when calling jar file directly, for example:

        java -jar PbnTools.jar -dtk http://www.strona-turniejow.pl/turniej999/index.html

For details on command line options please launch

        pbntools -h

## 3.9 Options through Java parameters

Additional configuration may be applied using Java virtual machine (JVM) properties. The following properties are available:

- `jsoup.log.folder` Directory, to which all files downloaded by JSoup library will be saved. Used for diagnostics purposes.
- `user.language` Set to `pl` or `en` to force the UI language.

An example of running the program with JVM parameter:

      java -Djsoup.log.folder=C:/temp/bbo-jsoup -jar PbnTools.jar -dtk http://www.tournaments.pl/tour999/index.html

# 4 Requirements

Java, version 6, is required. Platforms supported: Windows and Linux.

#
5 Download

##
5.1 Installable versions

Current version, 1.5.0:

- Windows
- Linux

Old binaries: 1.4.0: Windows Linux , 1.3.3: Windows Linux , 1.3.2: Windows Linux , 1.3.1: Windows Linux , 1.3.0: Windows Linux , 1.2.7: Windows Linux , 1.2.6: Windows Linux , 1.2.5: Windows Linux , 1.2.4: Windows Linux , 1.2.3: Windows Linux , 1.2.2: Windows Linux , 1.2.1: Windows Linux , 1.2.0: Windows Linux , 1.1.0: Windows Linux

##
5.2 Source code

- PbnTools 1.5.0 , PbnTools 1.4.0 , PbnTools 1.3.3 , PbnTools 1.3.2 , PbnTools 1.3.1 , PbnTools 1.3.0 , PbnTools 1.2.7 , PbnTools 1.2.6 , PbnTools 1.2.5 , PbnTools 1.2.4 , PbnTools 1.2.3 , PbnTools 1.2.2 , PbnTools 1.2.1 , PbnTools 1.2.0 , PbnTools 1.1.0 or see Development, section 6
- jlayer1.0.1.tar.gz
- jsoup-1.7.3-sources.jar jsoup-1.7.1-sources.jar jsoup-1.6.1-sources.jar
- logback-classic-1.2.3-sources.jar logback-core-1.2.3-sources.jar slf4j-api-1.7.30-sources.jar
- ZBar
  - zbarw modified
  - A patch set available with PbnTools source code.

- wget sources available as other sources distributed with msys wget package for msys

Sources for Apache HttpClient, Kotlin can be downloaded through maven repository. One can use gradle task, which is capable of downloading library sources.

## 5.3 Installation

Unpack zip file into an arbitrary target folder. This folder may not contain spaces.

#
6 Development

Program is written mainly in Java. I encourage to contribute either by programming or by submitting bug reports and suggestions.

Following development means are available:

- Dedicated forum - discussion.

- GIT - source code, thanks to github.com:

          git clone https://github.com/jarekczek/pbntools.git
          svn checkout svn://svn.code.sf.net/p/pbntools/code/trunk pbntools-code-directory

  Browse code on-line, PbnTools at sourceforge,

Guidelines for source code are in file README.SRC.txt, in source code archive, see: Download, 5.

## 6.1 Build requirements

1. Sun Java Development Kit, JDK 1.8.
2. ant, Debian package name: ant. Main build tool.
3. BeanShell, bsh-2.0b4.jar (or newer) pointed in build.xml
4. launch4j, to create exe file for Windows.
5. Latex tools for documentation. Debian package name: latex2html.
6. For building zbar additional tools are needed. Building zbar is not necessary.
7. JUnit, JUnit-addons - for auto-test targets.

# 7 Version history

1.5.0, 25.06.2026
  - Dealing cards with barcodes PCard2.
1.4.0, 01.05.2026
  - Tournament Calculator format.
1.3.3, 22.05.2021
  - Download improvement - automatic retry after http error 503
1.3.2, 20.05.2021
  - Fixed problem with downloading Bbo hand records
  - Upgraded wget for windows to 1.20.3-2 by msys
1.3.0, 06.04.2021
  - Bbo - support for hands history (not only tournaments)
  - Bbo - corrections for some movie links (big lin sections)
1.2.7, 09.11.2020
  - Bbo now uses https.
1.2.6, 18.05.2020
  - Fixed wget problem with certificates.
  - Generating log file to help troubleshooting (`%USERPROFILE%/.PbnTools/PbnTools.log`).
1.2.5, 04.04.2020
  - Saving login results from BBO, to help troubleshooting.
1.2.4, 12.04.2018
  - Messages on BBO login failure.
1.2.3, 17.03.2018
  - results.csv and results_ranked.csv files from BBO, colon as separator.
1.2.2, 12.03.2018
  - BBO download with authentication (obligatory).
  - results.csv file generation from BBO (experimental).
1.2.1, 27.11.2013
  - Fixed bugs.
1.2.0, 24.11.2013
  - Downloading of Bbo tournaments.
  - Lin to pbn conversion.
  - User agent option in configuration dialog.
  - New configuration option: www delay.
  - Pary download improvements.
1.1.0, 16.09.2012
  - Downloading tournaments in Pary format, i.e. warsbrydz , Wyniki, WOB, stare.
  - Switched barcode video library for dealing cards on Windows to the one using DirectShow driver instead of Video for Windows. This should remove most problems experienced by Windows users.
1.0.3, 05.04.2012
  - Check for updates option in About window.
  - Zbar modification, to handle cameras providing picture in MJPG format.
  - Made the app visible in taskbar.
1.0.2, 01.11.2011
  - Fixing PBN format. `T` instead of `10`.
1.0.1, 01.11.2011
  - Ignoring robots.txt file during tournament download.
1.0.0, 01.11.2011
  First official release, under GNU GPL 3.0.
  - Option Deal cards
0.5, 07.03.2010
  Private version.
  - Option Download Kops.

# 8 Ending

I am open for suggestions. I will be grateful for informations about incorrect operation of the program or a web-page.

Jarek Czekalski , last modification June 25 2026