.. _tools:

Available Tools
---------------

**NOTE** about devices.

Most tools support the use of multiple devices. You can define more than one device in a space separated list. Just provide multiple
device names to the option ``--device /dev/ttyUSB0 /dev/ttyUSB1`` when invoking the command.

The ``--device`` option list is checked during startup for valid serial devices and/or file names. If the device name is a valid file it is read for data. The format of the text
must be the same as the output generated by the ``magtest`` program. This is useful for debugging.

Tools will be added as they are developed. Currently the tools
available are:

magtest
=======

This tool is described in the installation instructions.

``magtest --help``

magdump
=======

This is a program that will dump a JSON string to the console for all
available devices. The default is to dump a string and exit. But if the
interval is set to a number, the program will dump a string every
``interval`` seconds

``magdump --help``

The regular options to set with this tool are:

.. code-block:: text

    -h, --help            show this help message and exit
    -d DEVICE, --device DEVICE
                          Serial device name (default: /dev/ttyUSB0)
    -i INTERVAL, --interval INTERVAL
                          Interval, in seconds, between dump records, in
                          seconds. 0 means once and exit. (default: 0)
    -v, --verbose         Display options at runtime (default: False)

   seldom used:
    --packets PACKETS     Number of packets to generate in reader (default: 50)
    --timeout TIMEOUT     Timeout for serial read (default: 0.005)
    --trace               Add most recent raw packet info to data (default: False)
    --nocleanup           Suppress clean up of unknown packets (default: False)

mag2sql
=======

This tool converts the JSON output from magdump into a draft MySQL definition. Users are urged to edit the output to match their needs.
the example prigram ``examples/magsql.py`` will load MySQL data once the database is defined.

``mag2sql --help``

``magdump | mag2sql > myschema.sql``

Configuration (options) File
============================

The example programs and ``magdump`` support the use of an options file that is read instead of completing all the options on the command line.
For example, instead of ``magdump --device /dev/ttyUSB1 --interval 60``, these coulld be included in an options file named, for example `pymagnum.opt` and the
command could be ``magdump @pymagnum.opt``. The `@` sign indicates the following is a file name and it read. There is an example in the `example` folder in GitHub.
It looks like this: (# denotes comments)

.. code-block:: text

    # Alter these to suit
    --device /dev/ttyUSB0
    --interval 60
    --packets 50
    --timeout 0.005
    # Remove # to enable the following
    #--verbose
    #--trace
    #--nocleanup