path: root/README

#
# TODO:
#   * add xivovp xivoxhfc dans /etc/dahdi/modules.con ?
#
# This tree is what needs to be changed in a default XiVO install to get it
# working on XIOH.
#
# The steps are described below.
#
# /
# |-- etc
# |   |-- asterisk
# |   |   `-- dahdi-channels.conf
# |   |-- dahdi
# |   |   `-- system.conf
# |   |-- init.d
# |   |   `-- xioh
# |   `-- udev
# |       `-- rules.d
# |           `-- 50-net.rules
# |-- lib
# |   |-- firmware
# |   |   |-- IxPiuMicrocode.dat
# |   |   `-- IxPiuMicrocode.license
# |   `-- modules
# |       `-- `uname -r`
# |           `-- xioh
# |               |-- e1000.ko
# |               |-- echo.ko
# |               |-- gcu.ko
# |               |-- gpio.ko
# |               |-- hssvoice_driver.ko
# |               |-- tdm_infra.ko
# |               |-- tdm_setup_driver.ko
# |               |-- xivo_tdm.ko
# |               |-- xivovp.ko
# |               `-- xivoxhfc.ko
# `-- usr
#     `-- share
#         `-- doc
#             |-- IxPiuMicrocode
#             `-- xioh
#                 `-- README
#
# The tarball including those files is generated from the repo using the command
#   tar cvzf xioh.tgz xioh-install --exclude-backups --exclude-vcs
#

