-
Notifications
You must be signed in to change notification settings - Fork 1
001 Full Instructions
I'm doing this from an Ubuntu laptop. If you're using Windows or OSX, you'll probably have to do some different stuff, at least up until the point where you've got the operating system installed on the Edison.
You'll need to have wireless Internet wherever you are doing this setup; you'll have to download and install a lot of stuff onto the Edison through its wifi connection. You will, of course, also need to know the network name and password for said wifi.
Download and install the Ubilinux operating system for the Edison
Get the Ubilinux distro here:
http://www.emutexlabs.com/ubilinux
Then install it using these instructions:
https://learn.sparkfun.com/tutorials/loading-debian-ubilinux-on-the-edison and http://www.emutexlabs.com/ubilinux/29-ubilinux/218-ubilinux-installation-instructions-for-intel-edison
Which basically boils down to unpacking the archive, which generates a folder called toFlash, in which there is a script called flashall.sh. Open a terminal (if you don't know how to do that, this tutorial is not for you; you'll need someone familiar with command-line computing to help you), navigate to the toFlash folder and, before plugging the Edison into the computer, type:
sudo ./flashall.sh
If you forget the "sudo", it will not work. It might look like it's working, but it won't (unless you're already root on your computer, in which case you either know what you're doing already, or you're so far out to sea that this process failing will be the least of your problems).
Bug fix: If flashing from a Mac (possibly another station) fails, the following may work: append -R to the following 2 lines in flashall.sh, towards the bottom of the script, so they look as follows:
flash-command --alt u-boot-env1 -D "${VARIANT_FILE}" -R
flash-command --alt rootfs -D "${ESC_BASE_DIR}/edison-image-edison.ext4" -R
When the console says it's waiting for a device, connect the Edison to the computer with 2 USB cables, one for power and the other for serial communication.
Once you start this process, go away for a while; it takes 10 or 12 minutes and you really don't want to interrupt it. Go get some fresh air, kiss your significant other, or have some nachos.
NB. The process above may fail on some systems with the flash 'completing' in just 30 seconds, but actually with nothing having flashed. We encountered this with one minimal Ubuntu 'flasher'. A workaround is to run the script without the sudo prefix but as the system super-user. First just type su and your super-user password to access the su terminal.
Connect to the Edison from your computer and configure it to access the Internet
When the flashing is done, you should have a working basic Ubilinux (basically stripped-down Debian) distribution running on the Edison, which you can manage using a command line through a tty (teletype) interface over USB. The easiest way to do this is with a program called Screen. If you don't have that on your computer, you can get it like this:
sudo apt-get install screen
To get into the tty session, connect by typing (on the host):
screen /dev/ttyUSB0 115200
On a Mac, you will find the Edison by typing:
ls /dev/tty.usb*
then, using the identifier your found (if you have more than one USB device you may need to do the previous line twice, once with the Edison unplugged and once with it plugged in and look for the one that appears only when the Edison is plugged in):
screen /dev/tty.usbserial-xxxxx 115200
That should get you into a console running as a terminal for the Edison. The terminal may be blank/empty at first, you might have to hit a random key (shift or return) to wake up the terminal. You should, at some point, possibly after a long run of gibberish, get a login prompt. Log in as user root, using password edison.
If you don't know how to work on a UNIX command line, you will need to do a LOT of reading, or find someone who can teach you. I'm afraid it's way beyond the scope of these instructions.
Use the Nano editing program (already on the Edison by default) to edit files on the Edison. If you haven't used Nano before, have a look at this: http://www.howtogeek.com/howto/42980/the-beginners-guide-to-nano-the-linux-command-line-text-editor/). If you don't want to read that here's the upshot: do your editing in Nano using the keyboard and arrow keys, push control-o then Enter to save, and control-x to quit the program and return to the command line.
The first file to edit is /ect/network/interfaces. Here you will instruct the Edison to listen for a wireless network, and provide it with the network name (ssid) and password.
nano /etc/network/interfaces
This will open a file full of cryptic lines, some of which have hashmarks # in front of them. The hashmarks are a convention for creating "comments"; they are not part of the functioning code in the file. Some of the "comments" are actually working code that we don't want to run right now; this is called "commenting out" code. Removing the hashmark beginning a line "uncomments" it, and it will be executed. This file actually contains many different possible network configurations, some of which are commented out and others active.
You need to comment out the "auto usb0" line and uncomment wlan0, and specify the ssid and password for the nearest wifi access point (you are replacing the Ubilinux example defaults of "Emutex" and "passphrase"). When you're done, the interfaces file should look like this (in fact you could erase the whole file and copy-paste this in if you want, of course changing the wireless username and password to match the internet connection where you are working):
# interfaces(5) file used by ifup(8) and ifdown(8)
auto lo
iface lo inet loopback
#auto usb0
iface usb0 inet static
address 192.168.2.15
netmask 255.255.255.0
auto wlan0
iface wlan0 inet dhcp
# For WPA
wpa-ssid mywirelessnetwork
wpa-psk mypassword
# For WEP
#wireless-essid Emutex
#wireless-mode Managed
#wireless-key s:password
# And the following 4 lines are for when using hostapd...
#auto wlan0
#iface wlan0 inet static
# address 192.168.42.1
# netmask 255.255.255.0
Note the ssid "mywirelessnetwork" and password "mypassword". Obviously, you should use the appropriate ssid and password for the internet connection wherever you are, since you need the Edison to get on the internet to download stuff for the next steps. When you're done, quit Nano (control-o then Enter to save, then control-x to quit).
Now change the hostname of your Edison, which is "ubilinux" by default, to whatever you want to call the Edison. I'm changing it to "missing-maps" but you can call it whatever you wan to. The /etc/hostname file, where the name is specified, is only one line long and simply contains the name, which is what all other devices on a network will see as the name of the edison.
nano /etc/hostname
Now reboot the Edison with this command, after which it should wake up and find itself connected to the Internet:
reboot
Your connection through Screen (the tty connection) should survive the reboot. If it doesn't just log in using Screen as before. The Edison should, if all has gone well up to now, have a connection to the internet. Check this, and incidentally find out your IP address on your local network, using the program ifconfig:
ifconfig
This will spit out a bunch of text that should include your dotted-quad IP address (in the form x.x.x.x; it will be the one in wlan0, perhaps something like 192.168.1.212). If you do not see this, your Edison is not connected to the Internet, and the following steps will not work.
##Now let's install some basic infrastructure
Assuming you've logged in again (as user "root" with password "edison", either via ssh or Screen), you're now on a command line with a basic, running Ubilinux distro connected to the internet. Good to go.
Run the updater to update all of the Debian packages
apt-get update
apt-get upgrade
Make some room on the root partition
The root partition on the Ubilinux setup is very tight for space. In what is NOT a very nice workaround (in fact it's quite a nasty hack), I've elected to move the /var/ folder into the home partition. After doing this, it's critical to create a link back to it so that the operating system can still deal with it; this is accomplished by creating a Symbolic Link or symlink using the ln (link) command.
mv /var /home/edison/
ln -s /home/edison/var/ /var
Depending on the circumstances, you may later put the /var/ folder back where it belongs, but for the moment we want to avoid hitting the storage ceiling. Speaking of that, a friend once showed me how to delete all the .deb files that had already been installed and were taking up space; I should try to remember how to do that.
Install Java (must be Java 7)
apt-get install openjdk-7-jdk
It will probably ask you to confirm you want to do this, type "Y" and enter and it will proceed.
This takes a while (depending on the speed of your internet connection). Once again I suggest passing the time by getting some fresh air, kisses, or nachos. Come back after 10 or 15 minutes, and if it's finished scrolling gibberish up the screen and is back in a command line, check if it worked by typing:
java -version
It should say 'java version "1.7.0_75"' or something like it.
Now install Tomcat 6
Tomcat 6 is pretty old, but Tomcat 7 requires extra configuration for ODK Aggregate; even though it's possible to get it working there seem to be some subtle problems with updating passwords and so forth which only appear quite late in the whole process and which I don't want to deal with right now, so I'd advise that you stick with Tomcat 6 for now.
apt-get install tomcat6 tomcat6-admin
Now you have to get into the tomcat-users configuration file to set passwords.
nano /etc/tomcat6/tomcat-users.xml
From inside the editor, add the following just before the end of the file (so just before the </tomcat-users> at the end:
<role rolename="manager"/>
<role rolename="admin"/>
<user username="admin" password="admin" roles="admin,manager"/>
or if using Tomcat 7 add the following:
<role rolename="manager-gui"/>
<role rolename="admin"/>
<user username="admin" password="admin" roles="admin,manager-gui"/>
By the way, if you're using Tomcat 7 (which I don't recommend at this stage), you'll need to modify the /etc/tomcat7/context.xml file. Go to the opening tag and add an attribute inside the opening tag so it reads thus:
<Context useHttpOnly="false">
Install PostgreSQL
PostgreSQL is a database, which ODK Aggregate will use to store and manipulate data behind the scenes. It's often called Posgres for short. It's a pretty advanced database, and you could use a simpler one called MySQL instead, but that requires the use of a Java-to-database connector utility that you have to download from Oracle, which means registering for an Oracle account, and basically just pisses me off. I prefer Postgres anyway, for a lot of reasons, and it works perfectly well with ODK Aggregate. Use the echo command to create the file /etc/apt/sources.list.d/pgdg.list, and add the PostgreSQL repository to it:
echo deb http://apt.postgresql.org/pub/repos/apt/ wheezy-pgdg main >> /etc/apt/sources.list.d/pgdg.list
Now perform the actual install:
apt-get install wget ca-certificates
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
apt-get update
apt-get install postgresql-9.4 postgresql-client
Now set the root password for Postgres with this set of commands that basically make you into the user "postgres" (who is allowed to muck with the database). Please note that there is a space before and after the hyphen on the su command. Then run the Postgres program itself, which appears as its own command line:
su - postgres
psql
Now, within the Postgres command line, add a password with this command. Yes, the command includes the backslash! It'll ask you to provide a password twice. I've used "all4one". You can use whatever you want (but do try to remember it).
\password postgres
all4one
all4one
Now get out of postgres command line and stop being the "postgres" user and get back to being root user
\q
exit
apt-get install nginx
service nginx start
Symlink the Nginx folder to /home, again to avoid running out of room on the Edison's root partition:
mv /usr/share/nginx/www /home/edison/
ln -s /home/edison/www/ /usr/share/nginx/www
If you know how to run a webserver, bully for you, you'll almost certainly do something better than what I'm about to propose:
Nginx has a default web page, called index, in the www folder. A proper developer or admin would leave this alone and make a new site, but I'm lazy and incompetent so I'm just going to modify the existing site. We'll deal with that later; for the moment I just wanted to get Nginx installed while we were still connected to the internet.
Here's a sample of the HTML for a really basic welcome screen. You can replace the text in /usr/share/nginx/www/index.html with this, or copy it into a file, call it index.html and copy it over to the Edison, or make your own web page.
nano /usr/share/nginx/www/index.html
And paste in the following with your own tweaks to taste:
<html>
<head>
<title>ODK Aggregate in your pocket courtesy of the Missing Maps</title>
</head>
<body bgcolor="white" text="black">
<center><h1>Welcome to the Missing Maps Micro-server.</h1>
<p>You are not on the Internet. This page is hosted on a tiny server near you.</p>
<p> Here is the local <a href="http://192.168.0.1:8080/ODKAggregate">Aggregate server.</a> Connect to it to upload blank forms and download completed forms. Use the same URL to connnect your ODK Collect applications on your surveyor's phones to the server.</p>
<p>You should install ODKCollect on your phone. Get it <a href="/files/ODK Collect v1.4.6 rev 1051.apk" download>here</a>.</p>
<p>Here, for that matter, is a copy of <a href="/files/net.osmand.plus_212.apk" download>OSMAND</a> which should be very helpful for navigating.</p>
<p>And here is the OSMAND <a href="/files/South_Kivu.obf" download>map file for South Kivu</a>.</p>
<p>Here are some <a href="instructions.html">instructions</a> to set up the surveying software on everyone's phones.</p>
<h2>Good luck, stay safe, and support free software and open data!</h2>
</center>
</body>
</html>
By the way, note that I've included a link to the ODK Aggregate server on the website. This needs to match the actual IP address you give the Edison when you set up your actual ODK Aggregate server. You will need to give the same address to the Aggregate setup script, otherwise the link from your welcome page will fail.
For that matter, I've included links to downloadable resources, which of course are not present at the moment. We'll add those later, when we've established an ssh connection to the server (after the next step of turning the Edison into an Access Point).
From here on in, we're not going to use the internet connection anymore. We'll now turn the Edison into its own access point, which is the whole point of the exercise: to produce a webserver that implements ODK Aggregate fully offline! The Edison will be a server on a Local Area Network (LAN) that it establishes using its wifi transceiver. This is a bit like a mobile phone providing a "mobile hotspot" (or whatever the Apple marketroids call it on the iPhone), except that it's running an actual web server rather than sharing an Internet connection.
Install hostapd, dnsmasq, and dnsutils
You'll need to install dnsmasq and hostapd. These are programs that will allow the Edison to be an access point without requiring a router to connect to it.
apt-get install dnsmasq
Unfortunately the version of hostapd natively installed in Ubilinux doesn't work with the hardware. You need to upgrade to the testing version of hostapd. Instructions about this are here: https://communities.intel.com/thread/61455 (see the bit labeled "Correct Answer). Heres's the upshot:
Set up Ubilinux to update with the repository for the "testing" versions of various tools with this command that adds a repository of bleeding-edge packages to the sources list:
echo deb http://ftp.us.debian.org/debian testing main contrib non-free >> /etc/apt/sources.list
Now, to avoid updating everything with testing versions (which would probably result in a total collapse of the operating system), we're going to "pin" a bleeding-edge package, which allows Ubilinux/Debian to mix bleeding-edge packages with stable ones. This command will create the file if it doesn't exist
echo 'Package: hostapd
Pin: release a=testing
Pin-Priority: 900' >> /etc/apt/preferences
Now run an update so that the testing repos will be included in those scanned by Ubilinux when it looks for stuff to install (note that the output will include a series of "Ignore..." lines and a suggestion to run apt-get update to fix the problems, don't worry this doesn't affect us). Then install the new hostapd.
apt-get update
apt-get -t testing install hostapd
At some point it will ask permission to restart services during package updates without asking permission, use the arrow keys to toggle to say "Yes" and let it carry on.
It will then ask if you want to install the package maintainer's version of the configuration file or keep your own; enter "N" to refuse the package maintainer's version. You need to retain the original Ubilinux version of the configuration script /etc/init.d/hostapd, which is customized for the Edison. To reiterate: do NOT accept the package maintainers version of the configuration file!
Now to install some tools that will help us set up a DNS nameserver (this allows us to specify what names connect to what IP addresses for all devices on the network, the upshot of which is you can tell people "connect to this wifi network, and then type this easily-remembered name into a browser, and you'll be connected to the Edison's welcome page, which will then provide you with everything else that you need).
apt-get install dnsutils
What we need to do is to specify what nameserver you want to contact; contact localhost instead of internet (this is part of dhcp, which not only serves an IP address but also tells the client who to use as a nameserver).
In the hosts file, which on any computer tells it what names it should associate with various IP addresses, add whatever name you want people to use to connect to your Edison (I'm using mm, which stands for Missing Maps, and happens to be very short and easy to type):
echo 192.168.0.1 mm >> /etc/hosts
Or whatever you want as the name that people will use to connect to your Edison (you could use "server" or whatever, instead of mm). The name mm, by the way, refers to the Missing Maps, the project for which this server is being first deployed http://missingmaps.org. It doesn't correspond to anything real in the world, it's purely a local name, on the local area network, for the IP address of the Edison. You will need to give this name to the setup script when you actually set up the ODK Aggregate server, or your instance of ODK Aggregate will not function correctly.
Now set up the range of IP addresses offered by the Edison.
echo dhcp-range=192.168.0.50,192.168.0.150,12h >> /etc/dnsmasq.conf
Now configure the Access point (AP)
Now you can configure the four files that need to be fiddled to run an AP: /etc/hostapd/hostapd.conf, /etc/default/hostapd, /etc/network/interfaces, and udhcpd-for-hostapd.conf.
Append the ssid and password you want for your AP to the hostapd.conf file:
echo 'ssid=MissingMaps
wpa_passphrase=all4one' >> /etc/hostapd/hostapd.conf
Now edit the hostapd default configuration:
echo 'DAEMON_CONF="/etc/hostapd/hostapd.conf"' >> /etc/default/hostapd
Then edit /etc/network/interfaces (remember this one? It's where you set up the Edison to get on the Internet when it was first set up).
nano /etc/network/interfaces
Uncomment the lines relevant to hostapd and comment out the wlan interface. While you're in there, add the line "post-up service hostapd restart". For some reason this seems to avoid you having to manually restart the hostapd service. When you're done, the interfaces file should look like this:
# interfaces(5) file used by ifup(8) and ifdown(8)
auto lo
iface lo inet loopback
#auto usb0
iface usb0 inet static
address 192.168.2.15
netmask 255.255.255.0
#auto wlan0
#iface wlan0 inet dhcp
# For WPA
# wpa-ssid mywirelessnetworkd
# wpa-psk mypassword
# For WEP
#wireless-essid Emutex
#wireless-mode Managed
#wireless-key s:password
# And the following 4 lines are for when using hostapd...
auto wlan0
iface wlan0 inet static
post-up service hostapd restart
address 192.168.0.1
netmask 255.255.255.0
Now kill the special version of the dchp server (udchpd) that is specifically built for hostapd:
nano /etc/hostapd/udhcpd-for-hostapd.conf
We're going to set its only interface to be a loopback, which keeps it out of the way and allows dnsmasq to take charge. At the top of the file there's a line that says "interface wlan0 #default: eth0", change that to
interface lo
Now reboot, and you should see a new wireless network appear in the room; it is your Edison, now an independent provider of a Local Area Network.
Download and run the ODK Aggregate installer Download the ODK Aggregate installer for your host platform (you're back on your own computer now, not in a terminal running the Edison). You will run the installer on your machine, not on the Edison.
https://opendatakit.org/downloads/
Pick the one appropriate to your host machine (so I choose the Linux x64 installer, since I'm running 64-bit Ubuntu, you pick the one that fits your computer). You can't run the installer on the Edison because it doesn't have a desktop, you have to run it on your computer. It will generate a folder containing files you need to then transfer to the Edison.
If you've downloaded the install to a UNIX machine, you may need to make it executable:
chmod +x /path/to/installer
Double-click the installer to run it. Assuming you've done everything according to the instructions on this page, the address of your instance is 192.168.0.1, so that's what you'll tell the ODK Aggregate installer is you internet-visible IP address.
I used all default settings, leaving the username "odk_user" (the default) and password "all4one" for the database. I left the database name "odk_prod" (default in the installer). Name of instance I used Ivan, and the Aggregate Username was surveyor. At the end of this process you'll have a .war file, a .sql file, and a readme. The readme outlines the remaining steps reasonably well.
The specific steps for the ODK Aggregate installer
These are not code but I've put them in a code box as they are very specific steps to follow:
I accept the agreement -> forward
Choose a folder to create the files which will then be uploaded to the Edison -> forward
PostgreSQL -> forward
-> forward
-> forward
No, I do not have an SSL certificate -> forward
HTTP/1.1 connector port: 8080 (leave as default),
Internet-visible IP address or DNS name: mm (or whatever name you used)-> forward
-> forward
Database port number: 5432, Database server (leave as default)
hostname: 127.0.0.1 (leave as default) -> forward
Database username: odk_user (leave as default)
Database password: all4one (remember you set this up when configuring Postgres?)
Retype password: all4one -> forward
Database Name: odk_prod, Database Schema Name: odk_prod -> forward
Name of your instance: Missing Maps (or whatever you want) -> forward
ODK Aggregate Username: surveyor (or whatever you want, but remember it) -> forward
-> forward
The installer will now generate a folder where you specified, containing three files, one called create_db_and_user.sql, one called ODKAggregate.war, and one called README.html (the latter which probably popped up in a web browser exhorting you to complete the installation).
##Now get these files onto the Edison to build the server!
The easiest way to do this is to use a tool called scp (Secure Copy). This is closely related to ssh (Secure Shell, the tool you might have used to talk to the Edison in the optional step near the beginning). The scp utility basically moves files between computers in a secure fashion; for our purposes at the moment we don't care so much about security as we do about a practical method to copy data onto a computer without any kind of obvious file manager or graphical user interface!
First you'll need to connect to the Edison's AP. Go to your wireless settings on your computer, and connect to the wireless of the Edison (if you've used the precise settings from this page, it's called MissingMaps, and the password is all4one). Once you're on, you should be able to connect to the Edison directly. You can test this by opening a browser and simply typing "mm/" or whatever you've used as a name for your server in the DNS setup plus a slash (/); it should take you to the welcome page you set up with Nginx.
Copy the Postgres configuration script onto the Edison using scp.
These commands are to your computer in a terminal, not to the Edison!
scp /path/to/create_db_and_user.sql root@mm:/home/edison
scp /path/to/ODKAggregate.war root@mm:/home/edison
Now, still from your computer, connect to the Edison by ssh:
ssh root@mm
or just use Screen from your computer again. Log into the command line of the Edison (back to running commands on the Edison now) and set up the database like this
su - postgres
psql
\cd /home/edison
\i create_db_and_user.sql
a bunch of echo commands in caps appear, then you're dumped into a postgres command line with the database name as the prompt (odk_prod if you didn't modify anything). Finished with that, get out of Postgres:
\q
exit
Now copy the .war file from /home/edison/ (where you put it using scp from your computer) into the Tomcat webapps folder, which is cleverly hidden in /var/lib/tomcat6/webapps.
cp /home/edison/ODKAggregate.war /var/lib/tomcat6/webapps/
It should start working right away. If it doesn't try the following:
service tomcat6 restart
Now you should have a working ODK Aggregate server! However, it's still unsecured. Go to the webapp at http://mm:8080/ODKAggregate and sign in as the superuser (surveyor in this case). The default password is aggregate. Change that immediately or Aggregate will continue harassing you about it (I made it all4one, but you can use whatever password you want). You can also create more users, which is a good idea if you want your mappers to be able to upload their work but you don't want them accidentally erasing something! The phones with ODK Collect just need to be pointed to http://mm/ODKAggregate (with the appropriate username and password) and they can grab forms and submit data.
**If you have trouble connecting to "mm/" or whatever you've used as the name for the IP address, you can always replace the "mm/" with the actual IP address of the Edison, which if you've followed everything here scrupulously will be 192.168.0.1.
##Put the downloadable resources in the Nginx folder
This is very useful if you want to set up people's phones without the internet! You can install ODK Collect without having access to the Play Store (and without the hassle of doing it from a computer with a USB cable). You can also provide them with OSMAND (offline map viewer from the OpenStreetMap community, which I hope you're contributing to with the data you gather), and a map file for OSMAND (the use of all these programs is way beyond the scope of this already bloated tutorial, so please read up on that elsewhere)!
Add a folder for files:
mkdir /usr/share/nginx/www/files/
and upload the latest versions of ODK Collect and Osmand on them (and ensure the hrefs match the filenames), those download links will then work. Get ODK Collect here: https://opendatakit.org/downloads/download-category/collect/ and OSMAND here: https://f-droid.org/repository/browse/?fdid=net.osmand.plus (this version of OSMAND, from F-Droid, is the full version compiled from source with no encouragement to buy the full app; I encourage anyone using it in high-income countries to buy it from the Play Store, but in the case of humanitarian mapping projects where there is no Internet this is the way to go). The final link, to the map of South Kivu, is a placeholder (we are using it for a mapping project in South Kivu province of the Democratic Republic of the Congo); you probably want to change that to something else, assuming you want to include a map at all.
Upload them using scp from your computer:
scp /path/to/thingyouwannauploadfromyourcomputer root@mm:/usr/share/nginx/www/files/