<type>how-to</type>
<domain>install</domain>
<id>raspberry</id>
<title>Using Wing with Raspberry Pi</title>
<date>$Date: 2006-12-28 17:21:43 -0500 (Thu, 28 Dec 2006) $</date>
<product>per+</product>
<summary>Learn how Wing can be used to speed up development and debugging of Python 
code running on a Raspberry Pi.</summary>

.. note::
  **"Within a couple of minutes I could fence in and eliminate an error 
  with the handling of a GPRS modem attached to the Raspberry Pi that 
  before I was trying to hunt down for hours."** 
  *-- Robert Rottermann*, `redCOR AG <http://redcor.ch/>`__

.. image:: /images/screenshots/wing7-screenshot-dark.png
  :alt: Wing Pro Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code running on the `Raspberry Pi <http://raspberrypi.org/>`__. 

Two versions of Wing are appropriate for use with this document: Wing Pro is the
full-featured Python IDE for professional developers, and Wing Personal is a free
alternative with reduced feature set.

If you do not already have Wing installed, `download it now <https://wingware.com/downloads>`__.

This document describes how to configure Wing for Raspberry Pi. To get started using Wing
as your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Introduction
------------

Wing does not run on the Raspberry Pi, but you can set up Wing on a computer connected to
the Raspberry Pi to work on and debug Python code remotely.

If you have Wing Pro, then you can set up development on the Raspberry Pi very quickly
as described in the following section.

If you have Wing Personal, you will need to set up remote file sharing and debugging
manually, as described in **Manual Configuration for Wing Personal** below.

In either case you will first need a TCP/IP network connection between the machine where
Wing is running and the Raspberry Pi. The easiest way to connect the Raspberry Pi to
your network is with ethernet, or see the instructions at the end of this document for
configuring a wifi connection.

Remote Development with Wing Pro
--------------------------------

To use Wing Pro's remote development capabilities with the Raspberry Pi, take
the following steps:

* If you do not already have Wing installed, `download it now 
  <https://wingware.com/downloads>`__ on Windows, Linux, or OS X.
  
* Make sure you can connect to the Raspberry Pi from the machine where Wing
  IDE will be running, using ``ssh`` (or `PuTTY <http://www.putty.org/>`__ on 
  Windows) without entering a password.  You need to set up the SSH keys
  on each machine, and load them into your SSH user agent via ``ssh-add`` (or
  in ``Pageant`` on Windows).

* Start up Wing and use ``New Project`` from the ``Project`` menu to create
  a project.  Select project type ``Raspberry Pi``.  Fill in the fields as 
  follows:
  
  * **Identifier** -- Set this to ``rasp`` or some other string to identify
    the Raspberry Pi
  * **Host Name** -- Set this to the string you use to SSH into the Raspberry
    Pi.  In most cases you'll need both a username and IP address, such as
    ``pi@192.168.0.2``.
    
  Note that you can edit your configuration later, or add remote hosts to any 
  project, from the ``Remote Hosts`` item in the ``Project`` menu.
    
* Next click ``OK`` to create that remote host.  Wing will attempt to install 
  the remote agent and then establish a connection.  If this fails, details of
  the SSH command's output will be given in the resulting dialog.
  
* Once you have the remote agent working, go into ``Project Properties``
  and set ``Python Executable`` to ``Remote`` and choose the remote host
  definition you just created above.  Then click ``OK`` to save the 
  project configuration.  If you have not already done so, save the project
  to disk using a name ending in ``.wpr``, for example ``raspremote.wpr``.
  
* Next right click on the ``Project`` tool in Wing and select ``Add Existing
  Directory``.  In the resultin dialog, press ``Browse`` to choice directories
  on the Raspberry Pi.
  
Once this is done, you can open files from the Project tool, with ``Open
From Project`` and in other ways, and work with them as if they were on
your local machine.  That includes debugging, running unit tests, issuing
revision control commands, searching, running a Python Shell or OS Commands
remotely, and using other features like goto-definition, find uses, and 
refactoring.

Manual Configuration for Wing Personal
--------------------------------------

This section describes how to set up remote debugging on a Raspberry Pi manually,
for Wing Personal.  These instructions also work with Wing Pro but it
is much easier to use Wing Pro's remote development features (see instructions
above).

To do this, you will first need (1) a network connection between the Raspberry Pi and the
computer where Wing will be running, and (2) a way to share files from the machine
running Wing and the Raspberry Pi. For file sharing, use ``Samba``, or simply transfer
a copy of your files to the Raspberry Pi using ``scp`` or ``rsync``.

