PyMaemo/Quick start guide

(Enabling USB networking)
m (notes about retirement of rootsh)
 
(41 intermediate revisions not shown)
Line 1: Line 1:
-
= Running Python code on N900 (quick start guide) =
+
= Getting Started: Setting Up Python Development Environment for N900 =
-
This article will describe the necessary steps to get your Python application running on N900. For the instructions to work, you need to have Internet connectivity on your device (e.g. WLAN or GPRS).
+
A basic development environment for Python development for Maemo consists of:
-
== Installing OpenSSH ==
+
* A source code editor
 +
* Some way to transfer application files to the tablet
 +
* Easily run the application (without installing it)
 +
 
 +
Alternatively, you can try other more complex development environments, briefly described at the end of this article.
 +
 
 +
This article will cover:
 +
 
 +
* Installation of necessary packages and USB connectivity setup
 +
* Some suggestions for Python code editors
 +
* How to transfer the application files to the N900
 +
* How to run the application
 +
 
 +
Application packaging and final deployment will be discussed separately at a later date.
 +
 
 +
Finally, there is a [http://www.youtube.com/watch?v=onAkb_7U5pk screencast] demonstrating the instructions from this guide, which should help clarifying some of the steps in a real setup session.
 +
 
 +
== Requirements ==
 +
 
 +
Before continuing, make sure you have:
 +
 
 +
Tablet requirements:
 +
 
 +
* Some kind of connectivity to the tablet (e.g. WLAN or GPRS), so that you can install required packages.
 +
* The N900 USB cable, which will be used to transfer files to the tablet.
 +
 
 +
Host requirements:
 +
 
 +
* An SSH client. For Linux, OpenSSH (through the "ssh" command) is enough. For Windows, [http://en.sourceforge.jp/projects/ttssh2/releases/ Tera Term] can be used. For Mac you can use "ssh" command in the Terminal.
 +
* An SCP/SFTP client. For Linux, OpenSSH (through the "scp" command) is enough. The KDE/GNOME environments also have built-in support for these protocols. For Windows, you can try [http://winscp.net/eng/index.php WinSCP] or [http://filezilla-project.org/ FileZilla].
 +
 
 +
For the purposes of this tutorial, you will '''not''' need Scratchbox installed. Scratchbox would only be necessary if you are unable to test your applications on the actual tablet.
 +
 
 +
== Installing required packages on N900 ==
 +
 
 +
You will need to install two applications on the tablet:
 +
 
 +
* [http://maemo.org/packages/view/openssh-server/ OpenSSH Server]
 +
* [http://maemo.org/packages/view/rootsh/ rootsh]
 +
 
 +
rootsh appears to have been replaced by either running <code>sudo gainroot</code> directly, or by running <code>root</code>.
OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.
OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.
-
If you are able to access the Internet from your N900 (e.g. using WLAN or GPRS) follow these instructions:
+
[[Root access]] is needed to allow to run commands as root on the X Terminal (using <code>sudo gainroot</code>).
-
# Enable extras repository. See http://wiki.maemo.org/Extras#Using_Extras for how to do it.
+
To install these applications, follow these steps:
-
# Install the package named "OpenSSH Client and Server". The client is also needed so we can enable USB networking in the next session, by ssh'ing to root@localhost. Optionally, you can install the rootsh package to enable local root access. See http://wiki.maemo.org/Root_access for details.
+
 
-
# The installation will ask for a new root password. Choose a good one.
+
# [[Extras#Using Extras|Enable the extras repository]].
 +
# Install the packages listed above.
 +
# The installation will ask for a new root password for SSH access. Choose a good one.
# Wait for installation to complete.
# Wait for installation to complete.
== Enabling USB networking ==
== Enabling USB networking ==
-
USB networking allows fast remote access to the device. To enable it, follow these steps (you need to repeat them every time you reboot the device:
+
USB networking allows to easily and quickly transfer files to the device and connect to it using SSH.
-
# If the USB cable is plugged and in "Mass storage mode", unpplug the cable and plug it again, now selecting "PC Suite Mode".
+
Note that this is not the only way to transfer files to the device. If you are already setup with your N900 and your desktop on the same LAN over Wifi, you can save yourself the trouble and skip this USB networking configuration section.
-
# On N900, open "X Terminal" and run:
+
-
ssh root@localhost ifup usb0
+
-
This command will ask for SSH fingerprint confirmation (because it is the first connection), and after typing the root password, USB networking will be enabled.
+
To enable USB networking, follow these steps (you need to repeat them every time you reboot the device):
-
Now configure the host. This is dependent on which OS (or Linux distro) you use, see http://wiki.maemo.org/USB_networking#Host_USB_Network_Configuration for detailed instructions for various OSes and Linux distros.
+
# If the USB cable is plugged and in "Mass storage mode", unplug the cable and plug it again, now selecting "PC Suite Mode".
 +
# On N900, open "X Terminal" and run:
 +
rootsh ifup usb0
 +
# Now you need to configure the host. This is dependent on which OS (or Linux distro) you use, but there are [[USB networking#Host USB Network Configuration|detailed instructions for various OSes and Linux distros]].
-
From now on you can connect to the N900 from your PC. In Linux, you can use:
+
From now on you can connect to the N900 using any SSH client and the following information:
 +
Host: 192.168.2.15
 +
Port: 22
 +
User: root
 +
Password: the password setup earlier
 +
 
 +
For instance, from a Linux terminal, you can connect to the tablet using this command:
  ssh root@192.168.2.15
  ssh root@192.168.2.15
-
 
-
For other OSes, please see the documentation associated to the SSH client being used.
 
== Preparing the N900 for Python Development ==
== Preparing the N900 for Python Development ==
-
To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. Note that this might be a risky operation because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.
+
To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. ''Be advised that this might be a risky operation'' because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.
-
 
+
-
To enable extras-devel add a new catalogue to the Application Manager, as instructed in https://wiki.maemo.org/Extras-devel (did you see the big warning on that page?)
+
-
 
+
-
Next, you need to install the packages you use (or plan to) on your application by running (through SSH):
+
-
apt-get update && apt-get install <packages>
+
Note that the requirement to enable the "extras-devel" repository might be removed later.
-
Where <packages> are the list of packages you are going to use. For instance, for a general GUI application, you will probably need at least "python-gtk2" and "python-hildon". See http://wiki.maemo.org/PyMaemo/Components for the current list of available packages.
+
To enable extras-devel add a new catalogue to the Application Manager, as instructed in [[Extras-devel]] (did you see the big warning on that page?)
-
== Running the Python application on the device (finally!) ==
+
After extras-devel is enabled, you will see on Application Manager a package called "maemo-python-device-env". Installing it will also install the basic environment necessary to run most Python applications on Maemo.
-
Now that you have the N900 properly setup, you just need to copy the Python code to the device and run it.
+
== Writing your code ==
-
=== Single file applications ===
+
Any good programmer oriented editor will be enough for development. If you have some development experience, you most probably already have chosen your favorite code editor and you can simply use it.
-
If your application consists of a single .py file, you can just copy it to the device using:
+
Here we list some options, both for Linux and Windows:
-
scp my_script.py root@192.168.2.15:/root
+
* [http://projects.gnome.org/gedit/ gedit]: the GNOME Editor has syntax highlight support for Python
 +
* [http://www.vim.org/ VIM] and [http://www.gnu.org/software/emacs/ Emacs]: the most popular editors, with many advanced features and versions for both Linux and Windows
 +
* [http://wiki.netbeans.org/Python NetBeans + Python plugin]: NetBeans is a multi-platform IDE, which with help of a plugin, supports development for Python
 +
* [http://maemo.org/downloads/product/Maemo5/pygtkeditor/ PyGTKEditor]: a syntax highlighting Python editor which runs natively on Maemo devices
-
And to run the application on N900:
+
Note that none of these editors will support code completion for PyMaemo modules out of box.
-
ssh root@192.168.2.15 run-standalone.sh python2.5 /root/my_script.py
+
For testing purposes, you can try the following code (the classic "hello world" example):
-
The application should then open on the device's screen, and any errors will be print on the terminal where you run the command below.
+
import gtk
 +
from gtk import Window, Button, Widget
 +
if __name__ == "__main__":
 +
    window = Window(gtk.WINDOW_TOPLEVEL)
 +
    window.connect("destroy", gtk.main_quit)
 +
    button = Button("Hello World")
 +
    button.connect_object("clicked", Widget.destroy, window)
 +
    window.add(button)
 +
    window.show_all()
 +
    gtk.main()
-
Alternatively, you can use this single command to run the code "on the fly" (i.e. without copying anything to the device):
+
Once you have your code written, you can proceed to copying application files to the device.
-
cat my_script.py | ssh root@192.168.2.15 run-standalone.sh python2.5
+
== Running the Python application on the device ==
-
===Multiple file applications ===
+
Now that you have the N900 properly setup and the code to run, you just need to copy the application files to the device and run it.
-
For applications which contain more than one file (e.g. images, or other Python files), you need to make all the necessary files accessible on the device. The simplest way is to copy all the code to some directory on the device, which you could do by using this single line:
+
The simplest way to copy files it to use a SFTP or SCP client. There are many free clients available for most OSes (we listed some examples on the "Requirements" section). On the Linux command line, you can use:
-
  tar -cf- my_application_dir/ | ssh root@192.168.2.15 tar -C /root -xvf-
+
  scp -pr my_application/ root@192.168.2.15:/root/my_application/
-
This command uses a combination of tar and ssh to copy all files under a directory recursively (taking care to keep permissions intact). Then, to run the application, use a command like this:
+
Replace "my_application/" with the path to the directory which contains your application files.
-
ssh root@192.168.2.15 run-standalone.sh python2.5 /root/my_application_dir/my_script.py
+
Finally, to run the application on the tablet, use (from a SSH terminal):
-
Alternatively, you can install the "sshfs" package on your PC (it is available at least on Debian and Ubuntu systems), and run:
+
cd /root/my_application
 +
python my_application.py
-
sshfs root@192.168.2.15:/root some_local_dir
+
== Alternative development environments ==
-
This will make the N900's /root directory accessible on some_local_dir directory on the PC. You can copy files to some_local_dir and they will be transparently copied to the device. To run the application, use the same command as shown earlier.
+
Besides the environment described on this article, there are two alternative development environments that might or might not be more appropriate for your purposes:
-
Once you don't need to access the directory anymore, run:
+
; PluThon (Eclipse based)
 +
: [http://pluthon.garage.maemo.org/ PluThon] is a full Python IDE for Maemo, based on Eclipse. While PluThon is easy to use and provides a complete solution, it is not necessary for basic Python development for Maemo. If you already use Eclipse for your development, PluThon might be your best option.
 +
; Official Maemo SDK (Scratchbox based)
 +
: [http://www.scratchbox.org/ Scratchbox] is a cross-compilation toolkit used for native Maemo development. Although it can be used in Python development as well (and comes very handy if you do not have access to a real device), it has a non-trivial learning curve and is not needed for pure Python development. However, if you plan to write new Python extensions (for instance, using [http://www.cython.org/ Cython] or [http://docs.python.org/c-api/index.html Python/C API] directly), Scratchbox is needed to cross-compile the C code. See the [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_SDK Maemo SDK section] on Maemo 5 developer guide for more details on it.
-
umount some_local_dir
+
Note that PluThon has built-in support for transferring and running code on the device. On the other hand, the Maemo SDK has no such support (unless you use some IDE like [http://esbox.garage.maemo.org/ ESbox]), so you need to follow steps similar to the ones described on this guide to copy and run your code on the tablet, if you choose to use the Maemo SDK.
-
sshfs can also be used the other way around: you can access your application's directory directly from the N900 (so no copying is needed at all). For that, install the "sshfs" package on N900 by running:
+
== Advanced tips ==
-
apt-get install sshfs
+
If you want to activate USB networking automatically upon connecting the device to the computer, just create a file called /etc/event.d/usbnet on the device with the following contents:
-
Make sure you have OpenSSH server installed on your PC, and run:
+
start on G_NOKIA_READY
 +
 +
console output
 +
exec ifconfig usb0 192.168.2.15 netmask 255.255.255.0 up
-
ssh root@192.168.2.15 # this will log into the N900
+
This way you just have to select "PC Suite mode" when plugging the device in.
-
mkdir /root/host_fs
+
-
sshfs <USER>@192.168.2.14:/path/to/my_application_dir /root/host_fs
+
-
run-standalone.sh python2.5 /root/host_fs/my_script.py
+
-
Once you don't need to access the directory anymore, run:
+
[[Category:N900]]
-
ssh root@192.168.2.15 umount /root/host_fs
+
[[Category:Python]]

Latest revision as of 21:04, 24 March 2011

Contents

[edit] Getting Started: Setting Up Python Development Environment for N900

A basic development environment for Python development for Maemo consists of:

  • A source code editor
  • Some way to transfer application files to the tablet
  • Easily run the application (without installing it)

Alternatively, you can try other more complex development environments, briefly described at the end of this article.

This article will cover:

  • Installation of necessary packages and USB connectivity setup
  • Some suggestions for Python code editors
  • How to transfer the application files to the N900
  • How to run the application

Application packaging and final deployment will be discussed separately at a later date.

Finally, there is a screencast demonstrating the instructions from this guide, which should help clarifying some of the steps in a real setup session.

[edit] Requirements

Before continuing, make sure you have:

Tablet requirements:

  • Some kind of connectivity to the tablet (e.g. WLAN or GPRS), so that you can install required packages.
  • The N900 USB cable, which will be used to transfer files to the tablet.

Host requirements:

  • An SSH client. For Linux, OpenSSH (through the "ssh" command) is enough. For Windows, Tera Term can be used. For Mac you can use "ssh" command in the Terminal.
  • An SCP/SFTP client. For Linux, OpenSSH (through the "scp" command) is enough. The KDE/GNOME environments also have built-in support for these protocols. For Windows, you can try WinSCP or FileZilla.

For the purposes of this tutorial, you will not need Scratchbox installed. Scratchbox would only be necessary if you are unable to test your applications on the actual tablet.

[edit] Installing required packages on N900

You will need to install two applications on the tablet:

rootsh appears to have been replaced by either running sudo gainroot directly, or by running root.

OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.

Root access is needed to allow to run commands as root on the X Terminal (using sudo gainroot).

To install these applications, follow these steps:

  1. Enable the extras repository.
  2. Install the packages listed above.
  3. The installation will ask for a new root password for SSH access. Choose a good one.
  4. Wait for installation to complete.

[edit] Enabling USB networking

USB networking allows to easily and quickly transfer files to the device and connect to it using SSH.

Note that this is not the only way to transfer files to the device. If you are already setup with your N900 and your desktop on the same LAN over Wifi, you can save yourself the trouble and skip this USB networking configuration section.

To enable USB networking, follow these steps (you need to repeat them every time you reboot the device):

  1. If the USB cable is plugged and in "Mass storage mode", unplug the cable and plug it again, now selecting "PC Suite Mode".
  2. On N900, open "X Terminal" and run:
rootsh ifup usb0
  1. Now you need to configure the host. This is dependent on which OS (or Linux distro) you use, but there are detailed instructions for various OSes and Linux distros.

From now on you can connect to the N900 using any SSH client and the following information:

Host: 192.168.2.15
Port: 22
User: root
Password: the password setup earlier

For instance, from a Linux terminal, you can connect to the tablet using this command:

ssh root@192.168.2.15

[edit] Preparing the N900 for Python Development

To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. Be advised that this might be a risky operation because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.

Note that the requirement to enable the "extras-devel" repository might be removed later.

To enable extras-devel add a new catalogue to the Application Manager, as instructed in Extras-devel (did you see the big warning on that page?)

After extras-devel is enabled, you will see on Application Manager a package called "maemo-python-device-env". Installing it will also install the basic environment necessary to run most Python applications on Maemo.

[edit] Writing your code

Any good programmer oriented editor will be enough for development. If you have some development experience, you most probably already have chosen your favorite code editor and you can simply use it.

Here we list some options, both for Linux and Windows:

  • gedit: the GNOME Editor has syntax highlight support for Python
  • VIM and Emacs: the most popular editors, with many advanced features and versions for both Linux and Windows
  • NetBeans + Python plugin: NetBeans is a multi-platform IDE, which with help of a plugin, supports development for Python
  • PyGTKEditor: a syntax highlighting Python editor which runs natively on Maemo devices

Note that none of these editors will support code completion for PyMaemo modules out of box.

For testing purposes, you can try the following code (the classic "hello world" example):

import gtk
from gtk import Window, Button, Widget
if __name__ == "__main__":
    window = Window(gtk.WINDOW_TOPLEVEL)
    window.connect("destroy", gtk.main_quit)
    button = Button("Hello World")
    button.connect_object("clicked", Widget.destroy, window)
    window.add(button)
    window.show_all()
    gtk.main()

Once you have your code written, you can proceed to copying application files to the device.

[edit] Running the Python application on the device

Now that you have the N900 properly setup and the code to run, you just need to copy the application files to the device and run it.

The simplest way to copy files it to use a SFTP or SCP client. There are many free clients available for most OSes (we listed some examples on the "Requirements" section). On the Linux command line, you can use:

scp -pr my_application/ root@192.168.2.15:/root/my_application/

Replace "my_application/" with the path to the directory which contains your application files.

Finally, to run the application on the tablet, use (from a SSH terminal):

cd /root/my_application
python my_application.py

[edit] Alternative development environments

Besides the environment described on this article, there are two alternative development environments that might or might not be more appropriate for your purposes:

PluThon (Eclipse based)
PluThon is a full Python IDE for Maemo, based on Eclipse. While PluThon is easy to use and provides a complete solution, it is not necessary for basic Python development for Maemo. If you already use Eclipse for your development, PluThon might be your best option.
Official Maemo SDK (Scratchbox based)
Scratchbox is a cross-compilation toolkit used for native Maemo development. Although it can be used in Python development as well (and comes very handy if you do not have access to a real device), it has a non-trivial learning curve and is not needed for pure Python development. However, if you plan to write new Python extensions (for instance, using Cython or Python/C API directly), Scratchbox is needed to cross-compile the C code. See the Maemo SDK section on Maemo 5 developer guide for more details on it.

Note that PluThon has built-in support for transferring and running code on the device. On the other hand, the Maemo SDK has no such support (unless you use some IDE like ESbox), so you need to follow steps similar to the ones described on this guide to copy and run your code on the tablet, if you choose to use the Maemo SDK.

[edit] Advanced tips

If you want to activate USB networking automatically upon connecting the device to the computer, just create a file called /etc/event.d/usbnet on the device with the following contents:

start on G_NOKIA_READY

console output
exec ifconfig usb0 192.168.2.15 netmask 255.255.255.0 up

This way you just have to select "PC Suite mode" when plugging the device in.