Aphasia Development Tutorial

From Openmoko

(Difference between revisions)
Jump to: navigation, search
m (Where are all the menus?)
(Arcitecture)
Line 201: Line 201:
  
 
And in the Aphasia system, each service producer is a separate Erlang process. All services are running in parallell, just like in real life. The Erlang VM is quite different from other platforms in that respect, thousands or tens of thousands of processes running at the same time is not uncommon in a well designed system.
 
And in the Aphasia system, each service producer is a separate Erlang process. All services are running in parallell, just like in real life. The Erlang VM is quite different from other platforms in that respect, thousands or tens of thousands of processes running at the same time is not uncommon in a well designed system.
 +
 +
== The GSM Service producer ==
 +
Where should we start if not with the GSM service producer (I will use the name GSM process from now on), it's a phone for God's sake. What kind of service can we expect from the GSM process, can we expect to be able to be connected to, and able to communicate with, someone or something. The GSM process is always on, it's also invisible. Most processes can display themselves on the screen but the GSM process does not show up, it's running in the background listening to the different signals coming from the Calypso GSM chip.
  
 
[TBD]
 
[TBD]

Revision as of 22:33, 17 July 2009

Contents

Installation

This section is about setting up your Freerunner GTA02 for running the Aphasia distro.

OpenWrt

Aphasia sits on the OpenWrt platform. A very configurable Linux distribution, and light on system resources. There's a great forum at [1]

Go to OpenWrt, section Build custom image and follow the instructions. When you are at the point Configure target and packages you have to do some choises. Here is the minimum installation for Aphasia:

make menuconf

OpenWrt Kamikaze (r16871) Configuration

Target System (Samsung S3C24xx [2.6])  --->    Samsung S3C24xx [2.6]
Target Profile (Openmoko GTA-02 (minimal))  --->   Openmoko GTA-02 (minimal)

[*] Image configuration  ---> (192.168.0.202) LAN IP Address 

Xorg  --->    app  ---> <*> xauth
Xorg  ---> driver  ---> <*> xf86-input-tslib
Xorg  ---> driver  ---> <*> xf86-video-glamo
Xorg  --->   font  ---> <*> dejavu-fonts-ttf

Network  ---> <*> gpsd
Network  ---> <*> ser2net

Phone  ---> <*> freerunner-alsa-scenarios

Utilities  ---> <*> alsa-utils
Utilities  ---> <*> bash

Extra packages  --->  <*> zoneinfo-europe

Sound  --->   <*> lame
Sound  --->   <*> madplay

Languages  ---> <*> erlang

Configure gpsd and ser2net

To autostart ser2net and gpsd insert a line in /etc/init.d/httpd, last line in desktop section:

desktop() {
	config_foreach system_config system
	hostname="${hostname:-OpenWrt}"

	unset args
	config_load httpd
	[ "$?" != "0" ] && {
		uci_set_default httpd <<EOF
config 'httpd'
	option 'port' '80'
	option 'home' '/www'
EOF
		config_load httpd
	}
	config_foreach httpd_config httpd
	/usr/sbin/ser2net ; /usr/sbin/gpsd /dev/ttySAC1
	
}

Open /etc/ser2net.conf and replace all port examples at the very end with this single line:

2001:raw:0:/dev/ttySAC0:115200 NONE 1STOPBIT 8DATABITS -XONXOFF -LOCAL RTSCTS

Runtime Environment

Install the GUI package ex11

Take a look at this example of what you can do with ex11 [2] Take the file at http://projects.openmoko.org/frs/download.php/753/ex11_lib.tgz and unzip it in your source directory.

mkdir /root/trunk
cd /root/trunk
tar -xvf ex11_lib.tgz

In file /root/.profile

export DISPLAY=:0

In file /etc/hosts remove . (dot) at the end of line localhost.

127.0.0.1 localhost

In file /root/.erlang

io:format("Running Erlang from root~n").
code:add_patha("/root/trunk").

Copy Xauthority from host

scp .Xauthority phone:/root

Add localhost to it with xauth

xauth
add OpenWrt/unix:0 MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
exit
cp .Xauthority /


