= Papywizard Developper Guide =

 * [#Introduction Introduction]
 * [#API API]
 * [#Architecture Architecture]
  * [#Hardware Hardware]
   * [#MerlinOrionprotocole Merlin/Orion protocole]
   * [#MerlinOrioncommandsset Merlin/Orion commands set]
   * [#MerlinOrioncommunicationexamples Merlin/Orion communication examples]
  * [#Model Model]
  * [#View View]
 * [#Distributing Distributing]
  * [#Debianpackage Debian package]
  * [#Maemopackage Maemo package]
  * [#Windowsinstaller 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, as the ':', '=' and '\r' chars.

Parameters used in the documentation:

||'''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)||
||''<dir>''||axis direction||0 or 1||1 ascii digit||0=increments (up/right), 1=decrements (down/left)||
||''<status>''||Axis status||||3 ascii digits||Second digit is 0 when axis is stopped||
||''<state>''||State of the shutter contact||1 ascii digit||0 or 1||0 opens the contact, 1 closes the contact||

=== Merlin/Orion commands set ===

||'''Function'''||'''Command'''||'''Response'''||'''Note'''||
||Read axis position||j<axis>||<pos>||||
||Read axis status||f<axis>||<status>||||
||Stop moving||L<axis>||||||
||Init (at switch on)||F<axis>[[BR]]a<axis>[[BR]]D<axis>||[[BR]]0E62D3[[BR]]0006F9||||
||Start moving||L<axis>[[BR]]G<axis>3<dir>[[BR]]I<axis>220000[[BR]]J<axis>||[[BR]][[BR]][[BR]]||220000 seems to be the divider for the speed. The lower the value, the higher the speed||
||Drive to position||L<axis>[[BR]]G<axis>00[[BR]]S<axis><pos>[[BR]]J<axis>||||||
||Set shutter contact state||O<axis><state>||||Both axis understand the command, but the contact is only set by yaw (0) axis||

=== Merlin/Orion communication examples ===

When switched on:
{{{
command       response
:F1\r         =\r
:F2\r         =\r
:a1\r         =D3620E\r
:D1\r         =F90600\r
:a2\r         =D3620E\r
:D2\r         =F90600\r
:D2\r         =F90600\r
}}}

''Note: the last command is sent twice by the original remote control, but all works fine if sent only once (like Papywizard does).''

Push up button in fast mode:
{{{
command       response
:L2\r         =\r
:G230\r       =\r
:I2220000\r   =\r
:J2\r         =\r
}}}

Release up button if fast mode:
{{{
command       response
:L2\r         =\r
:f2\r         =503\r
}}}

=== Model ===

=== View ===

== Distributing ==

=== Debian package ===

''TODO''

=== Maemo package ===

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

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

=== Windows installer ===

This is a little bit tricky (as always on this plateform!). You first need to install all developpement tools and libraries:

 * ''TODO''

Then, build the executable, by launching the windows setup script. The easiest is to use [http://ipython.scipy.org Ipython]:

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

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

''Note: the bluetooth doesn't work on Windows I don't know why, as I'm not really familiar with this plateform.''

== The future ==