Installing and Configuring the Debugger
.......................................

Once you have a network connection and some sort of file sharing set up, the
next step is to install and configure Wing's debugger.  This is done
as follows:

* If you do not already have Wing installed, `download it now 
  <https://wingware.com/downloads>`__ on Windows, Linux, or OS X.
  
* Download the `Raspberry Pi debugger package 
  <https://wingware.com/pub/wingide/~~FULL_VERSION~~/wing-debugger-linux-arm32-~~FULL_VERSION~~.tar.bz2>`__
  to your Raspberry Pi and unpack it with 
  ``tar xzf wing-debugger-linux-arm32-~~FULL_VERSION~~.tar.bz2``.  This creates a
  directory named ``wing-debugger-linux-arm32-~~FULL_VERSION~~``.
  
* Launch Wing and make sure that ``Accept Debug Connections`` is checked 
  when you click on the bug icon in the lower left of Wing's main window.
  Hovering the mouse over the bug icon will show additional status information,
  including the port Wing is listening on, which should be ``50005`` by default.
  
* Copy ``wingdebugpw`` from the machine where you have Wing installed to the 
  Raspberry Pi and place it into the directory ``wing-debugger-linux-arm32-~~FULL_VERSION~~``.  
  This file is located in the ``Settings Directory``, which is listed 5th in Wing's ``About`` box.
  
