= Papywizard Developper Guide =

 * [#Introduction Introduction]
 * [#API API]
 * [#Architecture Architecture]
  * [#Hardware Hardware]
   * [#MerlinOrionprotocole Merlin/Orion protocole]
   * [#MerlinOrioncommandsset Merlin/Orion commands set]
  * [#Model Model]
   * [#Custompresets Custom presets]
  * [#View View]
 * [#Distributing Distributing]
  * [#Makedebianpackage Make Debian package]
  * [#Makemaemopackage Make Maemo package]
  * [#Makewindowsinstaller Make Windows installer]
 * [#Thefuture The future]

== Introduction ==

Papywizard is entirely written in python. It uses PyGTK (Python bindings for GTK) toolkit for the GUI, and a few additional modules, mainly for hardware control (pybluez and pyserial). Optionnaly, vpython (OpenGL-based module) can also be used to simulate the position of the head (note that this will be soon a separate application).

== API ==

The API documentation is available as web page in the {{{html/}}} directory.

== Architecture ==

Papywizard uses a MVC-like pattern, which keeps the model separated from the views. This allows to use any other toolkit if needed; I recently switched from Tkinter to PyGTK, to run Papywizard on Nokia plateform. I hope, one day, to be able to run Papywizard on QTopia-based devices, like Openmoko. But I first need to get such device ;o)

Low-levels routines which control the hardware are also in their own package; I plan to made them even more modular, to be used in an external project to control the head. For know, only Merlin/Orion head is supported, but it is very easy to implement other heads.

A word about the simulation (to come).

=== Hardware ===

==== Merlin/Orion protocole ====

The head uses a simple ascii serial protocol; the serial line uses standard settings: 9600 8N1 (9600 bauds, 8 bits data, no parity, 1 stop bit). The head waits for incoming commands, and send response to them. The 2 axis are identical, and uses the same commands. They both wait for incoming commands; depending of the first value (see below), the command will be sent to one or the other axis.

A commands always starts with ':', and ends with '\r'. The head response always starts with '=', and also ends with '\r'. As TX/RX lines are wired together, the controller has to first readback its own command, before reading the head response. In the following documentation, the command readback is omitted.

Parameters used in the documentation:
  * <axe>: 1=vertical, 2=horizontal (1 ascii digit)
  * <pos> position coded with 24 bits (6 ascii digits, hex). .

||'''Parameter'''||'''What'''||'''allowed value'''||'''Format'''||'''Note'''||
||''<axis>''||axis to control||1 or 2||1 ascii digit||1=yaw, 2=pitch axis||
||''<pos>''||position||0 to 2²⁴-1||6 ascii digits, hex.||low byte is sent first (A35483 is read 8354A3). When switched on, read value is 800000. Right sens increments axis 1; left sens decrements it. Up sens increments axis 2; down decrements it. A complete turn (360°) increments/decrements by 0E6600 (so, the axis can make almost 9 turns before the counter overflow)||

=== Merlin/Orion commands set ===

 * Read axis position:
{{{
 command        response
 :j<axe>        =<pos>
}}}

 * Read axis status:
{{{
 command        response
 :f<axe>        =<s1><s2><s3>
}}}

Init (at switch on):
{{{
 command        response
 :F1            =
 :F2            =
 :a1            =D3620E
 :D1            =F90600
 :a2            =D3620E
 :D2            =F90600
 :D2            =F90600
}}}

Press up button in fast mode:
{{{
 command        response
 :L2            =
 :G230          =
 :I2220000      =
 :J2            =
}}}

Release up button in fast mode:
{{{
 command       response
 :L2            =
 :f2            =503
}}}

Drive up to xxx position:
{{{
 todo
}}}

=== Model ===

=== View ===

== Distributing ==

=== Make Debian package ===

Papywizard includes an distutils extension script to build debian package in a easy way:

{{{
$ python debian/setup.py bdist_debian
}}}

The package is build in the {{{dist/}}} directory.

=== Make Maemo package ===

Same for debian package:

{{{
$ python maemo/setup.py bdist_debian
}}}

=== Make Windows installer ===

This is a little bit tricky (as always on this plateform!).

You first need to build the executable, by launching the windows setup script. The easier is to use [http://ipython.scipy.org Ipython]:

{{{
In [1]: run windows/setup.py py2exe
}}}

Then, run the script {{{windows/papywizard.nsi}}} (need to install NSIS software) to build the installer itself.

== The future ==