===========================
Aqua Computer @ MyMiniCity_
===========================

.. |date| date:: %Y-%m-%d %H:%M

:Copyright: 2008 Tom (documentation) and Y0Gi (revision, reST_ conversion,
            English translation)
:Date: |date|
:Version: 5.01


.. attention: This is work in progress and currently incomplete!


.. sectnum::

.. contents::


.. |...| unicode:: U+2026
.. |rarrow| unicode:: U+8594


Preface
=======

This package and the contained software and documentation are solely intented
for use by members of the `Aqua Computer Support Forum`_.

.. important:: Please *do not* hand this on to anybody else.

Thanks to Y0Gi, Clark, Shoggy, Cronix and all the others who made this program
possible with their help and ideas.

Thanks as well to all (beta) testers and bug reporters who had and still have
much patience with this rapidly hacked-together piece of software:
@re@50, Alex, Anisachse, b0nez, dasc1mt, DrStrange, Eikman, FUNKMAN, gr3if,
HansWursT, hurra, JoFreak, KillerX, Kinyar, kite, LeifTech, Lev, maed,
Max_Payne, MISZOU, newold, NikoMo, Nini2000, nordy, saUerkraut, scott,
sebastian, Sonni, Stefan_K., Tahigwa, TemplarOfSteel, Vitektim, welteken, |...|

Anybody running a working and stable 4.x release should stick to that -
*"never touch a running system!"*

This version is primarily targeted to users without Python_ and are unable or
unwilling to install it. Furthermore, the integrated router control has been
completely rebuilt and considerable extended to avoid the need for additional
software (like RouterControl_).

There are two versions now:

*Python version*:
    This only works with an installed Python interpreter, which has become an
    inherent part of many operating system releases. Current Python releases
    are available at `<http://www.python.org/download/releases/>`_.

    Invoke as: ``ACmcMain.py <arguments>``

    With some Python installations, the interpreter has to be specified
    explicitly: ``python.exe ACmcMain.py <arguments>``

*Win32 version*:
    This should work with any 32-bit Windows since 2000. This version is
    capable of running instantly and has no need for an installation.

    Invoke as: ``ACmcMain.exe <arguments>``


Installation/Extraction
=======================

To avoid trouble, the archive should be extracted to a path with a preferably
short name and without spaces, e. g. to ``D:\``. This should then result in
something similar to ``D:\ACmcBatch500\...``.

The folder ``My Documents`` is no good idea because the paths (depending on
the Windows version and network neighborhood) can grow too long. Furthermore,
the folder is ``Program Files`` is a very bad idea because the application
might then be required to be run with administrative privileges.

If you have RouterControl_ installed from a previous version and it works
flawlessly, you should stick to it. There is a special router model RoCon_
which fully integrates the program.


Execution
=========

.. attention:: This is no application with a GUI (graphical user interface) -
   double-clicking it won't cut it.

To quickly open a shell (aka DOS box) with the correct working path, there is
CmdHere_ from the `XP PowerToys`_. With it, one can right-click a folder in
the Windows Explorer and an appropriate item is available through the context
menu.

**New:** Arguments can be passed on two ways:

- Arguments are written to a simple configuration file, ``ACmcConf.txt``. It
  needs to be on the same path as ``ACmcMain.py`` or ``ACmcMain.exe``
  respectively. The format is super-easy: plain text and exactly one argument
  per line.

