IX1ACTL(8)

NAME
ix1actl - download firmware and configuration to IX1 active ISDN controllers

SYNOPSIS
ix1actl [ -h | -?]
ix1actl -l
ix1actl {-i | -I} [-q] [-b <firmware base directory>] [-f <config file name>]
ix1actl {-u | -U} [-q] [-b <firmware base directory>] [-f <config file name>]
ix1actl -r [-q] [{-c# | -n <name>}] [-f <config file name>]
ix1actl [-d] [-q] [{-c# | -n <name>}] [-f <config file name>]

DESCRIPTION
The ix1actl command is used to download firmware and configuration data to the IX1 active ISDN boards from ITK / Digi, supported by the CAPI controller driver ix1a. These boards were originally manufactured by ITK, which is now part of the Digi International.

ix1actl uses a configuration file to determine the configuration settings and the firmware files to load onto every board. The default path name for this file is /etc/ix1a.cfg but an arbitrary file name can be specified on the command line.

Every IX1 active ISDN board needs some firmware loaded to be operable. Some boards need two files, a boot strap and the firmware itself, others need only a firmware file but no boot strap. Which boot strap and / or firmare file is needed for a specific board type is mentioned in the driver manual file ix1a(9).

The boot strap and firmware files themselves are strictly speaking not part of the ix1a device driver or ix1actl tool distribution. But with kind permission from Digi the necessary firmware files for the supported boards are installed with the package. To use other versions they must be extracted from the existing driver packages for the Microsoft Windows operating systems. Unfortunately the web site of Digi International does not offer any drivers for download any more (as far as known to the author). But as the boards are not manufactured any more and the drivers will not be developed further by Digi, the firmware files that come with the ix1a driver and the ix1actl tool are the latest and (hopefully) the best to be used with the boards supported.

  Command line options
The ix1actl program can perform several operations. The task to execute is defined by one of the main command line options:

-l  List all available CAPI controllers. The controllers handled by the ix1a driver are specially marked.

-i | -I
    Create an initial configuration file for all IX1 controllers found in the system. For every board default settings are used. With -i the command will fail if a configuration file with the same name already exists. Specifying -I will overwrite an existing file.

-u | -U
    Update an existing configuration file to reflect the currently available IX1 controllers. With -u only new boards not already found in the current file are added with defaults. Existing configuration records are not touched and no board is removed from the file. Specifying -U will also remove configuration entries for boards not found in the system (any more).

-d  Perform a firmware download for one or all IX1 controllers. This is the default if none of the other main options is specified. By default all controllers are handled. Using one of the following additional command line options one can select a single controller to download.

-r  Disable one or all IX1 controllers. By default all controllers are disabled, so they are not useable any more until a successful download operation. Using one of the following additional command line options one can select a single controller to disable.

The following additional command line options are supported by ix1actl:

-h | -?
    Print out some usage inforation about ix1actl and its usage. If this option is specified, nothing is done but printing out help information.

-b <firmware base directory>
    Use a specific directory for the bootstrap and firmware files. The default is /usr/share/capi/ix1a, but can be overriden with this option. The firmware base directory is only relevant when creating a default configuration file. It is stored into the global configuration field BaseDir. The download and disable tasks take the base directory from the configuration file.

-c# When used with -d or -r this option selects a single controller for the download or disable operation. The argument is the CAPI controller number to use. As the configuration file does not contain CAPI controller numbers one should check the output of “ix1actl -l” to see which controller is addressed through a specific CAPI controller number. Addressing a controller not handled by the ix1a driver or for which there is no entry in the configuration file will fail.

-f <config file name>
    Use a different path name for the configuration file. The default is /etc/ix1a.cfg.

-n <name>
    When used with -d or -r this option selects a single controller for the download or disable operation. The argument is the board name as used within the configuration file naming a board configuration section or as delivered by the command “ix1actl -l”. Case is not significant for the board name.

-q  Suppress normal program output. Only error message will be printed.

  The board configuration
The firmware and the configuration data to load onto every installed IX1 board in the system is determined from a configuration file. It contains the path names to the bootstrap and the firmware files for each board, and also configuration settings for the line attachment. The default path name for the configuration file is /etc/ix1a.cfg but that can be changed through the command line. For the documentation of its layout see ix1a.cfg(5).

AUTOMATICALLY LOADING BOARDS ON SYSTEM STARTUP
Normally all IX1 active ISDN boards should automatically be loaded during system startup. This is done through the system startup script /etc/rc.d/ix1a. This automatism must be enabled through /etc/rc.conf by adding the line “ix1a_enable="YES"”. The startup script will then automatically load the ix1a driver module if it is not already loaded or compiled into the kernel and load all boards with configuration sections in /etc/ix1a.cfg. On the first run (i.e. if no /etc/ix1a.cfg file exists) a default configuration file with entries for all currently available boards is created.

Note that the CAPI subsystem in general must also be enabled in /etc/rc.conf through a line like “capi_enable="YES"”.

FILES
/etc/ix1a.cfg
    By default the configuration file for the ix1actl tool resides in the directory /etc. But the directory and the file name can be changed through the command line.

EXAMPLES
The first example command line will simply list all available CAPI controllers:

    ix1actl -l

The following command line will create the initial configuration file /etc/ix1a.cfg for all IX1 boards found in the system, containing default settings. The resulting file should be checked and modified as needed.

    ix1actl -i

The next example will load all boards with configuration sections in the configuration file /etc/ix1a.cfg with their firmware and configuration settings:

    ix1actl -d

The last example will disable the board named “IX1-Basic-2”. After this command the addressed controller cannot be used until another download operation for it is successfully executed.

    ix1actl -r -n ix1-basic-2

SEE ALSO
c4b(4), ix1a(4), ix1a.cfg(5)

HISTORY
The ix1actl tool first appeared as an add-on for FreeBSD 5.3.

ACKNOWLEDGEMENTS
The information needed to implemented this tool (and the ix1a device driver) was taken from source code for the Linux and the Microsoft DOS driver package for the IX1 / Datafire boards from Digi International. This source code was donated to the author by Digi for implementing this driver.

AUTHORS
This manual page and ix1actl were written by Thomas Wintergerst <twinterg@gmx.de>.