Get Started

From VoiSmart Open Source Wiki

Revision as of 08:44, 14 January 2008 by Aep (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

About this document

This document is based on the original INSTALL documentation released by Daniele "Vihai" Orlandi <daniele_at_orlandi_dot_com> as part of the vstuff software.

The aim of the document is to get you started installing vGSM-II cards and get feedback from the community. If you find errors are probably mine. Drop me a line to get them documented Alberto "aep" <aep_at_it46_dot_se>


What do you need?

You need a vGSM-II card from Voismart. The vGSM-II card is a PCI adapter to make GSM network services available to the hosting system. vGSM-II Features

In a nutshell

The process of getting a vGSM-II card running in Asterisk consist on the following steps:

  • Compile and install Asterisk
  • Enable Asterisk debugging (optional)
  • Compile and install vstuff
  • Ensure that /dev/ks/userport_stream and /dev/ks/userport_frame character devices exist.
  • Ensure that the modules are loaded
vgsm2                  38248  6 
ks_userport            13364  0 
ks_softswitch           4948  2 ks_userport,vgsm2
kstreamer              40316  4 ks_userport,vgsm2,ks_softswitch
  • Ensure that asterisk loads correctly the chan_vgsm
  • Configure vgsm (vgsm.conf)
  • Enable Asterisk Manager to monitor events and send/receive SMS

vstuff source tree

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

Getting the vstuff code

You can either get a stable version from the http://open.voismart.it website or retrieve the development version using bazaar.

Download a tar.gz version

#wget http://www.visdn.org/download/http://www.visdn.org/download/vstuff-1.0.9.tar.gz

Check out the latest development version

Check out the latest development version by installing bazaar and running:

#bzr co http://repo.visdn.org/vstuff/devel vstuff-devel

If you are working on a bzr-retrieved tree, please read the DEVELOPERS file in the root directory. The package is based on the GNU Autotools, automake, autoconf, libtools, etc.

Make sure that you have all the software needed and run ./bootstrap

You might have to edit the version numbers of aclocal and automake to match the version number of your distribution

The bootstrap file looks like:

#! /bin/sh

set -x
libtoolize --copy --force               && \
aclocal-1.9 -I config                   && \
autoheader                              && \
automake-1.9 --add-missing --copy       && \
autoconf

Configure vstuff build system

if you downloaded the tar.gz version: cd into the untarred package tree and run ./configure if you checked out the developers version: cd into the vstuff-devel folder and run ./bootstrap ./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.

Compile vstuff

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

Vstuff 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

FIXME, INCLUDE GENERAL MODULE ARCHITECTURE

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

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.


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.


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

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.

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 samples/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 samples/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 location.

The PCI location is an identificator that locates a PCI device among 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 Computer telephony device: Espia Srl Unknown device 0001 (rev 01)

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 samples/vgsm_device 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/

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

Personal tools