VGSM INSTALL

From VoiSmart Open Source Wiki

Jump to: navigation, search
Installation Instructions
*************************

This tree contains several subprojects. Configuration and building is common
among the different subprojects while a specific install and configuration
rocedure is present for each one.

--------------------------------------
Step 1: Configure the build system
--------------------------------------

Note: If you are working on a bzr-retrieved tree, please read the DEVELOPERS
file in the root directory.

cd into the untarred package tree and run ./configure

Be sure that the kernel currently running is the same currently installed. If,
for example, you just upgraded the kernel you will need to reboot you machine
in order to run the newer kernel.

If your paths differ from the standard ones you may have to specify appropriate
parameters to "configure". Run "./configure --help" to see a list of those
parameters.

Pay particular attention to the last lines of the configure's output, this is
a sample output of a working configuration:

checking kernel build directory... /lib/modules/2.6.20.3-ubuntu1/build
checking asterisk modules directory... /usr/lib/asterisk/modules
checking asterisk includes... /usr/include/
checking asterisk/version.h usability... yes
checking asterisk/version.h presence... yes
checking for asterisk/version.h... yes
checking asterisk configuration directory... /etc/asterisk
checking pppd plugins directory... /usr/lib/pppd/2.4.4
checking pppd includes directory...
checking pppd config directory... /etc/ppp/

NOTE: Fedora Core 3's 2.6.11 kernel has some of the 2.6.12's patches
which introduce incompatible interface changes. Since they offer no way to
know what changes have been introduced, if you're using that kernel you will
probably need to add --with-kernel-have-sk-prot flag to configure invocation.

--------------------------------------
Step 2: Compile everything
--------------------------------------

Run "make" and check that everything gets compiled correctly.

--------------------------------------
Step 3: Installation and configuration
--------------------------------------

Run "make install", if you "configure"d it correctly, kernel modules will
be installed in the appropriate /lib/modules/ subdirectory, asterisk
modules will be installed in Asterisk's modules directory and so on for
pppd plugin, configurations, etc.

Run:

depmod -a

In order to update the modules dependencies

ldconfig

In order to update libraries cache


3.1 kstreamer
----------------------

kstreamer modules make use of character devices in /dev. In particular,
ks-userport needs two character devices and application expects them to be
found at /dev/ks/userport_stream and /dev/ks/userport_frame.

To accomplish this, a udev rule must be installed in /etc/udev/rules.d

In samples/etc_udev_rules.d/30-kstreamer.rules there is a sample ruleset file
to create the devices in the appropriate places. Please adapt group and modes
to your installation.

Please note that if you are using udev older than 054 you will need to use
special rules to work around some missing features in udev.

Now load ks_userport module with:

modprobe ks_userport

In /dev you should see the two character devices being created:

