= 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] * [#OutputXMLfile Output XML file] * [#Distributing Distributing] * [#Debianpackage Debian package] * [#Maemopackage Maemo package] * [#Windowsinstaller Windows installer] * [#Contribute Contribute] * [#Helpcoding Help coding] * [#Testandreportbugs Test and report bugs] * [#Internationalization Internationalization] * [#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 to control||1 or 2||1 ascii digit||1=yaw, 2=pitch axis|| ||''''||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)|| ||''''||axis direction||0 or 1||1 ascii digit||0=increments (up/right), 1=decrements (down/left)|| ||''''||Axis status||||3 ascii digits||Second digit is 0 when axis is stopped|| ||''''||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|||||| ||Read axis status||f|||||| ||Stop moving||L|||||| ||Init (at switch on)||F[[BR]]a[[BR]]D||[[BR]]0E62D3[[BR]]0006F9|||| ||Start moving||L[[BR]]G3[[BR]]I220000[[BR]]J||[[BR]][[BR]][[BR]]||220000 seems to be the divider for the speed. The lower the value, the higher the speed|| ||Drive to position||L[[BR]]G00[[BR]]S[[BR]]J|||||| ||Set shutter contact state||O||||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 === == Output XML file == Papywizard can generate a xml data file. This file mainly contains all positions used during shooting, and can be used by Autopano Giga to help positionning orphan pictures. This is very helpfull for high-resolution panos with deep blue sky, without details. Sift algorithmes can't find control points, there. The XML file is made of two parts: a header, qith global informations, and a shooting part, with all pictures and their position. The header exact format depends of the used mode (mosaic or preset). == Distributing == === Debian package === There is no debian packager yet. === 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.'' == Contribute == There are several ways to contribute: === Help coding === === Test and report bugs === === Internationalization === If you want to contribute but don't know how to code, you can make translation. To do that, you just need to download the latest [source:/trunk/locale/en/LC_MESSAGES/papywizard.po papywizard.po] file (using the '''Original Format''' link at the bottom of the page), which contains all sentences and words used in the soft, translate them using [http://www.poedit.net Poedit] (important; don't translate using a simple text editor), and send it back to me. == The future ==