- Arguments are passed on the command line. For that purpose, take a look at
  (don't execute) the example file ``Start.bat``. On Windows: ``Explorer
  |rarrow| right click |rarrow| edit``. The batch script ``HitCity.bat``
  performs exactly one hit and exits. You can create a shortcut to it and put
  it into your "Startup" folder.

- These two methods can be combined, too, whereas command line arguments take
  precedence. That means if no arguments are given on the command line, those
  in the configuration file are used. E. g., if the first argument (delay) is
  set to 10 seconds in the configuration file and the program is executed as
  ``ACmcMain.exe 20 ...``, then a value of 20 seconds will be used.

When calling the application (``ACmcMain.py`` or ``ACmcMain.exe``
respectively) without arguments, a small help text and a list of supported
routers is displayed.

**New:** The application waits for the user to press ``<enter>``. This keeps
the window with its output open after double-clicking the application binary
on Windows.

If it doesn't work, start the application in a shell instead of
double-clicking it or using a Windows shortcut. Only this way all error
messages and cases can be seen.

.. image:: includes/dosshell.png
   :height: 950
   :width: 1000


Arguments in Detail
===================

.. note:: Arguments between angle brackets are required (e. g. ``<foo>``)
   while arguments in square brackets are optional (e. g. ``[bar]``). If
   there's a pipe symbol (``|``) inside one of those pairs of braces,
   multiple choices are available (e. g. ``[red|green]``).


Short Version
-------------

``ACmcMain.exe <delay> <work file> <operation hours> <router type>
[router arguments]``

- argument 1: delay (1 .. 200 seconds | ``0`` = auto timer | ``T`` = test the
  router control)
- argument 2: work file (``0`` = no work file | ``1`` = default |
  ``drive:path\name``)
- argument 3: operation hours (``A`` = 24h | 24* R|W|E, ``R`` = run,
  ``W`` = wait, ``E`` = exit)
- argument 4: router type (``None`` | ``Batch`` | ``X`` | ``UPnP`` | ``UPnPa``
  | ``Get`` | ``Post`` | ``<model>`` according to the list of routers
- argument 5 and following: depends on router type (argument 4)

  - ``None`` (no additional arguments)
  - ``Batch`` (no additional arguments)
  - ``Fritz`` (no additional arguments) - for use with an AVM FritzBox via
    UPnP
  - ``X <application invokation with arguments>`` - external application
    (RouterControl_, cURL_, DisConnect_ etc.) and arguments
  - ``UPnPa <address>``
  - ``UPnP <address> <port>``
  - ``Get <address> <username> <password> <doc path>``
  - ``Post <address> <username> <password> <doc path> <data>`` (=/&-encoded)
  - ``model <address> [username] [password]``

In my case, it looks like this:

.. image:: includes/starting.png
   :height: 480
   :width: 696


Long Version
------------

- argument 1: delay

  - integer = fixed-length time span in the range of 1 to 200 seconds
  - ``0`` = (zero) auto timer (usually works with most providers, but not
    always)
  - ``T`` = test the router control (do a reconnect and exit)

- argument 2: work file

  - ``0`` = (zero) no work file - no disk access, but the application can't
    remember anything
  - ``1`` = (one) default setting
  - filename with path (optional) and drive (optional) -
    ``[[drive:]path\]name``

- argument 3: operation hours

  - ``A`` = 24 hours continuous operation
  - a string with one character for each hour (i.e. 24 characters resemble a
    a full day)

    - ``R`` = run - program runs
    - ``W`` = wait - program waits
    - ``E`` = exit - program will exit - therefor, a string like
      ``...WWEER...`` doesn't make that much sense ;-)

- argument 4: router name/type and optional arguments (argument 5 and
  following)

  ``None`` (no additional arguments)
      no router control - the line is disconnected by the router itself
      according to its idle time setting

  ``Fritz`` (no additional arguments)
      use with an AVM FritzBox

  ``UPnP <name|address> <port>``
      use with UPnP_ routers

      .. attention:: UPnP_ has to be permitted via the router setup.

      .. note:: There's a special router type ``Fritz`` for use with
         FritzBoxes.

  ``UPnPa <name|address>``
      use with old UPnP_ routers (e. g. Eumex 300 IP)

  ``model <address> <username> <password>``
      router model (according to the list), the router's IP address, username
      and password

      Pass the router model name *exactly* (use copy & paste) or the
      application won't recognize it. If your router makes trouble, experiment
      with similar models. Some routers dislike the fast series of commands -
      in that case, try out the "disconnect only" version.

      .. tip:: If your router model is not included in the list, send me a
         `private message`_ via the forums.

  .. _RoCon:

  ``RoCon`` (no additional arguments)
      Make use of a readily installed and working version of RouterControl_.
      It will be found automatically if it's installed to the default path (as
      suggested by its installer).

      The current version can be found at:
      `<http://www.routercontrol.de/rc.zip>`_
                    
  ``Batch`` (no additional arguments)
      control in a batch loop with an additional program

      functionality with RouterControl_, cURL_ etc. as in version 4.xx

      .. attention:: Some errorlevels changed in 4.xx updates.

  ``Get <address> <username> <password> <doc path>``
      HTTP GET (see `Special Stuff`_)

  ``Post <address> <username> <password> <doc path> <data>`` (=/&-encoded)
      HTTP POST (see `Special Stuff`_)

  .. _X:

  ``X <invocation of an external application>``
      Invocation of an external application (RouterControl_, DisConnect_ etc.)
      ass subprocess (partially untested)

      See the batch scripts ``MakeRC.bat`` for calling RouterControl_ and
      ``ACmcCURL.bat`` for calling cURL_.


Program Invocation
==================


Configuration File (``ACmcConf.txt``)
-------------------------------------

For creation of the file, please don't use a "monster" like MS Office Word or
something similar. Those applications nearly can do everything - except for
important things like producing a simple text file or brewing coffee.

For Windows users, the provided text editor (``notepad.exe``) is most
suitable.

The format of arguments is identical to passing them on the command line -
with one exception: The arguments have to be written below each other instead
of next to each other, i. e. there has to be exactly one argument per line.

``0``
    0 seconds = auto timer

``1``
    1 data storage = default file

``RRRRRRWWWWWWWWWWWWWWWWWR``
    23:00 till 5:59 = Run, 6:00 till 22:59 = Wait

``Linksys_WRT_54G(7.00.1)``
    router model = Linksys WRT 54G (FirmWare 7.00.1)

``192.168.1.1``
    router address = 192.168.1.1

``admin``
    username = admin

``secret``
    password = secret

.. note:: Take a look at the example file ``ACmcConf-Beispiel.txt`` which you
   can adjust and rename to ``ACmcConf.txt``.


Windows Shortcut (with Argument Passing)
----------------------------------------

Create a shortcut for ``ACmcMain.exe`` and adapt it.

For an AVM FritzBox, it might look like this:

.. image:: includes/winlink.png
   :height: 434
   :width: 376

Keyboard cowboys can type those arguments by hand everytime, of course ;-)