* On the Raspberry Pi, use ``/sbin/ifconfig`` to determine the IP address
  of the Raspberry Pi (not 127.0.0.1, but instead the number listed under
  ``eth0`` or ``wlan0`` if you're using wifi).
  
* On the host where Wing is running (not the Raspberry Pi), establish an 
  ssh reverse tunnel to the Raspberry Pi so the debugger can connect back to the IDE.  
  On Linux and OS X this is done as follows::
  
    ssh -N -R 50005:localhost:50005 <user>@<rasp_ip>
    
  You'll need to replace ``<user>@<rasp_ip>`` with the login name on the Raspberry
  Pi and the ip address from the previous step.
  
  The ``-f`` option can be added just after ``ssh`` to cause ``ssh`` to run in the
  background.  Without this option, you can use ``Ctrl-C`` to terminate the tunnel.
  With it, you'll need to use ``ps`` and ``kill`` to manage the process.
  
  On Windows, use `PuTTY <http://www.putty.org/>`__ to configure an ssh tunnel using 
  the same settings on the ``Connections > SSH > Tunnels page``:  Set ``Source port`` 
  to ``50005``, ``Destination`` to ``localhost:50005``, and select the ``Remote`` 
  radio button, then press the ``Add`` button.  Once this is done the tunnel will 
  be established whenever PuTTY is connected to the Raspberry Pi.
  
* In Wing's `Preferences <script:show_preferences_gui#prefname="debug.location-map">`__, 
  use the ``Debugger > Advanced > Location Map`` preference
  to set up a mapping from the location of your files on the remote host
  (the Raspberry Pi) and the machine where the IDE is running.  
  
  For example, if you have files in ``/home/pi/`` on your Raspberry Pi that match those
  in ``/Users/pitest/src/`` on the machine where Wing is running, then you
  would add those two to the location mapping for ``127.0.0.1``, with ``home/pi/`` as
  the remote directory and ``/Users/pitest/src/`` as the local directory.   On Windows
  the IP address to use in the location map may instead be the IP address of the
  host where Wing is running.  This depends on the peer ip that is reported on the
  IDE side for sockets opened through the pipe.
  
  Don't add a location map for the Raspberry Pi's ip address because your ssh tunnel makes 
  it look like the connection is coming from the local host where the IDE is running.

Invoking the Debugger
.....................

There are two ways to invoke the debugger:  (1) from the command line, or (2) from
within your Python code.  The latter is useful if debugging code running under a
web server or other environment not launched from the command line.

**Debugging from the Command Line**

To invoke the debugger without modifying any code, use the following command::

  wing-debugger-linux-arm32-~~FULL_VERSION~~/wingdb yourfile.py arg1 arg2

This is the same thing as ``python yourfile.py arg1 arg2`` but runs your code in Wing's
debugger so you can stop at breakpoints and exceptions in the IDE, step through your code, 
and interact using the ``Debug Console`` in the ``Tools`` menu.

By default this runs with ``python`` and connects the debugger to ``localhost:50005``,
which matches the above configuration.  To change which Python is run, set the
environment variable ``WINGDB_PYTHON``::

  export WINGDB_PYTHON=/some/other/python
  
Use the `Tutorial <ref:intro/tutorial>`__ in Wing's ``Help`` menu to learn more 
about the features available in Wing.

**Starting Debug from Python Code**

To start debug from within Python code that is already running, edit 
``wing-debugger-linux-arm32-~~FULL_VERSION~~/wingdbstub.py`` and change the line 
``WINGHOME = None`` to ``WINGHOME = /home/pi/wing-debugger-linux-arm32-~~FULL_VERSION~~`` 
where ``/home/pi`` should be replaced with the full path where you unpacked the
debugger package earlier.  Use ``pwd`` to obtain the full path if you don't know what it is.
  
Copy your edited ``wingdbstub.py`` into the same directory as your code and add ``import
wingdbstub`` to your code. This new line is what initiates debugging and connects back to
the IDE through the ssh tunnel.

An alternative to editing ``wingdbstub.py`` is to set ``WINGHOME`` in the environment
instead with a command like ``export WINGHOME=/home/pi/wing-debugger-linux-arm32-~~FULL_VERSION~~``.

Configuration Details
.....................

If for some reason you can't use port ``50005`` as the debug port on either machine,
this can be changed on the Raspberry Pi with ``kHostPort`` in ``wingdbstub.py`` or 
with the ``WINGDB_HOSTPORT`` environment variable.  To change the port the IDE is
listening on, use the ``Debugger > Listening > Server Port`` preference and or
``Debug Server Port`` in Project Properties in Wing.

If this is done, you will need to replace the port numbers in the ssh tunnel invocation 
in the following form::

  ssh -N -R <remote_port>:localhost:<ide_port> <user>@<rasp_ip>

The first port number is the port specified in ``kHostPort`` or with ``WINGDB_HOSTPORT``
environment variable, and the second one is the port set in Wing's preferences or 
Project Properties. 

On Windows using PuTTY, the ``Source port`` is the port set with ``kHostPort`` or
``WINGDB_HOSTPORT`` on the Raspberry Pi, and the port in the ``Destination`` is
the port Wing is configured to listen on.

Refer to the documentation for ``ssh`` or ``PuTTY`` for details.

Trouble-Shooting
................

There are several ways in which a debug configuration can fail and when a connection
cannot be established to the IDE code will run without debug.  Additional diagnostic
output is needed to find the cause of most problems.  This is done by setting an
extra environment variable before initiating debug on the Raspberry Pi::

  export WINGDB_LOGFILE=/home/pi/debug.log
  
Hovering the mouse over the bug icon in the lower left of Wing's window will show if
a debug connection is active.  Wing also adds icons to the toolbar while debugging.

If Wing is not receiving a connection, check the reverse ssh tunnel, make sure that
``wingdebugpw`` was copied, and check that Wing is listening for debug connections.

If Wing is receiving a connection but breakpoints are not reached or source code is not
shown when reaching an exception, check your location map preference.  A good way to
test this is to add a deliberate unhandled exception to your code (such as ``assert 0``)
to see if Wing's debugger stops but fails to show the source code.  The location map
must be correct for Wing to show the source code.

Setting up Wifi on a Raspberry Pi
---------------------------------

It is possible to easily and cheaply connect a Raspberry Pi 2 to a wifi network.
Here are instructions for doing this using an Edimax EW-7811Un wifi USB card
(although other cards may also work) for a passphrase-protected wifi network:

* Plug in the USB wifi card and reboot your Raspberry Pi

* Edit /etc/network/interfaces and comment out the interface for wlan1.  
  Nothing works if this is not done.
  
* Edit /etc/wpa_supplicant/wpa_supplicant.conf and add the following to the end::

    network={
    ssid="<yourssid>"
    scan_ssid=1
    key_mgmt=WPA-PSK
    psk="<yourpassphrase>"
    }

  Replace ``<yourssid>`` your wifi network name and ``<yourpassphrase>`` with your 
  wifi passphrase.  Be sure to use exactly the above with no changes in spacing and with 
  the quotes for the ssid and passphrase but not for other things.  Otherwise nothing 
  works and you won't get any usable error messages.

* Restart your Raspberry Pi again and wifi should work.

Related Documents
-----------------

For more information see:

* `Raspberry Pi home page <http://raspberrypi.org/>`__ for documentation and downloads.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.
