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

.. |date| date:: %d.%m.%Y, %H:%M Uhr

:Copyright: 2008 Tom (Dokumentation) und Y0Gi (Überarbeitung, reST_-Umsetzung)
:Date: |date|
:Version: 5.01


.. sectnum::

.. contents:: Inhalt


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


Vorwort
=======

Dieses Paket und die enthaltene Software und Dokumentation sind ausschließlich
für Mitglieder des `Aqua Computer Support-Forums`_ gedacht.

.. important:: Bitte *NICHT* weitergeben.

Danke an Y0Gi, Clark, Shoggy, Cronix und alle Anderen, die mit ihrer Hilfe und
ihren Ideen dieses Programm ermöglicht haben.

Danke auch an alle (Beta-)Tester und Bug-Reporter, die sehr viel Geduld mit
dieser schnell zusammengeschriebenen Software hatten und immer noch haben:
@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, |...|

Wer eine funktionierende und stabil laufende 4.x-Version hat, sollte diese
weiterhin verwenden - *"never touch a running system!"*

Diese Version richtet sich in erster Linie an User, die kein Python_ haben und
auch keines installieren dürfen/können/wollen. Weiterhin wurde die integrierte
Router-Steuerung komplett umgebaut und deutlich erweitert, um Hilfsprogramme
(wie z. B. RouterControl_) zu vermeiden.

Es gibt jetzt zwei Versionen:

*Python-Version*:
    Das läuft nur mit installiertem Python-Interpreter, der heute schon fester
    Bestandteil vieler Betriebssystem-Releases ist. Aktuelle Python-Versionen
    gibt's unter: `<http://www.python.org/download/releases/>`_

    Aufruf mit: ``ACmcMain.py <Parameterliste>``

    Bei manchen Pythons muss der Interpreter explizit angegeben werden:
    ``python.exe ACmcMain.py <Parameterliste>``

*Win32-Version*:
    Das sollte mit allen 32-Bit-Windows ab 2000 laufen. Diese Version ist
    sofort lauffähig und benötigt keinerlei Installation.

    Aufruf mit: ``ACmcMain.exe <Parameterliste>``


Installation/Auspacken
======================

Um allen Problemen vorzubeugen, sollte das Archiv in einen möglichst kurzen
Pfad (ohne Leerzeichen) entpackt werden, also z .B. nach ``D:\``. Mit dem
Standard-ZIP gibt das dann: ``D:\ACmcBatch500\...``.

Der Ordner ``Eigene Dateien`` ist keine gute Idee, weil die Pfade (je nach
Windows-Version und Netzwerkumgebung) zu lang werden können. Und der Ordner
``Programme`` ist eine ganz schlechte Idee, weil das Programm dann u. U. nur
noch mit Admin-Rechten läuft.

Wenn Du (von einer früheren Version) noch RouterControl_ installiert hast und
es problemlos läuft, solltest Du es weiterverwenden. Dafür gibt's ein
spezielles Router-Modell RoCon_, das das Programm vollständig integriert.


Ausführung
==========

.. attention:: Das ist kein Programm mit grafischer Windows-Oberfläche - ein
    Doppelklick bringt nicht viel.

Um schnell eine Shell (aka DOS-Fenster) mit dem richtigen Arbeitspfad zu öffen
gibt's CmdHere_ aus den `XP PowerToys`_: Damit kann man im Explorer auf den
Ordner rechtsklicken (Erweiterung des Kontext-Menues für Ordner).

**Neu:** Für die Übergabe der Parameter gibt es zwei Möglichkeiten:

- Die Parameter werden in eine einfache Konfigurations-Datei geschrieben:
  ``ACmcConf.txt``. Diese Datei muß sich im selben Verzeichnis befinden wie
  ``ACmcMain.py`` bzw. ``ACmcMain.exe``. Das Format ist super-einfach:
  Plain-Text und genau ein Parameter pro Zeile.

- Die Parameter werden auf der Kommandozeile übergeben. Beachte dazu auch die
  Beispiel-Dateien: ``Start.bat``. Mit "beachten" meine ich nicht ausführen,
  sondern angucken: ``Explorer |rarrow| Rechtsklick |rarrow| Bearbeiten``. Die
  Datei ``HitCity.bat`` macht genau einen Klick und endet dann. Dazu kann man
  eine Verknüpfung in den Autostart-Ordner legen.

- Diese beiden Methoden können auch gemischt werden. Die Parameter auf der
  Kommandozeile haben dabei Vorrang. D. h.: Wenn auf der Kommandozeile nichts
  steht, gelten die Einstellungen der Konfigurations-Datei. Z. B.: Wenn in der
  Konfigurations-Datei für die Verzögerungs-Zeit (erster Parameter) ein Wert
  von 10 Sekunden steht und man das Programm mit ``ACmcMain.exe 20 ...``
  startet, dann gelten 20 Sekunden.

