Blackfin Asterisk Package System (BAPs) ======================================= [[intro]] Introduction ------------ Package based Build system for Blackfin Asterisk. Key differences compared to buildroot based systems like Astfin and uCasterisk: + End users do not need to compile any software, they just install them on a running Blackfin system, for example: + root:~> ipkg install asterisk + will grab the latest Asterisk package from a web site and install it on a Blackfin based hardware platform. Use is not limited to Asterisk, it could be used to manage any Blackfin software, including the kernel. The use of ipkg is very common on the OpenWRT project, and similar package based systems are common on x86 Linux, e.g. apt-get, debs, rpms. + Note that software is installed at run time rather than build time. Packages (via ipkg) are used to install applications like Asterisk, rather than placing everything in a uImage. The target hardware is initially booted with a basic kernel and root file system, then packages are installed as required. We assume availability of persistent (non ram) based file system like yaffs or jffs2. + The goal is to make installing software on the Blackfin much easier for end-users, more like an x86 experience. + Compared to buildroot systems BAPS has a flat directory structure to ease development (less wear on your tab key). It is designed to allow modular compilation of packages, e.g. you can compile a single application without building the entire uImage. Faster and less output to wade through. Makefiles (e.g. asterisk.mk) and source (e.g. asterisk-1.4.4) are within one directory level of each other for easy navigation of the source tree. There is less chance of breaking the build system due to decoupling of modules (kernel, root fs, are separate from Asterisk). [[packages]] Packages -------- In addition to an IP04/IP08 uImage (kernel plus basic root filesystem) there is a growing list of packages: [frame="all",grid="all"] `15`20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Name,Description ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include::packages.csv[] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[started]] Getting Started --------------- The installation of the BAPs uImage is still a little complex (apologies). It requires working with u-boot using the RS232 console interface. For more information on this process please see the http://www.voip-info.org/wiki/view/IP04+Open+Hardware+IP-PBX[IP04 Wiki] or please post to the Blackfin Asterisk forum. However once the uImage is install life gets much easier! This process will *erase your IP04 root file system* so please backup anything you really need (like your asterisk conf files). 1/ Get the baseline BAPs uImage (contains kernel and basic root file system) and place it on your tftp server: http://www.rowetel.com/ucasterisk/downloads/uImage_r2.ip08 NOTE: Despite it's name, uImage_r2.ip08 works fine on both the IP04 and IP08. 2/ Connect a RS232 cable to your IP04 (via the daughter board) and stop the boot process at the u-boot prompt. Now we are going to write the new uImage to flash. your:mac:address can be found using *print* at the u-boot prompt. CAUTION: Do not cut/paste the steps below into your serial terminal program, as they often cannot respond fast enough and lose characters. Type each line carefully by hand. Install the new uImage into NAND flash using u-boot: ip04>set autostart ip04>set serverip your.tftp.server ip04>tftp 0x1000000 uImage_r2.ip08 ip04>nand erase clean ip04>nand erase ip04>nand write 0x1000000 0x0 0x300000 ip04>set bootargs ethaddr=your:mac:address root=/dev/mtdblock0 rw ip04>save ip04>bootm 0x1000000 (uClinux will boot.......) TIP: If Linux doesn't boot or you experience other problems reboot into uboot, type "print", and carefully check bootargs 3/ Now we have uClinux running, but using a ram-based ext2 file system (mtdblock0) for root. So we need to copy /root into the yaffs file system: On the IP04: root:~> copy_rootfs.sh root:~> reboot 4/ Now set up u-boot to mount root from yaffs (some of these env variables may be set already, use 'print' to check): ip04>set autostart yes ip04>set bootargs ethaddr=your:mac:address root=/dev/mtdblock2 rw ip04>set nandboot 'nboot 0x2000000 0x0' ip04>set bootcmd run nandboot ip04>save ip04>reset 5/ Boot IP04 to a uClinux root prompt. Use mount to check that root is mounted on mtdblock2 (yaffs file system). Now we can install some packages using ipkg: $root:~> ipkg update $root:~> ipkg install zaptel-spi asterisk native-sounds $root:~> reboot [[doco]] Documentation ------------- After installation many packages include documentation in the /usr/doc directory of the IP04. These are small files designed to capture Blackfin or IP04 specific information, for example simple tests and notes on differences from other versions of the same package. The documentation files can also be browsed from http://svn.astfin.org/software/baps/trunk/doc[BAPS SVN]. [[howto_developer]] HOWTO - Developer ----------------- 1/ svn co http://svn.astfin.org/software/baps/trunk baps 2/ You need this toolchain: [baps]$ wget http://blackfin.uclinux.org/gf/download/frsrelease/ \ 348/3347/blackfin-toolchain-07r1.1-3.i386.tar.gz [baps]$ tar xzf blackfin-toolchain-07r1.1-3.i386.tar.gz If you untar the toolchain in baps directory then it will be included in your path automatically. If you untar it somewhere else make sure the bin directories in this toolchain are in your path. 3/ Make a BAPS uImage that supports ipkg. This also configures uClinux-dist to support compiling of other packages. You need to make uClinux before making any other packages. [baps]$ make -f uClinux.mk uClinux [baps]$ cp uClinux-dist/images/uImage /tftpboot/uImage You can then try booting from your uImage via tftp, in u-boot: ip04>set autostart ip04>set bootargs ethaddr=your:mac:address root=/dev/mtdblock0 rw ip04>save ip04>tftp 0x1000000 uImage ip04>bootm Or you can flash the uImage as described in the <> section above. 4/ Check out ipkg.conf: root:~> cat /etc/ipkg.conf src snapshots http://rowetel.com/ucasterisk/ipkg dest root / Try installing a simple ipkgs: root:~> ipkg update root:~> ipkg list root:~> ipkg install hello root:~> hello 5/ BAPS uses init.d type start up scripts, for example: root:~> ls /etc/init.d root:~> /etc/init.d/hello root:~> /etc/init.d/hello enable root:~> ls -l /etc/rc.d/ [[howto_ipkg]] HOWTO - IPKG ------------ To build the ipkg: [baps]$ make -f hello.mk hello [baps]$ make -f hello.mk hello-package [baps]$ ls ipkg To create an index file: [baps]$ cd ipkg [baps]$ ../scripts/ipkg-make-index.sh . > Packages [baps]$ scp Packages /your/web/server Then change the first line in /etc/ipkg.conf on your IP04: src snapshots http://you.web.server And try: root:~> ipkg update root:~> ipkg list NOTES: 1/ If you change the post or pre inst scripts, it is a good idea to rm the existing $(TARGET_DIR) (see Makefile for your package), as the package make scripts don't seem to recognise when post/pre scripts have been changed. 2/ To debug post/pre inst scripts #!/bin/sh -x is your friend! 3/ To test ipkgs you can rcp down to the target: [host]$ rcp ipkg/asterisk_1.4.4-1_bfin.ipk root@ip04:/root [ip04]$ ipkg install asterisk_1.4.4-1_bfin.ipk If you get complaints about MD5 mismatch, then: [ip04]$ rm /usr/lib/ipkg/lists/snapshots [[howto_uclinux]] HOWTO - uClinux Changes ----------------------- Say you have changed a busybox option, or modified some files in uClinux-dist. To capture the changes to patches in SVN: [baps]$ make -f uClinux.mk uClinux-ip04-make-patch [baps]$ svn status Tips: To change linux kernel options: [baps]$ cd uClinux-dist [uClinux-dist]$ make linux_menuconfig (kernel changes) To change user application and library settings: [baps]$ cd uClinux-dist [uClinux-dist]$ make config_menuconfig To modify the IP04 rc, motd etc: [baps]$ cd uClinux-dist/vendors/Rowetel/IP04 (mess with files) Then capture changes as above with: [baps]$ make -f uClinux.mk uClinux-ip04-make-patch Notes ~~~~~ 1/ Patch files are compatible with Astfin, so hopefully it's possible to move patches back and forth between BAPS and Astfin. 2/ See TODO.txt 3/ To debug init shell scripts, e.g. files/hello.init, add a -x to the first line if the script using vi on the IP04: #!/bin/sh -x 4/ When writing init scripts your will find the busybox msh shell has some quirks, here is a link that explains them (all one line): http://dslinux.org/cgi-bin/moin.cgi/DSLinuxMshScriptingGuide? action=show&redirect=DSLinux+msh+scripting+guide 5/ For more information on the IPKG format: http://handhelds.org/moin/moin.cgi/Ipkg 6/ On the target, the ipkg data is stored in /usr/lib/ipkg/info/ [[directories]] Directories ----------- ipkg - completed packages are placed here include - from OpenWRT kamikaze, contains useful stuff for building packages. scripts - Useful scripts from OpenWRT kamikaze patch - patches for all packages files - start up scripts for packages, get copied to /etc/init.d on target [[g729]] G729 Codec Installation ----------------------- Analog Devices has developed an optimised g729 library for the Blackfin that can run on the IP04. Note that you require a license from Sipro to run this g729 codec legally. Here are the instructions for building and installing the g729 codec. Familiarity with compiling Blackfin code for the IP04 is assumed. 1/ Make sure the 2007 toolchain is installed as per the <> above. You path should include these directories: /path/to/baps/opt/uClinux/bfin-linux-uclibc/bin /path/to/baps/opt/uClinux/bfin-uclinux/bin 2/ Change the processor type in uClinux-dist/linux-2.6.x/.config to BF533: # CONFIG_BF532 is not set CONFIG_BF533=y Rebuild the uImage. You can test it by booting the uImage from ram: ip04>tftp 0x1000000 uImage;bootm Check that it boots as a BF533. Now flash this new uImage. It is possible to install this new kernel without erasing your root file system if you **just** erase the first 0x300000 of flash. ip04>set autostart ip04>set serverip your.tftp.server ip04>tftp 0x1000000 uImage_bf533 ip04>nand erase clean 0x0 0x300000 ip04>nand erase 0x0 0x300000 ip04>nand write 0x1000000 0x0 0x300000 3/ Check out and build libbfgdots: $ svn co svn://sources.blackfin.uclinux.org/uclinux-dist/trunk/lib/libbfgdots libbfgdots $ cd libbfgdots; make Now rcp libg729.so from libbfgdots to /lib on your IP04. When Asterisk boots it should load the g729 codec. Check the codec is installed with 'show translate' at the Asterisk CLI. [[credits]] Credits ------- Thanks to: Jeff Knighton, Alex Tao, Ming C (Vincent) Li, Mike Taht, Keith Huang, Mark Hindess, Nick Basil and Michael O'Conner for contributing. Thanks Bruce and Jan at Voiptel for the great work on the GUI. [[Voiptel]] VoipTel GUI Installation ------------------------ Bruce and Jan at http://voiptel.no/content/view/23/42/lang,en/[Voiptel] have recently done some great work on upgrading and debugging the AsteriskNow GUI for the IP04, using a modified version of several BAPS packages. We are working with Voiptel to make the Voiptel firmware more compatible with existing BAPS packages (for example share a common uImage, remove duplication of common packages. At the moment there are two versions of the Voiptel GUI, the new single-IPKG that is integrated with the other BAPs packages, and the version that requires a fresh uImage installation. Over the next few weeks this will migrate to one version. In the mean time, here are two sets of install instructions..... New Single IPKG Version ~~~~~~~~~~~~~~~~~~~~~~~ Assuming you have an IP04 with asterisk installed and running, just install the Voiptel GUI: root:~> ipkg update root:~> ipkg install voiptel-gui-pre root:~> reboot Thats it! The source code is available from http://svn.astfin.org/software/baps/trunk/voiptel-gui[here]. uImage Version ~~~~~~~~~~~~~~ The source code (package makefiles, GUI source etc) is available from the http://update.voiptel.no[Voiptel upgrade site]. Here are the instructions (thanks Bruce) for installing the Voiptel firmware: 1/ Download http://update.voiptel.no/uImage_r2.ip08[uImage_r2.ip08] and place the uImage on your TFTP server. NOTE: This uImage file is different to the uImage_r2.ip08 image from this site, it contains changes required to support the Voiptel GUI. 2/ Follow steps 1-5 in the <> section above. 3/ If your gateway happens to be 192.168.1.1 then the IP04 should automatically go online and fetch the needed packages and install them. If not you will have to change the network settings and reboot (replace x's with your gateway IP address, and y's with the new IP04 IP address). NOTE: There are two spaces after 'nameserver' root:~> sed -i 's/nameserver 192.168.1.1/nameserver xxx.xxx.xxx.xxx/g' /etc/network.sh root:~> sed -i 's/gw 192.168.1.1/gw xxx.xxx.xxx.xxx/g' /etc/network.sh root:~> sed -i 's/192.168.1.100/yyy.yyy.yyy.yyy/g' /etc/network.sh root:~> reboot 4/ When the IP04 boots up again it should start the installation process, which will take 10-15m, depending on your Internet connection. 5/ Once installation completes, reboot the IP04. It will start up with the default IP addresses again, so do the following if you use different addresses: * Set your PC to use the same network address (eg. 192.168.1.200) * Enter 192.168.1.100 into your web browser (preferably Firefox) * Login with admin / mysecret * Go to Options -> Show Advanced Options -> Network & Country Settings * Make the necessary changes, click Save and reboot * Change your own IP address back [[Voiptel_ug]] VoipTel GUI User Guide ---------------------- Well, not really a user guide! Just some basic notes to get started: * Point your web browser at your IP04 and login with admin/mysecret * I also start up an Asterisk CLI session so I can see what the GUI is up to. * The first step is to create a default Dialplan - without this none of the extensions can call each other. Go to *Calling Rules* and *click here* to create Dialplan1. Click *Activate Changes*. That's it for this menu. * Now lets set up a couple of FXS analog extensions. Go to *Users* and change the *6004 - David* extension to your name. From the *Dial Plan* box select *DialPlan1*. Uncheck the SIP and IAX check-boxes. Click *Save* then *Activate Changes*. * Now create a new analog extension. Click *New* then fill in some details like *Extension* and *Name*. Select *Analog Phone* to match a free FXS port (say Analog Port #3). Uncheck the SIP and IAX check-boxes. From the *Dial Plan* box select *DialPlan1*. Click *Save* then *Activate Changes*. * Now you should be able to dial one extension from another. * To add a SIP phone create a new extension (say 6015). In the password field enter the SIP password (e.g. lets also make this 6015). Check the SIP check-box. Click *Save* then *Activate Changes*. * Configure your SIP phone (e.g. via it's web interface) to be username/password 6015/6015 and the SIP server to be your IP04. Now try dialling the SIP phone from one of the analog phones. * Check out the CLI to see what the GUI is up to. This is what I found after setting up two analog (6004 and 6016), and one SIP (6015) extensions: + ------------------------------------------------------------------------------ ip04*CLI> show dialplan default [ Context 'default' created by 'pbx_config' ] '.' => 1. Goto(${EXTEN}) [pbx_config] '6004' => hint: Zap/4 [pbx_config] 1. Macro(stdexten|6004|${HINT}) [pbx_config] '6015' => hint: SIP/6015 [pbx_config] 1. Macro(stdexten|6015|${HINT}) [pbx_config] '6016' => hint: Zap/3 [pbx_config] 1. Macro(stdexten|6016|${HINT}) [pbx_config] ip04*CLI> sip show peers Name/username Host Dyn Nat ACL Port Status 6015/6015 192.168.1.23 D 5060 Unmonitored ip04*CLI> zap show channels Chan Extension Context Language MOH Interpret pseudo default 1 default default 2 default default 3 numberplan-cust default 4 numberplan-cust default ------------------------------------------------------------------------------ GUI Gotchas ~~~~~~~~~~~ I was caught by these: * On my web browser (Firefox on an Ubuntu laptop) I sometimes can't see buttons like New and Save on the bottom of the Users Page. To see them I decreased my font size using Ctrl--. * If you get a busy tone when you try to dial make sure you have selected a Dialplan (e.g. Dialplan1 above) for that phone. [[todo]] BAPS TODO --------- Some tasks that need doing....: + Work out a way to install uImage.ip08 without u-boot, i.e. from a uClinux root prompt. This will take much of the pain away, kernels can then be treated like packages. + Can we install kernels (uImage) using a package and no u-boot/RS232? + Should we separate kernel from baseline root file system install? + BAPS uImages for BF537 and BF533 + A way to build all packages needed for development, like ip08.mk, or maybe set up dependencies in existing Makefile, e.g. so that libssl.mk is called when making asterisk. Not sure about the best way to go here - the idea behind BAPs is to modularise compilation so I am sensitive to having many dependencies and all the extra output that would generate on the command line. + Fix the Maintainer Field in packages (e.g. specific entries for each package).