Include erlang VM in the boot process, simply add a line to /etc/init.d/x11 right after Xorg:

start() {
  export DISPLAY=":0"
  config_load x11
  Xorg $ARGS &
  erl -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /root/trunk -s main start > debug.txt
}

Development Environment

This section is about setting up and do some work on your development system. It can be a PC with Linux or Windows, or it can be a Mac.

IDE

  • Linux I am using SciTE for Erlang development on my Linux box. There are other alternatives but SciTE has some nice features not found in other packages.
  • Windows TBD
  • Mac TBD

Seting up SciTE for openmoko development

Before you start configuring SciTE, make sure ssh, scp and rsh works from a terminal window. Read USB_Networking to get it working. I have to run this script whenever I connect the neo to the host

#!/bin/bash
ifconfig usb0 192.168.0.200 netmask 255.255.255.0
/sbin/route add -host 192.168.0.202/32 dev usb0
echo 1 > /proc/sys/net/ipv4/ip_forward
iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
iptables -P FORWARD ACCEPT

Download from here http://www.scintilla.org/SciTE.html and install. If you have apt-get it can be as easy as

sudo apt-get install scite

Start SciTE and select menu Options|Open Global Options and uncomment

#Erlang|erl||\

and at other lines where erlang is a comment. You may have to start SciTE as root to do this. (To uncomment you just delete the hash at the beginning of the line).

Create a file named SciTE.properties in your erlang source directory.

# SciTE.properties is the per directory local options file and can be used to
# override settings made in SciTEGlobal.properties, SciTEUser.properties and
# SciTEDirectory.properties.
command.compile.*.erl=erlc $(FileName).erl
command.go.subsystem.*.erl=0
command.go.*.erl=erl -noshell -s $(FileName) start 
command.subsystem.1.*.erl=0
command.name.1.*.erl=svn update
command.1.*.erl= svn update $(FileNameExt)
command.name.2.*.erl= svn ci
command.2.*.erl= svn ci -m '$(4)' $(FileNameExt)
command.name.3.*.erl=svn co
command.3.*.erl=*svn co $(1)
command.name.4.*.erl=svn status
command.4.*.erl= svn status
command.name.5.*.erl=hot code loading
command.5.*.erl=erl -noshell -setcookie SFEWRG34AFDSGAFG35235 -name moko2@192.168.0.200 -eval "net_adm:ping('neo@192.168.0.202'), c:nl($(FileName))." -s init stop
command.subsystem.6.*.erl=0
command.name.6.*.erl=copy to Freerunner
command.6.*.erl= scp $(FileName).beam   phone:/root/trunk/
command.subsystem.7.*.erl=0
command.name.7.*.erl=add to subversion
command.7.*.erl= svn add $(FileNameExt)
abbreviations.*.erl=$(SciteUserHome)/erl_abbrev.properties
line.margin.visible=1
line.margin.width=2+
style.*.33

Arcitecture

Finally its starting to be interesting, how is the Aphasia system built? It's not very common to build systems in Erlang, and definitely rare to build GUI code in it.

Graphics

I'm using vector graphics to produce new widgets. Vector graphics is lightweight and programmable, easy to scale and rotate, and the bytesize is small. Use any vector-capable drawing application. I happen to use AutoCAD LT on Wine, but please suggest an open source alternative and I will be happy to create another small conversion program to translate the new drawing file to erlang source. If you have access to AutoCAD, take dxf2erl.erl from here

Drawing a widget in AutoCAD LT

Screencast here

Convert drawing to erlang source

Screencast here

Where are all the menus?

Aphasia is built for people with different communicative disabilities. Menus where ruled out from the Aphasia GUI from the very beginning due to the fact that you don't even have to have a disability to get lost in a miniature menu system.

Instead I'm using a positioning system where services (I'll talk about those later) are laid out on a large surface (surface of the earth actually) and you can reach a service by swiping the screen in different directions. Another much cooler way to reach a service is when you physically go to a certain place in "real life". How we accomplish this is covered in the GPS section.

The thing I call a service