/dev/ks
|-- userport_frame
`-- userport_stream


3.2 vISDN
----------------------

vISDN is based on kstreamer so, be sure to have correctly configured it before
proceeding.

As with kstreamer, some vISDN module (e.g. ppp) need to create devices in
/dev, so, you need to install 30-visdn.rules

Some distribution's (notably SuSE) net hotplug scripts may interfere
with the initialization of vISDN. You may see the interfaces go
down when you register them. I addedd an exception for visdn* interfaces
in /etc/hotplug.d/net/50-ifup.hotplug to avoid it.


3.2.1. Configuration

The first step of vISDN configuration relates to how hardware cards get
detected, named and configured at low-level.

You will want to persistently identify the same board across reboots, however
ISDN cards don't usually have a unique identificator, like the MAC address or
a serial number. The only way to uniquely and persistently reference the cards
is by using their PCI location. The PCI location is an identificator that
locates a PCI device amongs all the PCI buses connected to your host.

Of course, if you move a card from one slot to another, its PCI location
will change and you will have to update the configuration accordingly.

Unfortunately a clear connection between the PCI location and the physical
location is not always present. More than one PCI buses may be routed to the
physical slots and the order is not necessarily respected.

Find the PCI location of your ISDN card(s) using lspci:

# lspci
[...]
0000:00:07.0 Network controller: Cologne Chip Designs GmbH ISDN networki
	controller [HFC-PCI] (rev 02)
0000:00:09.0 ISDN controller: Cologne Chip Designs GmbH: Unknown device 08b4
	(rev 01)
[...]

The PCI location is the first sequence of digits, 0000:00:07.0 and 0000:00:09.0.

Make /etc/visdn/devices directory if missing and create one file for each PCI
device.
Name those files 'pci-PCILOCATION', so, in the former example you will
create two files:

pci-0000:00:07.0
pci-0000:00:09.0

In samples/ there are two device configuration files to copy from; one is a
sample for a HFC-S PCI A card, the other is for a HFC-4S card.

A proper hotplug script is still missing, a manual configurator has been
included, it is called 'visdn_configurator' and it is distributed in 'scripts/'.
visdn_configurator gets installed in /usr/sbin

If you correctly configured everything, including udev, running
'visdn_configurator' will load the modules, configure the cards and connect
the channels.

The next stage consists in configuring Asterisk to interact with vISDN.

In 'samples/' you will find examples for visdn.conf and extensions.conf
configuration files to be put in asterisk configuration directory. Edit
them according to your configuration.


3.2.2. Troubleshooting

--- TO BE WRITTEN ---

Check that the devices are created in /dev/visdn
Check that the sysfs device object gets populated with vISDN-specific
attributes.

/sys/bus/pci/devices/0000:00:07.0 should look like:

lrwxrwxrwx   1 root root    0 Oct 19 21:40 bus -> ../../../bus/pci
-r--r--r--   1 root root 4096 Oct 19 21:40 class
-rw-r--r--   1 root root  256 Oct 19 21:40 config
-rw-r--r--   1 root root 4096 Oct 19 21:40 detach_state
-r--r--r--   1 root root 4096 Oct 19 21:40 device
lrwxrwxrwx   1 root root    0 Oct 19 21:40 driver -> ../../../bus/pci/drivers/hfc-pci
                                                                      ^^^^^^^^^^^^^^^
-r--r--r--   1 root root 4096 Oct 19 21:40 fifo_state
                                          ^^^^^^^^^^^^
-r--r--r--   1 root root 4096 Oct 19 21:40 irq
-r--r--r--   1 root root 4096 Oct 19 21:40 local_cpus
drwxr-xr-x   2 root root    0 Oct 19 21:37 pcm
                                          ^^^^^
drwxr-xr-x   2 root root    0 Oct 19 20:49 power
-r--r--r--   1 root root 4096 Oct 19 21:40 resource
-rw-------   1 root root    8 Oct 19 21:40 resource0
-rw-------   1 root root  256 Oct 19 21:40 resource1
drwxr-xr-x   7 root root    0 Oct 19 21:37 st0
                                          ^^^^^
-r--r--r--   1 root root 4096 Oct 19 21:40 subsystem_device
-r--r--r--   1 root root 4096 Oct 19 21:40 subsystem_vendor
-r--r--r--   1 root root 4096 Oct 19 21:40 vendor


3.3 vGSM
----------------------

vGSM drivers are based on kstreamer so, be sure to have correctly configured
it before proceeding.

vGSM cards register several character devices, vGSM-I cards register one device
for each ME while vGSM-II cards register three devices for each
ME (ASC0, ASC1, MESIM) and one device for each SIM holder.

The default device names are thus:

- vGSM-I
 /dev/vgsm_meX

- vGSM-II
 /dev/vgsm2_meX
 /dev/vgsm2_meaX
 /dev/vgsm2_mesimX
 /dev/vgsm2_simX

'X' is a number assigned to each GSM module/SIM holder and is calculated with
the formula X=cardnum*8 + menum

Unfortunately cardnum depends on the order with which the Linux kernel
enumerates PCI devices which means that removing a card may renumber some or
all the other cards.

3.3.1 Persistent devices naming (EXPERIMENTAL)
----------------------------------------------

NOTE: If you only have one card or you are not concerned of eventual renubering
it is recommendable to skip this procedure as it is sensitive to the specific
Linux distribution, udev version and configuration.

A helper script for udev lets you associate permanent names to
devices. The script is located in unsupported/lib_udev/vgsm_helper and is
referenced in 30-vgsm.rules.

Please note that these rules have only be tested with recent versions of udev.

Install udev rule in unsupported/etc_udev_rules.d/30-vgsm to /etc/udev/rules.d/
Install udev helper script in /lib/udev or where it is appropriate in your
distribution.

Identify your cards:

vGSM-I cards don't have a serial number programmed in the hardware so, the only
reliable way to identify the card is through the PCI location.

vGSM-II cards do have the serial number, so, it may be used to identify the card
along with the PCI clocation.

The PCI location is an identificator that locates a PCI device amongs all the
PCI buses connected to your host.

Of course, if you move a card from one slot to another, its PCI location
will change and you will have to update the configuration accordingly.

Unfortunately a clear connection between the PCI location and the physical
location is not always present. More than one PCI buses may be routed to the
physical slots and the order is not necessarily respected.

Find the PCI location of your vGSM card(s) using lspci:

# lspci
[...]
00:0d.0 Network controller: Tiger Jet Network Inc. Tiger3XX Modem/ISDN interface
00:0e.0 Class ff00: Unknown device f16a:0004 (rev 01)
[...]

vGSM-I cards are marked Tiger Jet Network Inc.
vGSM-II cards are marked ****************** FIXME

The PCI location is the first sequence of digits prepended by 0000:, in this
example 0000:00:0d.0 and 0000:00:0e.0

Make /etc/vgsm/devices directory and create one file for each PCI device.
Name those files 'pci-PCILOCATION', so, in the former example you will
create two files:

/etc/vgsm/
`-- devices
    |-- pci-0000:00:0d.0
    `-- pci-0000:00:0e.0

In unsupported/etc_vgsm_devices there are two sample device configuration
files, one identifying the card by the PCI location ID and the other identifying
the card by its serial number.

You should now reboot or:

1. reload udev rules with "udevcontrol reload_rules"
2. Remove and re-insert vgsm or vgsm2 module

If everyting is correct, you will see properly named device being
created in /dev/vgsm/

3.3.2 Asterisk configuration
-----------------------------

In /etc/asterisk (or wherever you have your Asterisk configuration files) you
have to create these files:

vgsm.conf
vgsm_operators.conf
vgsm_countries.conf

In 'samples/etc_asterisk' you will find sample configuration files. Put them in
Asterisk's configuration directory and edit them according to your
configuration.

In particular you will have to put the correct device names in the module's
sections.

Finally start Asterisk and check that the modules get configured and initialized
with "show vgsm modules"

Please also refer, for further questions or trouble, to:

http://open.voismart.it/index.php/VGSM_FAQ

Thank you!
Personal tools