= XIOH install SOP =

  ==  Contents ==

    * 0 Prerequisites and hardware description of the appliance

    * 1 Installing XiVO on the Hard Drive

    * 2 Personalize the system
        * 2.1 Setup the serial console
        * 2.2 Install our modules
        * 2.3 Copy the Intel's TDM firmware
        * 2.4 Configure the init
        * 2.5 Configure dahdi
        * 2.6 Set the network interfaces

    * 3 Usage
        * 3.1 Boot & reboot
        * 3.2 Upgrade XiVO

    * 4 Be aware that...

    * 5 FAQ

        * 4.1 How to set the hardware clock?
        * 4.2 How to report bugs?
        * 4.3 Where to find the sources?
        * 4.4 How to send a patch?
        * 4.5 How do I use the fron pannel serial port?
        * 4.6 I don't have the Ethernet interfaces
        * 4.7 How to replace the Hard Drive, or the mother board?
        * 4.8 Is there an echo canceller?

    * 5 Tips

        * 5.1 Setup the serial console with GRUB LEGACY


  == Prerequisites ==

    Mount the Suresnes/Common Filer, and cd to the `Hardware/xioh-install/release`
    dir. It is a GIT repo cloned, manually pulled, hopefully up to date. This is
    where you should access this README file.


    == Hardware description of the XIOH front and back side ==

  ==  Back ==

  connectors from left to right :

      X       X     X     X       X       X     X    X    X    X   X
      2xUSB   eth0  eth1  eth2    ttyS0   BRI3  BRI2 BRI1 BRI0 FXS FXO

  Currently, the Ethernet ports could be labelled on the other way.

  ==  Front ==

  connector : ttyS1

  LEDs from left to right :

      X    X    X    X    X    X    X    X    X    X    X     X
      LED0 LED1 LED2 LED3 LED4 LED5 LED6 LED7 LED8 LED9 LED10 LED11
      PWR  <----  not defined yet   ---> eth0 eth1 eth2 IERR  SATA


  ==  Install XiVO on the Hard Drive ==

    Use an other computer to install XiVO. Once finished, you need to
    personalize the system. Do it on your current setup, you need can't yet boot
    on the XiOH hardware.

  == Personalize the system ==

    === Setup the serial console ===

    For GRUB LEGACY, see section Tips.
    For GRUB 2, edit `/etc/default/grub` and define the following variables
    (replace if any):

        GRUB_SERIAL_COMMAND="serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1"
        GRUB_TERMINAL="serial console"
        GRUB_CMDLINE_LINUX="console=ttyS0,115200n8"

    Then, you need to update GRUB with the following command:

        `update-grub`

    Now you need to enable the serial console prompt by editing `/etc/inittab`
    and adding the following line (should be commented):
    `T0:23:respawn:/sbin/getty -L ttyS0 115200 vt100`

    It has also to be anabled on the `/etc/securetty` file (is the default).

    === Install our modules ===

    Copy the `modules/xioh` dir in the following directory:

        /lib/modules/`uname -r`

    Then remove the default network kernel module located at
    /lib/modules/`uname -r`/kernel/drivers/net/e1000/e1000.ko

    Finally install the new modules with the following command:

        depmod -a

    === Copy the Intel's TDM firmware ===

    Copy the file `thirdparty/IxPiuMicrocode.dat` in the `/lib/firmware/`
    folder.
    Copy its license file `thirdparty/IxPiuMicrocode.license` in the
    `/usr/share/doc/` folder.

    === Configure the init ===

    Copy `etc/init.d/xioh` in `/etc/init.d` and then run the following command:

        update-rc.d xioh defaults

    === Configure dahdi ===

    Copy `etc/dahdi/system.conf` in `etc/dahdi/`.
    Copy `etc/dahdi-channels.conf` in `etc/asterisk/`.

    === Set the network interfaces ===

    In order to have your network interfaces named in order, copy
    etc/udev/rules.d/50-net.rules to the installed system.

    If you installed XiVO on a secondary hardware, you'll need to remove the
    `/etc/udev/rules.d/70-persistent-net.rules` file.

  == Usage ==

    === Boot & Reboot ===

    To boot the board, plug the power cable. You need to press the Power switch
    (SW1, right side) few seconds to boot.

    There is no reboot actually. You need to halt the board. Either from
    GNU/Linux or by pressing the switch SW1 few seconds.

    Please mind that "reboot" command halt the board. You'll need to press the
    the switch SW1 to restart the board.

    === Upgrade XiVO ===

    You can use the `xivo-upgrade' command, but you actually need to restart
    the system in order to reload correctly the drivers.
    Don't forget to restart!


  == Be aware that.. ==

    * You should not run the `dahdi_genconf` tool. Use our
      `etc/dahdi/system.conf` file instead. If you do so, it will override it
      using an empty file. Restore the old one from `/etc/dahdi/system.conf.bak`.
      Same for the `etc/dahdi-channels.conf` file that would be overriden.

    * Everything that goes wrong is not necessarily your fault. Please report.

    * You can't actually boot through USB, no need to try.

  ==  FAQ ==

    * How to set the hardware clock?
      If the system clock is wrong, set is using the following command for
      example or using ntpd

            date -s "2012-11-14 11:21:00 +0200"

      Then, write the RTC with the system clock:

            hwclock -w

    * How to report bugs?
      You can reach us on the Freenode IRC network at #xivo-hard

    * Where to find the sources?
      Get them from 0001-0001.okey.ohanda.org

    * How to send a patch?
      See 'How to report bugs?' or read hardware.xivo.fr

    * How do I use the fron pannel serial port?
      It depends of your needs, really. Small hint: its node is /dev/ttyS1

    * I don't have the Ethernet interfaces

      It's probably because the setup was for an other board. Please check is
      they are popullated with a greater name than "eth2". Use `ifconfig -a`.
      If so, please do as explained in "Set the network interfaces".

    * How to replace the Hard Drive, or the mother board?

      First, open the box:
      Remove the screws at the bottom (near the front side) and two on each
      side, the one at the bottom, close to the front side, the other at the
      middle, close to the back side.

      Then, disconnect all cables.

      Finally, unscrew the HDD box to replace it, or the mother board.

      Please read the "I don't have the Ethernet interfaces" entry, as you'll
      probably hit this issue if you don't reinstall from scratch.

    * Is there an echo canceller?

      Yes, we enable by default OSLEC, through the module "echo".
      "dahdi_echocan_oslec" is its dahdi interface.
      To desable it, remove the call in system.conf dahdi file.


  ==  Tips ==

    Setup the serial console with GRUB LEGACY
    You need to edit the `/boot/grub/grub.conf` file, by adding at the top:

        serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
        terminal serial

    Then, every kernel entry should looks like:

        kernel          /vmlinuz-2.6.32-5-686 root=/dev/sda4 ro console=ttyS0,115200n8


<!-- vi:syntax=markdown:tw=80
  -->