Erlang

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Quick and dirty)
(Example Code)
 
(38 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{note |This article is written while I am doing this stuff myself on my Linux Ubunty 8.1 system. If you are on another OS brand or version you will probably have to adjust some parts to make it work. To help understand what commands to type on a terminal on the phone and what to type on a terminal on the host, all phone-terminal text is in green. }}
 
 
 
 
== Introduction ==
 
== Introduction ==
 
[http://www.erlang.org Erlang] is a programming language which has many features more commonly associated with an operating system than with a programming language: concurrent processes, scheduling, memory management, distribution, networking, etc.
 
[http://www.erlang.org Erlang] is a programming language which has many features more commonly associated with an operating system than with a programming language: concurrent processes, scheduling, memory management, distribution, networking, etc.
Line 30: Line 27:
  
 
[[Image:Dialer.gif]]
 
[[Image:Dialer.gif]]
 +
 +
== Installation on OpenWrt ==
 +
 +
Follow the guidelines in the [[OpenWrt]] wiki page. Go to "Build Custom Image" and follow the instructions. In "Configure target and packages" scroll down to Languages and select Erlang.
  
 
== Installation on FSO distribution ==
 
== Installation on FSO distribution ==
  
The minimal erlang system is only 4 MB. It fits nicely into whats left in the Freerunner and neo1973 after openmoko-fso-image is installed. However, as I am building a vertical application on Openmoko I would prefere to use openmoko-fso-console-image as a baseline and add Xorg and erlang to make a clean environment. Until I have found out how to do that I run the fso-image-glibc and disable e-wm et al.
+
The minimal erlang system is only 4 MB. It fits nicely into whats left in the Freerunner and neo1973 after openmoko-fso-image is installed.  
  
=== Install erlang ===
 
 
Download cean_installer.bin from CEAN http://cean.process-one.net/downloads/ At the CEAN Downloads page, select "Installer" and "Production" and "Linux ARMEL" and Download.  Copy the file cean_installer.bin to your neo. To save keystrokes I have added "192.168.0.202 phone" to my /etc/hosts file.
 
Download cean_installer.bin from CEAN http://cean.process-one.net/downloads/ At the CEAN Downloads page, select "Installer" and "Production" and "Linux ARMEL" and Download.  Copy the file cean_installer.bin to your neo. To save keystrokes I have added "192.168.0.202 phone" to my /etc/hosts file.
  
 
<pre>
 
<pre>
scp cean_installer.bin  phone:/home/root
+
scp cean_installer.bin  root@phone:/home/root
 
</pre>
 
</pre>
  
Line 45: Line 45:
  
 
<pre>
 
<pre>
ssh phone
+
ssh root@phone
 
</pre>
 
</pre>
  
Line 58: Line 58:
 
Or if you get it from your host:
 
Or if you get it from your host:
 
<pre>
 
<pre>
scp ./somedir/libsctp.so.1.0.9 phone:/usr/lib/libsctp.so.1
+
scp ./somedir/libsctp.so.1.0.9 root@phone:/usr/lib/libsctp.so.1
 
</pre>
 
</pre>
  
Line 86: Line 86:
 
</pre>
 
</pre>
  
I use  ^C and then "a" to exit the shell.
+
I use  ^G and then "q" to exit the shell.
 
+
=== Install the GUI package ex11 ===
+
Take a look at this example of what you can do with ex11 [http://projects.openmoko.org/docman/view.php/59/22/MAQ01113.MP4]
+
Download from http://projects.openmoko.org/frs/?group_id=59 It is sufficient if you take the file at http://projects.openmoko.org/frs/download.php/753/ex11_lib.tgz and unzip it in your source directory.
+
 
+
In file /home/root/.profile
+
<font color="green">
+
<pre>
+
export DISPLAY=:0
+
</pre>
+
</font>
+
 
+
In file /home/root/.erlang
+
<font color="green">
+
<pre>
+
io:format("Running Erlang from root~n").
+
code:add_patha("/home/root/trunk").
+
</pre>
+
</font>
+
 
+
I keep my erlang source in /home/root/trunk
+
 
+
Copy Xauthority from host
+
 
+
<pre>
+
scp .Xauthority phone:/home/root
+
</pre>
+
 
+
When everything is installed you can try this "hello World" code to verify the platform. It will create an empty window.
+
<pre>
+
-module(test).
+
-export([start/0]).
+
-import(ex11_lib,[eMapWindow/1,xDo/2,xFlush/1,xColor/2,xCreateSimpleWindow/7]).
+
-include("ex11_lib.hrl").
+
-define (WT,480).
+
-define (HT,640).
+
 
+
start() -> spawn(fun win/0).
+
 
+
win() ->
+
{ok, Display} = ex11_lib:xStart("3.1"),
+
Win = xCreateSimpleWindow(Display,0,0,?WT,?HT,?XC_arrow,xColor(Display,?blue)),
+
xDo(Display, eMapWindow(Win)),
+
xFlush(Display),
+
loop().
+
 
+
loop() ->
+
receive
+
Any -> io:format("Unknown Event~p~n",[Any]), loop()
+
end.
+
</pre>
+
Put this code in a file named test.erl Start erlang console
+
 
+
<font color="green">
+
<pre>
+
./cean/start.sh
+
</pre>
+
</font>
+
 
+
and compile and run the file with
+
<font color="green">
+
<pre>
+
c(test).
+
test:start().
+
</pre>
+
</font>
+
 
+
Note that it is ok to create and compile the file on your host and copy the compiled file "test.beam" to the phone. If you want to compile on the phone you have to install the compiler. Try this in the erlang shell.
+
<font color="green">
+
<pre>
+
cean:install(compiler).
+
</pre>
+
</font>
+
 
+
I must admit that for some reason it doesn't work for me. I don't compile on the phone anyway so it's no big deal.
+
  
 
== Installation on SHR-testing distribution ==
 
== Installation on SHR-testing distribution ==
Line 170: Line 95:
  
 
Make sure you have an uboot that is [http://wiki.openmoko.org/wiki/Flashing_the_Neo_FreeRunner#Flashing_the_boot_loader_to_the_NAND compatible], I used Uboot u-boot-gta01bv4-1.2.0+svnnow-r13_0_2632_0.bin
 
Make sure you have an uboot that is [http://wiki.openmoko.org/wiki/Flashing_the_Neo_FreeRunner#Flashing_the_boot_loader_to_the_NAND compatible], I used Uboot u-boot-gta01bv4-1.2.0+svnnow-r13_0_2632_0.bin
 
Install Debian, install script is here http://wiki.openmoko.org/wiki/Debian
 
  
 
Follow the instructions. I had to type in the setenv string and then saveenv.
 
Follow the instructions. I had to type in the setenv string and then saveenv.
 
Reboot to get the new menu_4 title to show up.
 
Reboot to get the new menu_4 title to show up.
  
=== Install erlang ===
+
Install Debian, install script is here: [[Debian]]
 +
 
 
<font color="green">
 
<font color="green">
 
<pre>
 
<pre>
Line 183: Line 107:
 
</font>
 
</font>
  
=== Install the GUI package ex11 ===
+
== Erlang development environment ==
Take a look at this example of what you can do with ex11 [http://projects.openmoko.org/docman/view.php/59/22/MAQ01113.MP4]
+
You can in fact choose any text editor, and use a terminal window to compile and copy compiled erlang beam-files to the phone. However, I have found SciTE to be a nice choice. It has erlang colour coding, bracket matching, code completion and lots of more stuff you are accustomed to find in a programmers editor. And it's easily configurable to handle compilation and error tracking, click on an error message to go to the line where the error is located.
  
Download from http://projects.openmoko.org/frs/?group_id=59 It is sufficient if you take the file at http://projects.openmoko.org/frs/download.php/437/ex11lib.zip and unzip it in your source directory.
+
In addition to all this you can set it up to let you run your erlang app on the host, and to copy the compiled app to the phone and run it there. All from within SciTE. This gives a very fast turnaround time, I can compile my app - run on host - copy to neo - run on neo in less than a minute. Part of this fast development cycle is of course due to the fact that erlang is platform agnostic - the same compiled code runs on Arm and Intel Linux and Windows.
  
In home directory file .profile
+
Mac users have TextMate. Check out the bundle and install.
<font color="green">
+
 
<pre>
 
<pre>
export DISPLAY=:0
+
$ svn co http://svn.textmate.org/trunk/Bundles/Erlang.tmbundle
 
</pre>
 
</pre>
</font>
 
Remove "-nolisten tcp" from /etc/X11/xinit/xservrrc
 
 
Install xauth package and create .Xauthority file
 
<font color="green">
 
<pre>
 
debian-gta01:~# apt-get install xauth
 
debian-gta01:~# xauth
 
xauth:  creating new authority file /root/.Xauthority
 
Using authority file /root/.Xauthority
 
xauth> q
 
</pre>
 
</font>
 
Copy .Xauthority to /
 
 
 
When everything is installed you can try this "hello World" code to verify the platform. It will create an empty window.
 
<pre>
 
-module(test).
 
-export([start/0]).
 
-import(ex11_lib,[eMapWindow/1,xDo/2,xFlush/1,xColor/2,xCreateSimpleWindow/7]).
 
-include("ex11_lib.hrl").
 
-define (WT,480).
 
-define (HT,640).
 
 
start() -> spawn(fun win/0).
 
 
win() ->
 
{ok, Display} = ex11_lib:xStart("3.1"),
 
Win = xCreateSimpleWindow(Display,0,0,?WT,?HT,?XC_arrow,xColor(Display,?blue)),
 
xDo(Display, eMapWindow(Win)),
 
xFlush(Display),
 
loop().
 
 
loop() ->
 
receive
 
Any -> io:format("Unknown Event~p~n",[Any]), loop()
 
end.
 
</pre>
 
Put this code in a file named test.erl Compile the file with
 
<font color="green">
 
<pre>
 
erlc test.erl
 
</pre>
 
</font>
 
Run from erlang console.
 
<font color="green">
 
<pre>
 
erl
 
test:start().
 
</pre>
 
</font>
 
 
== Erlang development environment ==
 
You can in fact choose any text editor, and use a terminal window to compile and copy compiled erlang beam-files to the phone. However, I have found SciTE to be a nice choice. It has erlang colour coding, bracket matching, code completion and lots of more stuff you are accustomed to find in a programmers editor. And it's easily configurable to handle compilation and error tracking, click on an error message to go to the line where the error is located.
 
 
In addition to all this you can set it up to let you run your erlang app on the host, and to copy the compiled app to the phone and run it there. All from within SciTE. This gives a very fast turnaround time, I can compile my app - run on host - copy to neo - run on neo in less than a minute. Part of this fast development cycle is of course due to the fact that erlang is platform agnostic - the same compiled code runs on Arm and Intel Linux and Windows.
 
  
 
{{note |Other options for erlang developers are Eclipse and NetBeans. Add [http://erlide.sourceforge.net/ erlIDE] to Eclipse or use [http://sourceforge.net/projects/erlybird ErlyBird] }}
 
{{note |Other options for erlang developers are Eclipse and NetBeans. Add [http://erlide.sourceforge.net/ erlIDE] to Eclipse or use [http://sourceforge.net/projects/erlybird ErlyBird] }}
Line 256: Line 122:
 
=== You don't need an emulator ===
 
=== You don't need an emulator ===
 
All you need to run a phone application on your host is erlang and an X-server. Are you running linux it's just to install erlang and you are done. On a Mac you also have to install the Apple X-server app. It works right out of the box, and is a free download from www.apple.com. Textmate is the recommended erlang ide for mac-users. Windows users have to take another path. You develop and compile erlang source on your windows box, and use erlang's built in [[hot code loading]] to run your code right on the phone without any restart or reboot.
 
All you need to run a phone application on your host is erlang and an X-server. Are you running linux it's just to install erlang and you are done. On a Mac you also have to install the Apple X-server app. It works right out of the box, and is a free download from www.apple.com. Textmate is the recommended erlang ide for mac-users. Windows users have to take another path. You develop and compile erlang source on your windows box, and use erlang's built in [[hot code loading]] to run your code right on the phone without any restart or reboot.
 
=== Install SciTE ===
 
Download from here http://www.scintilla.org/SciTE.html and install. If you have apt-get it can be as easy as
 
<pre>
 
sudo apt-get install scite
 
</pre>
 
 
=== Seting up SciTE for openmoko development ===
 
Before you start configuring SciTE, make sure ssh, scp and rsh works from a terminal window.
 
I have to run this script whenever I connect the neo to the host
 
<pre>
 
#!/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
 
</pre>
 
 
Start SciTE and select menu Options|Open Global Options and uncomment
 
<pre>
 
#Erlang|erl||\
 
</pre>
 
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.
 
<pre>
 
# 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 neo1973
 
#command.6.*.erl= scp $(FileName).beam  phone:/root/erlang/trunk/ #Debian
 
command.6.*.erl= scp $(FileName).beam  phone:/home/root/trunk/
 
command.subsystem.7.*.erl=0
 
command.name.7.*.erl=add to subversion
 
command.7.*.erl= svn add $(FileNameExt)
 
command.subsystem.8.*.erl=0
 
command.name.8.*.erl=stop X
 
command.8.*.erl= rsh root@192.168.0.202 /etc/init.d/xserver-nodm stop
 
#command.8.*.erl= rsh root@192.168.0.202 /etc/init.d/zhone-session stop #Debian
 
command.subsystem.9.*.erl=0
 
command.name.9.*.erl=start
 
command.9.*.erl= rsh root@192.168.0.202 /etc/init.d/xserver-nodm start
 
#command.9.*.erl= rsh root@192.168.0.202 /etc/init.d/zhone-session start #Debian
 
abbreviations.*.erl=$(SciteUserHome)/erl_abbrev.properties
 
line.margin.visible=1
 
line.margin.width=2+
 
style.*.33
 
</pre>
 
 
==Runtime Environment==
 
I am developing a vertical market product based on Openmoko, so I want my erlang platform alone to run (no window manager nor Zhone) when the phone is switched on.
 
 
===Quick and dirty===
 
Remove packages Enlightenment and Illume.
 
<font color="green">
 
<pre>
 
opkg -recursive remove e-wm
 
</pre>
 
</font>
 
 
This is my  /etc/X11/Xsession.d/90xXWindowManager. I keep my erlang beam files at /home/root/trunk.
 
<font color="green">
 
<pre>
 
#!/bin/sh -e
 
/home/root/cean/start.sh -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /home/root/trunk -s main start > debug.txt
 
</pre>
 
</font>
 
 
 
For Debian users it's /usr/bin/zhone-session. I keep my erlang beam files at /root/erlang/trunk
 
<font color="green">
 
<pre>
 
#zhone &
 
#matchbox-keyboard-toggle &
 
erl -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /root/erlang/trunk -s main start > debug.txt
 
#exec matchbox-window-manager -use_titlebar no
 
</pre>
 
</font>
 
 
Replace "-s main start" with "-s your_module_name your_function_name"
 
 
 
All I have to do now is to re-start X whenever I want to run an uploaded app. This is what the last two menu buttons do in SciTe - stop X on the phone, and start X on the phone. As an alternative for stopping and starting X you can use Erlang's built-in [[hot code loading]].
 
 
 
[[Image:Scite.jpg]]
 
 
 
The svn xxx menu items is for version control if you are [[Using Subversion]].
 
 
Type
 
<pre>
 
ssh phone
 
</pre>
 
to get a terminal window and type
 
<font color="green">
 
<pre>
 
tail -f /debug.txt
 
</pre>
 
</font>
 
to read shell printout from the erlang process.
 
 
===The right way===
 
I would prefer to use openmoko-fso-console-image as a baseline and add Xorg, erlang and my applications to make a clean environment.
 
 
TBD
 
  
 
== Example Code ==
 
== Example Code ==
Line 393: Line 137:
 
</pre>
 
</pre>
  
== Graphics ==
+
There also is a Native DBus Implementation available for Erlang:
I'm using vector graphics to produce new widgets. Vector graphics is lightweight and programmable, easy to scale and rotate, and the Byte-Size 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 [http://projects.openmoko.org/frs/?group_id=59 here]
+
 
+
http://sourceforge.net/projects/dbus-erlang/
=== Drawing a widget in AutoCAD LT ===
+
  
Screencast [http://www.kvamme.se/Aphasia/Erlang_files/mokobattery.mov here]
+
===Use GTK in Erlang===
  
=== Convert drawing to erlang source ===
+
You can design GUIs with glade using erlang-gtknode.
  
Screencast [http://www.kvamme.se/Aphasia/Erlang_files/battery.mov here]
 
  
  
 
[[Category:Application Developer]]
 
[[Category:Application Developer]]

Latest revision as of 17:16, 13 May 2010

Contents

[edit] Introduction

Erlang is a programming language which has many features more commonly associated with an operating system than with a programming language: concurrent processes, scheduling, memory management, distribution, networking, etc.

[edit] Concurrency

- Erlang has extremely lightweight processes whose memory requirements can vary dynamically. Processes have no shared memory and communicate by asynchronous message passing. Erlang supports applications with very large numbers of concurrent processes. No requirements for concurrency are placed on the host operating system.

[edit] Distribution

- Erlang is designed to be run in a distributed environment. An Erlang virtual machine is called an Erlang node. A distributed Erlang system is a network of Erlang nodes (typically one per processor). An Erlang node can create parallel processes running on other nodes, which perhaps use other operating systems. Processes residing on different nodes communicate in exactly the same was as processes residing on the same node.

[edit] Robustness

- Erlang has various error detection primitives which can be used to structure fault-tolerant systems. For example, processes can monitor the status and activities of other processes, even if these processes are executing on other nodes. Processes in a distributed system can be configured to fail-over to other nodes in case of failures and automatically migrate back to recovered nodes.

[edit] Soft real-time

- Erlang supports programming "soft" real-time systems, which require response times in the order of milliseconds. Long garbage collection delays in such systems are unacceptable, so Erlang uses incremental garbage collection techniques.

[edit] Hot code loading

- Many systems cannot be stopped for software maintenance. Erlang allows program code to be changed in a running system. Old code can be phased out and replaced by new code. During the transition, both old code and new code can coexist. It is thus possible to install bug fixes and upgrades in a running system without disturbing its operation.

[edit] Incremental code loading

- Users can control in detail how code is loaded. In embedded systems, all code is usually loaded at boot time. In development systems, code is loaded when it is needed, even when the system is running. If testing uncovers bugs, only the buggy code need be replaced.

[edit] External interfaces

- Erlang processes communicate with the outside world using the same message passing mechanism as used between Erlang processes. This mechanism is used for communication with the host operating system and for interaction with programs written in other languages. If required for reasons of efficiency, a special version of this concept allows e.g. C programs to be directly linked into the Erlang runtime system.

[edit] Fast and Lean

- Erlang is fast and lean. A general erlang application has lots of processes. If you are used to OOP you can compare a process with an object. One process per object instance. To make sure the neo could cope with this I watched top while I was busy dialing a phone number on the Aphasia dialer. Each of the twelve buttons are a separate process. Each has its own little animation, and if you look carefully you can see they run in parallell and are acting independent of each other. The top statistics show a really low CPU utilization, I have to dial quite fast to exceed 5% CPU. Next test I made was to measure the time it takes to start these 12 processes and have them display themselves on the screen (aka start the dialer app). It takes approximately 0.5 sec!

Dialer.gif

[edit] Installation on OpenWrt

Follow the guidelines in the OpenWrt wiki page. Go to "Build Custom Image" and follow the instructions. In "Configure target and packages" scroll down to Languages and select Erlang.

[edit] Installation on FSO distribution

The minimal erlang system is only 4 MB. It fits nicely into whats left in the Freerunner and neo1973 after openmoko-fso-image is installed.

Download cean_installer.bin from CEAN http://cean.process-one.net/downloads/ At the CEAN Downloads page, select "Installer" and "Production" and "Linux ARMEL" and Download. Copy the file cean_installer.bin to your neo. To save keystrokes I have added "192.168.0.202 phone" to my /etc/hosts file.

scp cean_installer.bin  root@phone:/home/root

Open a terminal window to the phone. Password is blank. Unless you changed it to something you just have to press enter at the prompt.

ssh root@phone

Before you can install erlang you have to get a copy of the file libsctp.so.1. I grabbed one from my Debian installation on the cf card at /media/mmcblk0p2/usr/lib/

cp /media/mmcblk0p2/usr/lib/libsctp.so.1 /usr/lib

Or if you get it from your host:

scp ./somedir/libsctp.so.1.0.9 root@phone:/usr/lib/libsctp.so.1

Make sure you have "tar" installed on the phone:

opkg update
opkg install tar

Now you are ready to install erlang. On the phone, type

chmod 777 cean_installer.bin
./cean_installer.bin

If all goes well you will see the erlang console prompt

Erlang (BEAM) emulator version 5.6.3 [source] [async-threads:0] [kernel-poll:false]

Eshell V5.6.3  (abort with ^G)
1>

I use ^G and then "q" to exit the shell.

[edit] Installation on SHR-testing distribution

Get a version from CEAN, as described above, but get the "Archive", and not the "Installer". You will need the "libsctp" lib, too, but it's not in SHR anywhere. You can get a compatible .so out of the .deb package from this link [1]. Find the file libsctp.so.1.0.9, and save it to /usr/lib/ on your SHR freerunner. You should now be able to start the erlang shell.

[edit] Installation on Debian distribution

Make sure you have an uboot that is compatible, I used Uboot u-boot-gta01bv4-1.2.0+svnnow-r13_0_2632_0.bin

Follow the instructions. I had to type in the setenv string and then saveenv. Reboot to get the new menu_4 title to show up.

Install Debian, install script is here: Debian

apt-get install erlang-base

[edit] Erlang development environment

You can in fact choose any text editor, and use a terminal window to compile and copy compiled erlang beam-files to the phone. However, I have found SciTE to be a nice choice. It has erlang colour coding, bracket matching, code completion and lots of more stuff you are accustomed to find in a programmers editor. And it's easily configurable to handle compilation and error tracking, click on an error message to go to the line where the error is located.

In addition to all this you can set it up to let you run your erlang app on the host, and to copy the compiled app to the phone and run it there. All from within SciTE. This gives a very fast turnaround time, I can compile my app - run on host - copy to neo - run on neo in less than a minute. Part of this fast development cycle is of course due to the fact that erlang is platform agnostic - the same compiled code runs on Arm and Intel Linux and Windows.

Mac users have TextMate. Check out the bundle and install.

$ svn co http://svn.textmate.org/trunk/Bundles/Erlang.tmbundle
NOTE: Other options for erlang developers are Eclipse and NetBeans. Add erlIDE to Eclipse or use ErlyBird



[edit] You don't need an emulator

All you need to run a phone application on your host is erlang and an X-server. Are you running linux it's just to install erlang and you are done. On a Mac you also have to install the Apple X-server app. It works right out of the box, and is a free download from www.apple.com. Textmate is the recommended erlang ide for mac-users. Windows users have to take another path. You develop and compile erlang source on your windows box, and use erlang's built in hot code loading to run your code right on the phone without any restart or reboot.

[edit] Example Code

[edit] Use D-Bus in erlang

Dbus = open_port({spawn,"mdbus -s"}, [stream, use_stdio, binary]),
loop(Dbus).

And get the response

loop(Dbus) ->
receive
{Dbus,Msg} -> io:format("Dbus msg:~p~n",[Msg]),loop(Dbus)
end.

There also is a Native DBus Implementation available for Erlang:

http://sourceforge.net/projects/dbus-erlang/

[edit] Use GTK in Erlang

You can design GUIs with glade using erlang-gtknode.

Personal tools
NOTE: This article is written while I am doing this stuff myself on my Linux Ubunty 8.1 system. If you are on another OS brand or version you will probably have to adjust some parts to make it work. To help understand what commands to type on a terminal on the phone and what to type on a terminal on the host, all phone-terminal text is in green.



Introduction

Erlang is a programming language which has many features more commonly associated with an operating system than with a programming language: concurrent processes, scheduling, memory management, distribution, networking, etc.

Concurrency

- Erlang has extremely lightweight processes whose memory requirements can vary dynamically. Processes have no shared memory and communicate by asynchronous message passing. Erlang supports applications with very large numbers of concurrent processes. No requirements for concurrency are placed on the host operating system.

Distribution

- Erlang is designed to be run in a distributed environment. An Erlang virtual machine is called an Erlang node. A distributed Erlang system is a network of Erlang nodes (typically one per processor). An Erlang node can create parallel processes running on other nodes, which perhaps use other operating systems. Processes residing on different nodes communicate in exactly the same was as processes residing on the same node.

Robustness

- Erlang has various error detection primitives which can be used to structure fault-tolerant systems. For example, processes can monitor the status and activities of other processes, even if these processes are executing on other nodes. Processes in a distributed system can be configured to fail-over to other nodes in case of failures and automatically migrate back to recovered nodes.

Soft real-time

- Erlang supports programming "soft" real-time systems, which require response times in the order of milliseconds. Long garbage collection delays in such systems are unacceptable, so Erlang uses incremental garbage collection techniques.

Hot code loading

- Many systems cannot be stopped for software maintenance. Erlang allows program code to be changed in a running system. Old code can be phased out and replaced by new code. During the transition, both old code and new code can coexist. It is thus possible to install bug fixes and upgrades in a running system without disturbing its operation.

Incremental code loading

- Users can control in detail how code is loaded. In embedded systems, all code is usually loaded at boot time. In development systems, code is loaded when it is needed, even when the system is running. If testing uncovers bugs, only the buggy code need be replaced.

External interfaces

- Erlang processes communicate with the outside world using the same message passing mechanism as used between Erlang processes. This mechanism is used for communication with the host operating system and for interaction with programs written in other languages. If required for reasons of efficiency, a special version of this concept allows e.g. C programs to be directly linked into the Erlang runtime system.

Fast and Lean

- Erlang is fast and lean. A general erlang application has lots of processes. If you are used to OOP you can compare a process with an object. One process per object instance. To make sure the neo could cope with this I watched top while I was busy dialing a phone number on the Aphasia dialer. Each of the twelve buttons are a separate process. Each has its own little animation, and if you look carefully you can see they run in parallell and are acting independent of each other. The top statistics show a really low CPU utilization, I have to dial quite fast to exceed 5% CPU. Next test I made was to measure the time it takes to start these 12 processes and have them display themselves on the screen (aka start the dialer app). It takes approximately 0.5 sec!

Dialer.gif

Installation on FSO distribution

The minimal erlang system is only 4 MB. It fits nicely into whats left in the Freerunner and neo1973 after openmoko-fso-image is installed. However, as I am building a vertical application on Openmoko I would prefere to use openmoko-fso-console-image as a baseline and add Xorg and erlang to make a clean environment. Until I have found out how to do that I run the fso-image-glibc and disable e-wm et al.

Install erlang

Download cean_installer.bin from CEAN http://cean.process-one.net/downloads/ At the CEAN Downloads page, select "Installer" and "Production" and "Linux ARMEL" and Download. Copy the file cean_installer.bin to your neo. To save keystrokes I have added "192.168.0.202 phone" to my /etc/hosts file.

scp cean_installer.bin  phone:/home/root

Open a terminal window to the phone. Password is blank. Unless you changed it to something you just have to press enter at the prompt.

ssh phone

Before you can install erlang you have to get a copy of the file libsctp.so.1. I grabbed one from my Debian installation on the cf card at /media/mmcblk0p2/usr/lib/

cp /media/mmcblk0p2/usr/lib/libsctp.so.1 /usr/lib

Or if you get it from your host:

scp ./somedir/libsctp.so.1.0.9 phone:/usr/lib/libsctp.so.1

Make sure you have "tar" installed on the phone:

opkg update
opkg install tar

Now you are ready to install erlang. On the phone, type

chmod 777 cean_installer.bin
./cean_installer.bin

If all goes well you will see the erlang console prompt

Erlang (BEAM) emulator version 5.6.3 [source] [async-threads:0] [kernel-poll:false]

Eshell V5.6.3  (abort with ^G)
1>

I use ^C and then "a" to exit the shell.

Install the GUI package ex11

Take a look at this example of what you can do with ex11 [1] Download from http://projects.openmoko.org/frs/?group_id=59 It is sufficient if you take the file at http://projects.openmoko.org/frs/download.php/753/ex11_lib.tgz and unzip it in your source directory.

In file /home/root/.profile

export DISPLAY=:0

In file /home/root/.erlang

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

I keep my erlang source in /home/root/trunk

Copy Xauthority from host

scp .Xauthority phone:/home/root

When everything is installed you can try this "hello World" code to verify the platform. It will create an empty window.

-module(test).
-export([start/0]).
-import(ex11_lib,[eMapWindow/1,xDo/2,xFlush/1,xColor/2,xCreateSimpleWindow/7]).
-include("ex11_lib.hrl").
-define (WT,480).
-define (HT,640).

start() -> spawn(fun win/0).

win() ->
{ok, Display} = ex11_lib:xStart("3.1"),
Win = xCreateSimpleWindow(Display,0,0,?WT,?HT,?XC_arrow,xColor(Display,?blue)),
xDo(Display, eMapWindow(Win)),
xFlush(Display),
loop().

loop() ->
receive
Any -> io:format("Unknown Event~p~n",[Any]), loop()
end.

Put this code in a file named test.erl Start erlang console

./cean/start.sh

and compile and run the file with

c(test).
test:start().

Note that it is ok to create and compile the file on your host and copy the compiled file "test.beam" to the phone. If you want to compile on the phone you have to install the compiler. Try this in the erlang shell.

cean:install(compiler).

I must admit that for some reason it doesn't work for me. I don't compile on the phone anyway so it's no big deal.

Installation on SHR-testing distribution

Get a version from CEAN, as described above, but get the "Archive", and not the "Installer". You will need the "libsctp" lib, too, but it's not in SHR anywhere. You can get a compatible .so out of the .deb package from this link [2]. Find the file libsctp.so.1.0.9, and save it to /usr/lib/ on your SHR freerunner. You should now be able to start the erlang shell.

Installation on Debian distribution

Make sure you have an uboot that is compatible, I used Uboot u-boot-gta01bv4-1.2.0+svnnow-r13_0_2632_0.bin

Install Debian, install script is here http://wiki.openmoko.org/wiki/Debian

Follow the instructions. I had to type in the setenv string and then saveenv. Reboot to get the new menu_4 title to show up.

Install erlang

apt-get install erlang-base

Install the GUI package ex11

Take a look at this example of what you can do with ex11 [3]

Download from http://projects.openmoko.org/frs/?group_id=59 It is sufficient if you take the file at http://projects.openmoko.org/frs/download.php/437/ex11lib.zip and unzip it in your source directory.

In home directory file .profile

export DISPLAY=:0

Remove "-nolisten tcp" from /etc/X11/xinit/xservrrc

Install xauth package and create .Xauthority file

debian-gta01:~# apt-get install xauth
debian-gta01:~# xauth
xauth:  creating new authority file /root/.Xauthority
Using authority file /root/.Xauthority
xauth> q

Copy .Xauthority to /


When everything is installed you can try this "hello World" code to verify the platform. It will create an empty window.

-module(test).
-export([start/0]).
-import(ex11_lib,[eMapWindow/1,xDo/2,xFlush/1,xColor/2,xCreateSimpleWindow/7]).
-include("ex11_lib.hrl").
-define (WT,480).
-define (HT,640).

start() -> spawn(fun win/0).

win() ->
{ok, Display} = ex11_lib:xStart("3.1"),
Win = xCreateSimpleWindow(Display,0,0,?WT,?HT,?XC_arrow,xColor(Display,?blue)),
xDo(Display, eMapWindow(Win)),
xFlush(Display),
loop().

loop() ->
receive
Any -> io:format("Unknown Event~p~n",[Any]), loop()
end.

Put this code in a file named test.erl Compile the file with

erlc test.erl

Run from erlang console.

erl
test:start().

Erlang development environment

You can in fact choose any text editor, and use a terminal window to compile and copy compiled erlang beam-files to the phone. However, I have found SciTE to be a nice choice. It has erlang colour coding, bracket matching, code completion and lots of more stuff you are accustomed to find in a programmers editor. And it's easily configurable to handle compilation and error tracking, click on an error message to go to the line where the error is located.

In addition to all this you can set it up to let you run your erlang app on the host, and to copy the compiled app to the phone and run it there. All from within SciTE. This gives a very fast turnaround time, I can compile my app - run on host - copy to neo - run on neo in less than a minute. Part of this fast development cycle is of course due to the fact that erlang is platform agnostic - the same compiled code runs on Arm and Intel Linux and Windows.

NOTE: Other options for erlang developers are Eclipse and NetBeans. Add erlIDE to Eclipse or use ErlyBird



You don't need an emulator

All you need to run a phone application on your host is erlang and an X-server. Are you running linux it's just to install erlang and you are done. On a Mac you also have to install the Apple X-server app. It works right out of the box, and is a free download from www.apple.com. Textmate is the recommended erlang ide for mac-users. Windows users have to take another path. You develop and compile erlang source on your windows box, and use erlang's built in hot code loading to run your code right on the phone without any restart or reboot.

Install SciTE

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

Seting up SciTE for openmoko development

Before you start configuring SciTE, make sure ssh, scp and rsh works from a terminal window. 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

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 neo1973
#command.6.*.erl= scp $(FileName).beam   phone:/root/erlang/trunk/ #Debian
command.6.*.erl= scp $(FileName).beam   phone:/home/root/trunk/
command.subsystem.7.*.erl=0
command.name.7.*.erl=add to subversion
command.7.*.erl= svn add $(FileNameExt)
command.subsystem.8.*.erl=0
command.name.8.*.erl=stop X
command.8.*.erl= rsh root@192.168.0.202 /etc/init.d/xserver-nodm stop
#command.8.*.erl= rsh root@192.168.0.202 /etc/init.d/zhone-session stop #Debian
command.subsystem.9.*.erl=0
command.name.9.*.erl=start
command.9.*.erl= rsh root@192.168.0.202 /etc/init.d/xserver-nodm start
#command.9.*.erl= rsh root@192.168.0.202 /etc/init.d/zhone-session start #Debian
abbreviations.*.erl=$(SciteUserHome)/erl_abbrev.properties
line.margin.visible=1
line.margin.width=2+
style.*.33

Runtime Environment

I am developing a vertical market product based on Openmoko, so I want my erlang platform alone to run (no window manager nor Zhone) when the phone is switched on.

Quick and dirty

Remove packages Enlightenment and Illume.

opkg -recursive remove e-wm

This is my /etc/X11/Xsession.d/90xXWindowManager. I keep my erlang beam files at /home/root/trunk.

#!/bin/sh -e
/home/root/cean/start.sh -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /home/root/trunk -s main start > debug.txt


For Debian users it's /usr/bin/zhone-session. I keep my erlang beam files at /root/erlang/trunk

#zhone &
#matchbox-keyboard-toggle &
erl -setcookie SFEWRG34AFDSGAFG35235 -name neo@192.168.0.202 -noshell -pa /root/erlang/trunk -s main start > debug.txt
#exec matchbox-window-manager -use_titlebar no

Replace "-s main start" with "-s your_module_name your_function_name"


All I have to do now is to re-start X whenever I want to run an uploaded app. This is what the last two menu buttons do in SciTe - stop X on the phone, and start X on the phone. As an alternative for stopping and starting X you can use Erlang's built-in hot code loading.


Scite.jpg


The svn xxx menu items is for version control if you are Using Subversion.

Type

ssh phone

to get a terminal window and type

tail -f /debug.txt

to read shell printout from the erlang process.

The right way

I would prefer to use openmoko-fso-console-image as a baseline and add Xorg, erlang and my applications to make a clean environment.

TBD

Example Code

Use D-Bus in erlang

Dbus = open_port({spawn,"mdbus -s"}, [stream, use_stdio, binary]),
loop(Dbus).

And get the response

loop(Dbus) ->
receive
{Dbus,Msg} -> io:format("Dbus msg:~p~n",[Msg]),loop(Dbus)
end.

Graphics

I'm using vector graphics to produce new widgets. Vector graphics is lightweight and programmable, easy to scale and rotate, and the Byte-Size 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