Beim Aufruf des Programmes (``ACmcMain.py`` bzw. ``ACmcMain.exe``) ohne
Parameter gibt's eine kleine Hilfe und eine Liste der unterstützten Router.

**Neu:** Das Programm wartet jetzt auf die Eingabetaste (Enter/Return). Beim
"Windows-Doppelklick" wird sonst das Fenster gleich wieder geschlossen und man
sieht nix.

Wenn's nicht läuft sollte man das Programm nicht mit einem Doppelklick oder per
Windows-Verknüpfung sondern in einer Shell starten. Nur so hat man die
Möglichkeit, alle Fehlermeldungen und Fehler-Zustände zu entdecken:

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


Die Parameter im Einzelnen
==========================

.. note:: Parameter in spitzen Klammern sind zwingend erforderlich (z. B.
   ``<foo>``), Parameter in eckigen Klammern sind optional (z. B. ``[bar]``).
   Befindet sich innerhalb solcher spitzen oder eckigen Klammernpaare ein
   seknrechter Strich/das Pipe-Symbol (``|``), stehen mehrere Möglichkeiten
   zur Auswahl (z. B. ``[rot|grün]``).


Kurzversion (für Lesefaule)
---------------------------

``ACmcMain.exe <Delay> <WorkFile> <Betriebsstunden> <Router-Typ>
[Router-Parameter]``

- Parameter 1: Delay (1 .. 200 Sekunden | ``0`` = Auto-Timer | ``T`` = Test
  der Router-Steuerung)
- Parameter 2: WorkFile (``0`` = keine ArbeitsDatei | ``1`` =
  Default-Einstellung | ``Drive:Path\Name``)
- Parameter 3: Betriebsstunden (``A`` = 24h | 24* R|W|E, ``R`` = Run,
  ``W`` = Wait, ``E`` = Exit)
- Parameter 4: Router-Typ (``None`` | ``Batch`` | ``X`` | ``UPnP`` | ``UPnPa``
  | ``Get`` | ``Post`` | ``<model>`` gemäß Router-Liste)
- Parameter 5 und weiter: je nach Router-Typ (Parameter 4)

  - ``None`` (keine Parameter)
  - ``Batch`` (keine Parameter)
  - ``Fritz`` (keine Parameter) - für AVM FritzBox via UPnP
  - ``X <Programmaufruf mit Parametern>``: Externes Programm (RouterControl_,
    cURL_, DisConnect_ usw.) und Parameterliste
  - ``UPnPa <Adresse>``
  - ``UPnP <Adresse> <Port>``
  - ``Get <Adresse> <Username> <Passwort> <DocPath>``
  - ``Post <Adresse> <Username> <Passwort> <DocPath> <Data>`` (=/&-encoded)
  - ``model <Adresse> [Username] [Passwort]``

Bei mir sieht das dann z. B. so aus:

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


Langversion
-----------

- Parameter 1: Delay

  - Zahl = Feste Zeitangabe im Bereich 1 bis 200 Sekunden
  - ``0`` = (Null) Auto-Timer (das funktioniert je nach Provider meistens - aber
    nicht immer)
  - ``T`` = Test der Router-Steuerung (nur einen Reconnect ausführen und beenden)

- Parameter 2: WorkFile

  - ``0`` = (Null) keine Arbeitsdatei - kein Plattenzugriff, aber dann kann er
    sich auch nix merken.
  - ``1`` = (Eins) Default-Einstellung
  - Dateiname mit Pfad (optional) und Laufwerk (optional) -
    ``[[Drive:]Path\]Name``

- Parameter 3: Betriebsstunden

  - ``A`` = 24-Stunden Dauerbetrieb
  - Zeichenkette mit einem Buchstaben für jede Stunde (24 Zeichen für 0-23 Uhr)

    - ``R`` = Run - Programm läuft
    - ``W`` = Wait - Programm wartet
    - ``E`` = Exit - Programm wird beendet - eine Zeichenkette der Form
      ``...WWEER...`` macht also nicht allzu viel Sinn ;-)

