HokuyoAIST range sensor driver
==============================

Contents:

.. toctree::
   :maxdepth: 2

This library provides a driver for Hokuyo laser scanner devices using the SCIP
protocol version 1 or 2. It has been tested with the Hokuyo URG-04LX, UBG-04LX,
UHG-08LX, UTM-30LX and UXM-30LX-E but it should work with any scanner that
conforms to these protocol versions, including the URG-04LX-F01 and the
URG-04LX-UG01 (Simple-URG).

For a full list of classes and functions, see the `API documentation`_.

.. _`API Documentation`:
   doxygen/html/index.html


Dependencies
============

This library uses the Flexiport library for communication with devices. That
library must be installed. If you are using the Windows binary installer,
Flexiport may be installed with HokuyoAIST. Otherwise, it must be installed
separately.

Flexiport is available from GitHub_.

.. _github:
   http://www.gibhub.com/gbiggs/flexiport


Examples
========

If BUILD_EXAMPLES is enabled when the library is compiled and installed,
example sources are installed under "${prefix}/share/hokuyoaist-2/examples".
These can be used as a basis for creating your own software.

Building
--------

The examples can be built by making a directory (anywhere on your system where
you have write permissions will do), changing to that directory and executing
CMake with the example's source directory as an argument. For example, if you
have installed HokuyoAIST into /usr/local, you could do the following:

.. code-block:: bash

   $ cd ~
   $ mkdir hokuyoaist_examples
   $ cd hokuyoaist_examples
   $ ccmake /usr/local/share/hokuyoaist-2/examples/

Running
-------

The examples requires that you specify suitable options for the underlying
Flexiport object used to communicate with the laser scanner. At a minimum, a
type will be required. Other options, such as a baud rate, may also be
specified. For example:

.. code-block:: bash

   ./HokuyoAISTExample_example -o type=serial,device=/dev/ttyACM0,timeout=1 -b 19200

This will start the example, looking for the laser on port /dev/ttyACM0 and
using a timeout of one second, and connecting at a baud rate of 19200bps.

See the flexiport documentation for more details on available port types and
their options. Specify -h or -? to see a list of available options for the
example.

Some log file pairs for use with the LogReaderPort port type are also included.
Using a log file pair means the hardware (in this case, the laser scanner) does
not need to be present to execute the example. You can use the log file pairs
like this:

.. code-block:: bash

   ./HokuyoAISTExample_example -o type=logreader,file=example_urg04lx.log,timeout=1

See the Flexiport LogReaderPort object documentation for more options that can
be used with log file pairs. See the Flexiport LogWriterPort object
documentation for details on how to make your own log file pair for testing
your programs.

The available log file pairs are:

- example_urg_04lx.log(r,w): URG-04LX (Classic-URG)
- example_utm_30lx.log(r,w): UTM-30LX (Top-URG)
- example_uxm_30lx_e.log(r,w): UXM-30LX-E

GetID Example
-------------

(Developed by Luiz Mirisola.)

This example is a stripped down version of the hokuyoaist_example that
connects to the device, prints out its serial number, and closes the device.

It is useful for writing udev scripts to create permanent symlinks to your
lasers, in the case where you have more than one laser, as the serial number is
not otherwise available through udev.

The file, "96-hokuyo.rules," should be copied to /etc/udev/rules.d, followed by
restarting the udev deamon.

When a Hokuyo sensor is plugged, the /dev/ttyACM* device will be generated as
before, and a symbolic link called hokuyo_XXXXXX will also be generated, where
XXXXX is the laser serial number.

Note for Windows users
----------------------

Because Windows lacks a readily-available implementation of getopt, command line
options are not available for the example on this platform. Hard-coded options
will be used instead; change them in the source file and recompile if you need
to change the port options.


License
=======

This software is developed at the National Institute of Advanced
Industrial Science and Technology. Approval number H22PRO-1195. This
software is licensed under the Lesser General Public License. See
COPYING.LESSER.


Changelist
==========

4.0

- Removed support for serial connections (note: not serial-over-USB, which is
  what all current non-ethernet Hokuyo sensors use).
- Removed SCIP 1.0 support.

