Support #407
Updated by Daniel Curtis almost 10 years ago
Follow these instructions only if you wish to compile your Jasper software from scratch. h2. Burn Raspbian image onto SD card We’ll first clear the SD card using GParted on Ubuntu, but you can use an equivalent utility or operating system. In GParted: right-click on each partition of the SD card, then select +Unmount+ and +Delete+. Apply the changes with +Edit -> Apply+ All Operations. Download Raspbian Wheezy from http://downloads.raspberrypi.org/raspbian_latest. While we’ve tested Jasper on the 2014-01-07 release, newer releases may also work. * We’ll use dd to burn the image to the disk. Obtain the address of the SD card with: <pre> sudo fdisk -l </pre> * Our device address was ‘/dev/mmcblk0’, so the following command burns the image to the disk: <pre> sudo dd if=2013-12-20-wheezy-raspbian.img of=/dev/mmcblk0 bs=2M </pre> When it’s done, remove your SD card, insert it into your Raspberry Pi and connect it to your computer via ethernet. h2. Configure Raspbian We’re now going to do some basic housekeeping and install some of the required libraries. You should SSH into your Pi with a command similar to the following. The IP address usually falls in the 192.168.2.3-192.168.2.10 range. * SSH into the Pi <pre> ssh pi@192.168.2.3 </pre> > password (default): raspberry * Run the following, select to ‘Expand Filesystem’ and restart your Pi: <pre> sudo raspi-config </pre> * Run the following commands to update Pi and some install some useful tools. <pre> sudo apt-get update sudo apt-get upgrade --yes sudo apt-get install vim git-core espeak python-dev python-pip bison libasound2-dev libportaudio-dev python-pyaudio --yes </pre> * Plug in your USB microphone. Let’s open up an ALSA configuration file in vim: <pre> sudo vim /etc/modprobe.d/alsa-base.conf </pre> Change the following line: > options snd-usb-audio index=-2 To this: > options snd-usb-audio index=0 * Back in the shell, run: <pre> sudo alsa force-reload </pre> * Next, test that recording works (you may need to restart your Pi) by recording some audio with the following command: <pre> arecord temp.wav </pre> * Make sure you have speakers or headphones connected to the audio jack of your Pi. You can play back the recorded file: <pre> aplay -D hw:1,0 temp.wav </pre> NOTE: If nothing is played, try turning up the microphone volume using @alsamixer@. * Add the following line to the end of @~/.bash_profile@ (you may need to run @touch ~/.bash_profile@ if the file doesn’t exist already): <pre> vi ~/.bash_profile </pre> > export LD_LIBRARY_PATH="/usr/local/lib" > source .bashrc </pre> * And this to your @~/.bashrc@ or @~/.bash_profile@: <pre> vi ~/.bash_profile </pre> > LD_LIBRARY_PATH="/usr/local/lib" > export LD_LIBRARY_PATH > PATH=$PATH:/usr/local/lib/ > export PATH With that, we’re ready to install the core software that powers Jasper. h2. Install Pocketsphinx * Jasper uses Pocketsphinx for voice recognition. Let’s download and unzip the sphinxbase and pocketsphinx packages: <pre> wget http://downloads.sourceforge.net/project/cmusphinx/sphinxbase/0.8/sphinxbase-0.8.tar.gz wget http://downloads.sourceforge.net/project/cmusphinx/pocketsphinx/0.8/pocketsphinx-0.8.tar.gz tar -zxvf sphinxbase-0.8.tar.gz tar -zxvf pocketsphinx-0.8.tar.gz </pre> * Now we build and install sphinxbase: <pre> cd ~/sphinxbase-0.8/ ./configure --enable-fixed make sudo make install </pre> * And pocketsphinx: <pre> cd ~/pocketsphinx-0.8/ ./configure make sudo make install </pre> Once the installations are complete, restart your Pi: * <pre> reboot </pre> h2. Install CMUCLMTK, OpenFST, MIT Language Modeling Toolkit, m2m-aligner, Phonetisaurus Note that some of these installation steps take more time to complete than previous steps. * Begin by installing some dependencies: <pre> sudo apt-get install subversion autoconf libtool automake gfortran g++ --yes </pre> * Next, move into your home (or Jasper) directory to check out and install CMUCLMTK: <pre> svn co https://svn.code.sf.net/p/cmusphinx/code/trunk/cmuclmtk/ cd cmuclmtk/ sudo ./autogen.sh && sudo make && sudo make install cd .. </pre> * Then, when you’ve left the CMUCLTK directory, download the following libraries: <pre> wget http://distfiles.macports.org/openfst/openfst-1.3.3.tar.gz wget https://mitlm.googlecode.com/files/mitlm-0.4.1.tar.gz wget https://m2m-aligner.googlecode.com/files/m2m-aligner-1.2.tar.gz wget https://phonetisaurus.googlecode.com/files/phonetisaurus-0.7.8.tgz wget http://phonetisaurus.googlecode.com/files/g014b2b.tgz </pre> * Untar the downloads: <pre> tar -xvf m2m-aligner-1.2.tar.gz tar -xvf openfst-1.3.3.tar.gz tar -xvf phonetisaurus-0.7.8.tgz tar -xvf mitlm-0.4.1.tar.gz tar -xvf g014b2b.tgz </pre> * Build OpenFST: <pre> cd openfst-1.3.3/ sudo ./configure --enable-compact-fsts --enable-const-fsts --enable-far --enable-lookahead-fsts --enable-pdt sudo make install # come back after a really long time </pre> * Build M2M: <pre> cd m2m-aligner-1.2/ sudo make </pre> * Build MITLMT: <pre> cd mitlm-0.4.1/ sudo ./configure sudo make install </pre> * Build Phonetisaurus: <pre> cd phonetisaurus-0.7.8/ cd src sudo make </pre> * Move some of the compiled files: <pre> sudo cp ~/m2m-aligner-1.2/m2m-aligner /usr/local/bin/m2m-aligner sudo cp ~/phonetisaurus-0.7.8/phonetisaurus-g2p /usr/local/bin/phonetisaurus-g2p </pre> * Build Phonetisaurus model: <pre> cd g014b2b/ ./compile-fst.sh </pre> * Finally, rename the following folder for convenience: <pre> mv ~/g014b2b ~/phonetisaurus </pre> At this point, we’ve installed Jasper and all the necessary software to run it. Before we start playing around, though, we need to configure Jasper and provide it with some basic information. h2. Configuring the Jasper Client h3. Install Jasper Client * In the home directory of your Pi, clone the Jasper source code: <pre> git clone https://github.com/jasperproject/jasper-client.git jasper </pre> * Jasper requires various Python libraries that we can install in one line with: <pre> sudo pip install --upgrade setuptools sudo pip install -r jasper/client/requirements.txt </pre> * Run @crontab -e@, then add the following line, if it’s not there already: > @reboot /home/pi/jasper/boot/boot.sh; * Set permissions inside the home directory: <pre> sudo chmod 777 -R * </pre> Restart your Raspberry Pi. Doing so will run boot.py, which generates the languagemodel.lm file in the client/ folder. h3. Generating a user profile In order for Jasper to accurately report local weather conditions, send you text messages, and more, you first need to generate a user profile. * To facilitate the process, run the profile population module that comes packaged with Jasper <pre> cd ~/jasper/client python populate.py </pre> The process is fairly self-explanatory: fill in the requested information, or hit ‘Enter’ to defer at any step. The resulting profile will be stored as a YML file at profile.yml. Important: @populate.py@ will request your Gmail password. Of course, this is purely optional and will never leave the device. This password allows Jasper to report on incoming emails and send you text or email notifications, but be aware that the password will be stored as plaintext in profile.yml. The Gmail address can be entered alone (without a password) and will be used to send you notifications if you configure a Mailgun account, as described below. h3. Mailgun as a Gmail alternative If you’d prefer not to enter your Gmail password, you can setup a free Mailgun account that Jasper will use to send you notifications. It’s incredibly painless and Jasper is already setup for instant Mailgun integration. Note that if you don’t enter your Gmail address, however, Jasper will only be able to send you notifications by text message (as he won’t know your email address). In slightly more detail: # Register for a free Mailgun account. # Navigate to the “Domains” tab and click on the sandbox server that should be provided initially. # Click “Default Password” and choose a password. # Take note of the “Default SMTP Login” email address. # Edit your profile.yml to read: > ... > mailgun: > username: postmaster@sandbox95948.mailgun.org > password: your_password # Enjoy your notifications. h3. Facebook tokens To enable Facebook integration, Jasper requires an API key. Unfortunately, this is a multi-step process that requires manual editing of profile.yml. Fortunately, it’s not particularly difficult: # Go to https://developers.facebook.com and select ‘Apps’, then ‘Create a new app’. # Give your app a name, category, etc. The choices here are arbitrary. # Go to the Facebook Graph API Explorer and select your App from the drop down list in the top right (the default choice is ‘Graph API Explorer’). # Hit ‘Get Access Token’ with the default permissions. # Take the resulting API key and add it to profile.yml in the following format: > ... > prefers_email: false > timezone: US/Eastern > keys: > FB_TOKEN: abcdefghijklmnopqrstuvwxyz Note that similar keys could be added when developing other modules. For example, a Twitter key might be required to create a Twitter module. The goal of the profile is to be straightforward and extensible. Spotify integration Jasper has the ability to play playlists from your Spotify library. This feature is optional and requires a Spotify Premium account. To configure Spotify on Jasper, just perform the following steps. * Install Mopidy with: <pre> wget -q -O - http://apt.mopidy.com/mopidy.gpg | sudo apt-key add - sudo wget -q -O /etc/apt/sources.list.d/mopidy.list http://apt.mopidy.com/mopidy.list sudo apt-get update sudo apt-get install mopidy mopidy-spotify --yes </pre> * We need to enable IPv6: <pre> sudo modprobe ipv6 echo ipv6 | sudo tee -a /etc/modules </pre> Now run @sudo vim /root/.asoundrc@, and insert the following contents: <pre> pcm.!default { type hw card 1 } ctl.!default { type hw card 1 } </pre> * We need to create the following new file and delete the default startup script: <pre> sudo mkdir /root/.config sudo mkdir /root/.config/mopidy sudo rm /etc/init.d/mopidy </pre> * Now let’s run @sudo vim /root/.config/mopidy/mopidy.conf@ and insert the following > [spotify] > username = YOUR_SPOTIFY_USERNAME > password = YOUR_SPOTIFY_PASSWORD > > [mpd] > hostname = :: > > [local] > media_dir = ~/music > > [scrobbler] > enabled = false > > [audio] > output = alsasink Finally, let’s configure crontab to run Mopidy by running @sudo crontab -e@ and inserting the following entry: > @reboot mopidy; Upon restarting your Jasper, you should be able to issue a “Spotify” command that will enter Spotify mode. For more information on how to use Spotify with your voice, check out the Usage guide. h2. Software Architecture Having installed the required libraries, it is worth taking a moment to understand how they interact and how the client code is architected. Jasper utilizes a number of open source libraries to function. Pocketsphinx performs speech recognition via Python bindings to the CMUSphinx engine. Jasper’s voice is owed to the popular TTS program, eSpeak. Phonetisaurus and CMUCLMTK enable Jasper to generate dictionaries and language models on-the-fly based on the custom module vocabularies. Mopidy enables streaming from Spotify, for those users who wish to use the module. The client architecture is organized into a number of different components: h2. Jasper Client Architecture main.py is the program that orchestrates all of Jasper. It creates mic, profile, and conversation instances. Next, the conversation instance is fed the mic and profile as inputs, from which it creates a notifier and a brain. The brain then receives the mic and profile originally descended from main and loads all the interactive components into memory. The brain is essentially the interface between developer-written modules and the core framework. Each module must implement isValid() and handle() functions, as well as define a WORDS = [...] list. To learn more about how Jasper interactive modules work and how to write your own, check out the API guide h2. Resources * http://jasperproject.github.io/documentation/software/#manual-installation