- Parameter 4: Router-Name/Typ und ggf. Parameterliste (Parameter 5 und
  folgende)

  ``None`` (keine weiteren Parameter)
      Keine Routersteuerung - die Leitung wird mit dem Idle-Timeout
      (Router-Setup) getrennt

  ``Fritz`` (keine weiteren Parameter)
      Betrieb mit einer AVM FritzBox

  ``UPnP <Name|Adresse> <Port>``
      Betrieb mit UPnP-Routern

      .. attention:: UPnP_ muss im Router-Setup erlaubt werden.

      .. note:: Für die FritzBoxen gibt's einen speziellen Routertyp
         ``Fritz``.

  ``UPnPa <Name|Adresse>``
      Betrieb mit alten UPnP-Routern (z. B. Eumex 300 IP)

  ``model <Adresse> <Username> <Passwort>``
      Router-Modell (gemäß Liste), IP-Adresse des Routers, Name und Passwort

      Das Router-Modell bitte *GENAU* (copy & paste) übernehmen, sonst findet
      er's nicht. Wenn Dein Router zickt, solltest Du mit ähnlichen Modellen
      ein wenig experimentieren. Manche Router mögen die schnelle Befehlsfolge
      nicht - versuch dann mal die "disconnect-only"-Version.

      .. tip:: Wenn Dein Router in der Liste fehlt, schreib' mir über das
         Forum eine Kurzmitteilung_.

  .. _RoCon:

  ``RoCon`` (keine weiteren Parameter)
      Verwendung einer fertig installierten und funktionsfähigen Version von
      RouterControl_. Wenn es im Standard-Pfad installiert ist (Vorgabe des
      Programmes beim Installieren), wird es automatisch gefunden.

      Die aktuelle Version gibt's unter: `<http://www.routercontrol.de/rc.zip>`_
                    
  ``Batch`` (keine weiteren Parameter)
      Steuerung in einer Batch-Schleife mit einem Zusatz-Programm

      Funktion mit RouterControl_, cURL_ usw. wie in der Version 4.xx

      .. attention:: Bei 4.xx-Updates haben sich einige Errorlevels geändert.

  ``Get <Adresse> <Username> <Passwort> <DocPath>``
      HTTP-GET (siehe Spezielles_)

  ``Post <Adresse> <Username> <Passwort> <DocPath> <Data>`` (=/&-encoded)
      HTTP-POST (siehe Spezielles_)

  .. _X:

  ``X <Aufruf eines externen Programmes>``
      Einbindung eines externen Programmes (RouterControl_, DisConnect_ usw.)
      als Subprozess (teilweise ungetestet)

      Beachte dazu auch die Dateien ``MakeRC.bat`` für die Einbindung von
      RouterControl_ und die Datei ``ACmcCURL.bat`` für die Verwendung mit
      cURL_.


Programmaufruf
==============


Konfigurationsdatei (``ACmcConf.txt``)
--------------------------------------

Zum Erstellen der Datei bitte kein "Monster" wie MS Office Word oder Ähnliches
benutzen. Die Dinger können fast alles, nur die wichtigen Sachen wie z. B.
eine einfache Textdatei erstellen oder Kaffee kochen - das können sie nicht.

Windows-User nehmen dazu am besten den Windows-Editor (``notepad.exe``).

Das Parameter-Format ist exakt identisch mit der direkten Übergabe auf der
Kommandozeile - mit einem Unterschied: Die Parameter werden untereinander und
nicht nebeneinander geschrieben, d. h. es gibt genau einen Parameter pro Zeile.

``0``
    0 Sekunden = Auto-Timer

``1``
    1 Datenspeicher = Default-Datei

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

``Linksys_WRT_54G(7.00.1)``
    RouterModell = Linksys WRT 54G (FirmWare 7.00.1)

``192.168.1.1``
    RouterAdresse = 192.168.1.1

``admin``
    Benutzer = admin

``geheim``
    Passwort = geheim

Bitte beachte dazu auch die Beispiel-Datei ``ACmcConf-Beispiel.txt``, die
musst Du nur bearbeiten/anpassen und in ``ACmcConf.txt`` umbenennen.


Windows-Verknüpfung (mit Parameter-Übergabe)
--------------------------------------------

Zuerst eine Verknüpfung für ``ACmcMain.exe`` erstellen und diese Verknüpfung
dann bearbeiten.

Für eine AVM FritzBox sieht das dann etwa so aus:

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

Geübte Tastatur-Akrobaten können die Parameter natürlich auch jedesmal von
Hand neu eintippen ;-)


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

Die Batcherei der Vorgängerversionen hat sich hier eigentlich erledigt und
ist in dieser Version für besondere Spezialfälle vorgesehen.

Zum prinzipiellen Aufruf der 5er-Version in einem Batch-Programm: Siehe
Beispiel-Dateien ``Start.bat`` und ``ACmcCurl.bat``.

``MakeRC.bat`` erzeugt - wie in der Vorgängerversion - ein Batch-Programm zur
Verwendung mit ``RouterControl.exe``. Das ist allerdings überflüssig, da
RouterControl_ offensichtlich wunderbar mit dem ``X``-Parameter (siehe X_
oben)
funktioniert.


