AVMAICCTL(8)

NAME
avmaicctl - download firmware and configuration to AVM active ISDN controllers

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

DESCRIPTION
The avmaicctl command is used to download firmware and configuration data to the active ISDN boards from AVM supported by the CAPI controller driver avmaic.

avmaicctl 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/avmaic.cfg but an arbitrary file name can be specified on the command line.

The firmware files themselves are strictly speaking not part of the avmaic device driver or avmaicctl tool distribution. But with permission from AVM these files are installed with the avmaic driver into /usr/share/capi/avmaic. The files installed are versions known to work with the driver (at least the ones supporting the DSS1 D-channel protocol). What file is needed for which board is mentioned in avmaic(4). There are also hints in that manual file where to get the most recent versions of the firmware files.

Besides the firmware file a controller may be provided with line configuration settings. The firmware file name and the line access parameters are taken from a configuration file. The default path name for it is /etc/avmaic.cfg, but that can be changed through the command line options for avmaicctl.

  Command line options
The avmaicctl 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 avmaic driver are specially marked.

-i | -I
    Create an initial configuration file for all active AVM 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 active AVM 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 active AVM 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 active AVM 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 avmaicctl:

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

-b <firmware base directory>
    Use a different directory for the firmware files than /usr/share/capi/avmaic. The firmware base directory is only relevant when creating a default configuration file. It is used to create the path name for the firmware file stored into the configuration section for each board. The download and disable tasks take the firmware file name as specified in 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 “avmaicctl -l” to see which controller is addressed through a specific CAPI controller number. Addressing a controller not handled by the avmaic driver or for which there is no entry in the configuration file will fail.

    AVM boards with more than one ISDN port require the download operation to be executed over the CAPI controller number for the first port of the board. Namely this is true for the AVM C2 and the AVM C4. If avmaicctl is called with the controller number of the second or higher port, the download will be refused.

-f <config file name>
    Use a different path name for the configuration file. The default is /etc/avmaic.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 “avmaicctl -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 active AVM board in the system is determined from a configuration file. It contains the path names to the firmware files for each board, and also configuration settings for the line attachment. The default path name for the configuration file is /etc/avmaic.cfg but that can be changed through the command line. For the documentation of its layout see avmaic.cfg(5).

AUTOMATICALLY LOADING BOARDS ON SYSTEM STARTUP
Normally all AVM active ISDN boards should automatically be loaded during system startup. This is done through the system startup script /etc/rc.d/avmaic. This automatism must be enabled through /etc/rc.conf by adding the line “avmaic_enable="YES"”. The startup script will then automatically load the avmaic driver module if it is not already loaded or compiled into the kernel and load all boards with configuration sections in /etc/avmaic.cfg. On the first run (i.e. if no /etc/avmaic.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"”.

The AVM B1 PCMCIA is a little bit different from the other board types. It can be loaded on system startup like the other board types. But in general it will be added to the system during runtime and it will be removed again without stopping the system. To load such a card when it is attached to a PCCARD slot one has to add some lines to /etc/devd.conf like

    attach 10 {
            device-name "avamic[0-9]+";
            action "/etc/rc.d/avmaic start";
    }

or

    attach 10 {
            device-name "avmaic0";
            action "/usr/sbin/avmaicctl -n AVMB1-1";
    }

provided that there is a corresponding configuration section in /etc/avmaic.cfg. Note that the first example will (re-)load all available AVM active ISDN boards in the system. The second will only load the board named “AVMB1-1” and leave other boards in their current state.

FILES
/etc/avmaic.cfg
    By default the configuration file for the avmaicctl 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:

    avmaicctl -l

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

    avmaicctl -i

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

    avmaicctl -d

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

    avmaicctl -r -n AVMC4-2

SEE ALSO
avmaic(4), c4b(4), avmaic.cfg(5), http://www.avm.de, ftp://ftp.in-berlin.de/pub/capi4linux.

HISTORY
The avmaicctl tool first appeared as an add-on for FreeBSD 4.6.

ACKNOWLEDGEMENTS
The information needed to implemented this tool was mostly extracted from the board download tool for the Linux driver for active AVM ISDN boards written by Carsten Paeth <calle@calle.in-berlin.de>.

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