A service is often described as a contract between a consumer and a producer. When you go to the barber you know you will get a shave (if you are a man). The service is the implicit contract between you and the barber that he will shave not rub. There are many barber shops down the street offering essentially the same service, so there can be many service producers for one service.

And in the Aphasia system, each service producer is a separate Erlang process. All services are running in parallell, just like in real life. The Erlang VM is quite different from other platforms in that respect, thousands or tens of thousands of processes running at the same time is not uncommon in a well designed system.

The GSM Service producer

Where should we start if not with the GSM service producer (I will use the name GSM process from now on), it's a phone for God's sake. What kind of service can we expect from the GSM process, can we expect to be able to be connected to, and able to communicate with, someone or something. The GSM process is always on, it's also invisible. Most processes can display themselves on the screen but the GSM process does not show up, it's running in the background listening to the different signals coming from the Calypso GSM chip.

[TBD]

Personal tools

Installation

This section is about setting up your Freerunner GTA02 for running the Aphasia distro.

OpenWrt

Aphasia sits on the OpenWrt platform. A very configurable Linux distribution, and light on system resources. There's a great forum at [1]

Go to OpenWrt, section Build custom image and follow the instructions. When you are at the point Configure target and packages you have to do some choises. Here is the minimum installation for Aphasia:

make menuconf

OpenWrt Kamikaze (r16871) Configuration

Target System (Samsung S3C24xx [2.6])  --->    Samsung S3C24xx [2.6]
Target Profile (Openmoko GTA-02 (minimal))  --->   Openmoko GTA-02 (minimal)

[*] Image configuration  ---> (192.168.0.202) LAN IP Address 

Xorg  --->    app  ---> <*> xauth
Xorg  ---> driver  ---> <*> xf86-input-tslib
Xorg  ---> driver  ---> <*> xf86-video-glamo
Xorg  --->   font  ---> <*> dejavu-fonts-ttf

Network  ---> <*> gpsd
Network  ---> <*> ser2net

Phone  ---> <*> freerunner-alsa-scenarios

Utilities  ---> <*> alsa-utils
Utilities  ---> <*> bash

Extra packages  --->  <*> zoneinfo-europe

Sound  --->   <*> lame
Sound  --->   <*> madplay

Languages  ---> <*> erlang

Configure gpsd and ser2net

To autostart ser2net and gpsd insert a line in /etc/init.d/httpd, last line in desktop section:

desktop() {
	config_foreach system_config system
	hostname="${hostname:-OpenWrt}"

	unset args
	config_load httpd
	[ "$?" != "0" ] && {
		uci_set_default httpd <<EOF
config 'httpd'
	option 'port' '80'
	option 'home' '/www'
EOF
		config_load httpd
	}
	config_foreach httpd_config httpd
	/usr/sbin/ser2net ; /usr/sbin/gpsd /dev/ttySAC1
	
}

Open /etc/ser2net.conf and replace all port examples at the very end with this single line:

2001:raw:0:/dev/ttySAC0:115200 NONE 1STOPBIT 8DATABITS -XONXOFF -LOCAL RTSCTS

Runtime Environment

Install the GUI package ex11

Take a look at this example of what you can do with ex11 [2] Take the file at http://projects.openmoko.org/frs/download.php/753/ex11_lib.tgz and unzip it in your source directory.

mkdir /root/trunk
cd /root/trunk
tar -xvf ex11_lib.tgz

In file /root/.profile

export DISPLAY=:0

In file /etc/hosts remove . (dot) at the end of line localhost.

127.0.0.1 localhost

In file /root/.erlang

io:format("Running Erlang from root~n").
code:add_patha("/root/trunk").

Copy Xauthority from host

scp .Xauthority phone:/root

Add localhost to it with xauth

xauth
add OpenWrt/unix:0 MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
exit
cp .Xauthority /


Include erlang VM in the boot process, simply add a line to /etc/init.d/x11 right after Xorg:

start() {
  export DISPLAY=":0"
  config_load x11
  Xorg $ARGS &
  erl -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /root/trunk -s main start > debug.txt
}

Development Environment

This section is about setting up and do some work on your development system. It can be a PC with Linux or Windows, or it can be a Mac.