Bildschirmausgabe
=================

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


Spezielles
==========

.. note:: Für Pros.

- Prinzipiell kann unter ``X`` jedes Programm aufgerufen werden.

  Da bietet sich dann natürlich cURL_ an, das für jede beliebige Plattform
  verfügbar ist. Die aktuelle cURL_-Version für deine Plattform gibt es auf
  `<http://curl.haxx.se/download.html>`_

  Connect/Disconnect-Befehle für alle möglichen Router gibt's hier:
  `<http://reconnect.thau-ex.de/>`_

- Disconnect-Befehle lassen sich auch direkt mit ``Get`` und ``Post`` absenden.

  - Die cURL-Befehle (aus oben genannter Quelle) müssen nur noch vom Batch-
    und cURL-Overhead befreit werden. Es werden nur die HTTP_-Methoden GET und
    POST (cURL-Parameter ``-d``) via HTTP-Port 80 sowie
    Standard-Authentifizierung unterstützt. Für alle andere Methoden, Ports
    und Authentifizierungen (z. B. via Cookie_) mußt du cURL als Programm
    einbinden.

  - In den Strings können folgende Platzhalter verwendet werden:

    ``@IP@``
        IP-Adresse des Routers
    ``@US@``
        Benutzername
    ``@PW@``
        Passwort

- to be continued |...|


Changelog
=========

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

   * - Datum
     - Version
     - Bemerkung

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

   * - 2008/07/03 20:30
     - 5.00 -a
     - zu schnell für Netgear DG834B |rarrow| Delay in die Routersteuerung
       eingebaut (tnx 2 maed)

   * - 2008/07/03 23:50
     - 5.00 -b
     - AddOn: Alle reconnect (= disconnect + connect) Router mit ~_1 als
       "disconnect-only"-Version aufrufbar

   * - 2008/07/04 09:55
     - 5.00 -c
     - BugFix: ``import subprocess`` vergessen/gelöscht/übersehen/verschlampt
       (tnx 2 Nini2000 aka Chris)

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

   * - 2008/07/09 20:40
     - 5.00 -e
     - BugFix: noch einer |...| int/string-``TypeError`` in Zeile 237

   * - 2008/07/15 09:30
     - 5.00 -f
     - AddOn: IP-Adressblock-Detection und Delay eingebaut (in "human steps"
       von 1 Minute bis 5 Stunden)

   * - 2008/07/18 10:45
     - **5.01**
     - Feature: Unterstützung für Konfigurationsdateien

   * - 2008/07/18 19:50
     - 5.01 -a
     - AddOn: integrierte Unterstützung für RouterControl_

   * - 2008/07/19 14:30
     - 5.01 -b
     - BugFix: bei RoCon_ den (gefundenen) richtigen Pfad verschusselt
       (tnx 2 @re@50)

   * - 2008/07/21 15:00
     - 5.01 -c
     - AddOn: integrierte Unterstützung für Telekom DisConnect_


TODO
====

- Testen, testen, testen
- Ausbau der Router-Datenbank
- E-Mail-/SMS-Notify - work in progress (tnx 2 Y0Gi)
- Übersetzung dieser Dokumentation ins Englische - vielleicht hat da ja mal
  jemand die Muße

Das war eigentlich schon alles. Jetzt wünsch' ich Dir viel Spaß beim Aufbau
unserer Stadt!


Allgemeines/Disclaimer
======================

Bei der vorliegenden Software wird garantiert, daß diese Platz auf der Platte
verschwendet. Weitere Funktionen sind rein zufällig und vom Author gar nicht
beabsichtigt. Vor dem Ausführen irgendeiner dieser Anwendungen wird hiermit
ausdrücklich gewarnt.

.. warning:: USE AT YOUR OWN RISK!

Die enthaltenen Quelltexte sind "mal eben schnell zusammengehackt" und sollten
in dieser Ursprungsform nicht für Lehr- und Schulungszwecke verwendet werden ;-)

-- Tom, 2008


.. _MyMiniCity:     http://myminicity.com/
.. _reST:           http://docutils.sourceforge.net/rst.html
.. _Aqua Computer Support-Forums: 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://de.wikipedia.org/wiki/Universal_Plug_and_Play
.. _Kurzmitteilung: http://www.aqua-computer-systeme.de/cgi-bin/YaBB/YaBB.pl?board=4;action=imsend;to=Thomas_Haindl
.. _HTTP:           http://de.wikipedia.org/wiki/Hypertext_Transfer_Protocol
.. _Cookie:         http://de.wikipedia.org/wiki/HTTP-Cookie