Shell Script (aka Windows Batch)
--------------------------------

Fiddling around with batch scripts as it was common in the previous release is
no longer necessary and reserved for special cases.

For general invocation of the 5.x release in a batch script, see the example
files ``Start.bat`` and ``ACmcCurl.bat``.

``MakeRC.bat`` creates - just like in the previous release - a batch script
for use with ``RouterControl.exe``. However, this is needless as
RouterControl_ apparently works very well with the ``X`` argument (see X_).


Screen Output
=============

.. image:: includes/running.png
   :height: 411
   :width: 695


Special Stuff
=============

.. note:: For pros.

- Basically, every program can be invoked using the ``X`` argument.

  A very suitable tool is cURL_, which is available for many platforms. The
  current version is available for download at
  `<http://curl.haxx.se/download.html>`_.

  Connect/disconnect commands for various router models are listed at
  `<http://reconnect.thau-ex.de/>`_.

- Disconnect commands can also be issued directly with the ``Get`` and
  ``Post`` arguments.

  - cURL commands (as seen in the list referenced above) just need to be freed
    from batch and cURL overhead. Only the HTTP_ methods GET and POST (cURL
    argument ``-d``) via HTTP port 80 as well as standard authentification are
    supported. For all other methods, ports, and authentication schemes (e. g.
    using a cookie_), cURL has to be invoked as program.

  - The following placeholders can be used inside the strings:

    ``@IP@``
        the router's IP aadress
    ``@US@``
        username
    ``@PW@``
        password

- to be continued |...|


Changelog
=========

.. list-table::
   :header-rows: 1
   :widths: 17 6 77

   * - date
     - version
     - note

   * - 2008/07/03 16:30
     - **5.00**
     - initial release

   * - 2008/07/03 20:30
     - 5.00 -a
     - too fast for Netgear DG834B |rarrow| added delay to the router control
       (tnx 2 maed)

   * - 2008/07/03 23:50
     - 5.00 -b
     - add-on: all reconnect (= disconnect + connect) routers with ~_1 can be
       treated as "disconnect-only"

   * - 2008/07/04 09:55
     - 5.00 -c
     - bugfix: ``import subprocess`` forgotten/deleted/overlooked/misplaced
       (tnx 2 Nini2000 aka Chris)

   * - 2008/07/06 20:20
     - 5.00 -d
     - bugfix: int/string ``TypeError`` in line 226 (``upnp_reconnect``)
       (tnx 2 newold aka scorpionking)

   * - 2008/07/09 20:40
     - 5.00 -e
     - bugfix: another one |...| int/string ``TypeError`` in line 237

   * - 2008/07/15 09:30
     - 5.00 -f
     - add-on: added IP address range detection and delay (in "human steps"
       ranging from 1 minute to 5 hours)

   * - 2008/07/18 10:45
     - **5.01**
     - feature: support for configuration files

   * - 2008/07/18 19:50
     - 5.01 -a
     - AddOn: integrated support for RouterControl_

   * - 2008/07/19 14:30
     - 5.01 -b
     - bugfix: messed up the (found) correct path with RoCon_ (tnx 2 @re@50)

   * - 2008/07/21 15:00
     - 5.01 -c
     - add-on: integrated support for Telekom DisConnect_


TODO
====

- testing, testing, testing
- extension of the router database
- e-mail/SMS notify - work in progress (tnx 2 Y0Gi)

Well, that's actually it. Now have fun building our city!


General/Disclaimer
==================

For the software at hand, it is guaranteed that it wastes harddisk space.
Additional functionality exists by sheer chance and is not intended by the
author at all. Be cautioned against executing any of these applications.

.. warning:: USE AT YOUR OWN RISK!

The contained source code has been hacked together in a rush and should not
be used for education and training purposes ;-)

-- Tom, 2008


.. _MyMiniCity:     http://myminicity.com/
.. _reST:           http://docutils.sourceforge.net/rst.html
.. _Aqua Computer Support Forum: http://www.aqua-computer-systeme.de/cgi-bin/YaBB/YaBB.pl
.. _Python:         http://www.python.org/
.. _RouterControl:  http://www.routercontrol.de/
.. _CmdHere:        http://download.microsoft.com/download/whistler/Install/2/WXP/EN-US/CmdHerePowertoySetup.exe
.. _XP PowerToys:   http://www.microsoft.com/windowsxp/downloads/powertoys/xppowertoys.mspx
.. _cURL:           http://curl.haxx.se/
.. _DisConnect:     http://www.kessler-design.com/speedport-w700v/download.html
.. _UPnP:           http://en.wikipedia.org/wiki/Universal_Plug_and_Play
.. _private message: http://www.aqua-computer-systeme.de/cgi-bin/YaBB/YaBB.pl?board=4;action=imsend;to=Thomas_Haindl
.. _HTTP:           http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
.. _cookie:         http://en.wikipedia.org/wiki/HTTP_cookie