IDE

  • Linux I am using SciTE for Erlang development on my Linux box. There are other alternatives but SciTE has some nice features not found in other packages.
  • Windows TBD
  • Mac TBD

Seting up SciTE for openmoko development

Before you start configuring SciTE, make sure ssh, scp and rsh works from a terminal window. Read USB_Networking to get it working. I have to run this script whenever I connect the neo to the host

#!/bin/bash
ifconfig usb0 192.168.0.200 netmask 255.255.255.0
/sbin/route add -host 192.168.0.202/32 dev usb0
echo 1 > /proc/sys/net/ipv4/ip_forward
iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
iptables -P FORWARD ACCEPT

Download from here http://www.scintilla.org/SciTE.html and install. If you have apt-get it can be as easy as

sudo apt-get install scite

Start SciTE and select menu Options|Open Global Options and uncomment

#Erlang|erl||\

and at other lines where erlang is a comment. You may have to start SciTE as root to do this. (To uncomment you just delete the hash at the beginning of the line).

Create a file named SciTE.properties in your erlang source directory.

# SciTE.properties is the per directory local options file and can be used to
# override settings made in SciTEGlobal.properties, SciTEUser.properties and
# SciTEDirectory.properties.
command.compile.*.erl=erlc $(FileName).erl
command.go.subsystem.*.erl=0
command.go.*.erl=erl -noshell -s $(FileName) start 
command.subsystem.1.*.erl=0
command.name.1.*.erl=svn update
command.1.*.erl= svn update $(FileNameExt)
command.name.2.*.erl= svn ci
command.2.*.erl= svn ci -m '$(4)' $(FileNameExt)
command.name.3.*.erl=svn co
command.3.*.erl=*svn co $(1)
command.name.4.*.erl=svn status
command.4.*.erl= svn status
command.name.5.*.erl=hot code loading
command.5.*.erl=erl -noshell -setcookie SFEWRG34AFDSGAFG35235 -name moko2@192.168.0.200 -eval "net_adm:ping('neo@192.168.0.202'), c:nl($(FileName))." -s init stop
command.subsystem.6.*.erl=0
command.name.6.*.erl=copy to Freerunner
command.6.*.erl= scp $(FileName).beam   phone:/root/trunk/
command.subsystem.7.*.erl=0
command.name.7.*.erl=add to subversion
command.7.*.erl= svn add $(FileNameExt)
abbreviations.*.erl=$(SciteUserHome)/erl_abbrev.properties
line.margin.visible=1
line.margin.width=2+
style.*.33

Arcitecture

Finally its starting to be interesting, how is the Aphasia system built? It's not very common to build systems in Erlang, and definitely rare to build GUI code in it.

Graphics

I'm using vector graphics to produce new widgets. Vector graphics is lightweight and programmable, easy to scale and rotate, and the bytesize is small. Use any vector-capable drawing application. I happen to use AutoCAD LT on Wine, but please suggest an open source alternative and I will be happy to create another small conversion program to translate the new drawing file to erlang source. If you have access to AutoCAD, take dxf2erl.erl from here

Drawing a widget in AutoCAD LT

Screencast here

Convert drawing to erlang source

Screencast here

Where are all the menus?

Aphasia is built for people with different communicative disabilities. Menus where ruled out from the Aphasia GUI from the very beginning due to the fact that you don't even have to have a disability to get lost in a miniature menu system.

Instead I'm using a positioning system where services (I'll talk about those later) are laid out on a large surface (surface of the earth actually) and you can reach a service by swiping the screen in different directions. Another much cooler way to reach a service is when you physically go to a certain place in "real life". How we accomplish this is covered in the GPS section.

The thing I call a service

A service is often described as a contract between a consumer and a producer. When you go to the barber you know you will get a shave (if you are a man). The service is the implicit contract between you and the barber that he will shave not rub. There are many barber shops down the street offering essentially the same service, so there can be many service producers for one service.

And in the Aphasia system, each service producer is a separate Erlang process. All services are running in parallell, just like in real life. The Erlang VM is quite different from other platforms in that respect, thousands or tens of thousands of processes running at the same time is not uncommon in a well designed system.

[TBD]