First pass at converting documentation to online rst markup

docs/source/index.rst

@@ -1,16 +1,13 @@
-.. Open Vehicles documentation master file, created by
-   sphinx-quickstart on Thu Jun 27 10:25:04 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Open Vehicles's documentation!
-=========================================
+===============================
+Open Vehicles Monitoring System
+===============================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
+   :maxdepth: 1
+   :caption: Available Documents:
 
+   introduction
+   userguide/index
 
 Indices and tables
 ==================

docs/source/introduction.rst

@@ -0,0 +1,8 @@
+============
+Introduction
+============
+
+The OVMS (Open Vehicle Monitoring System) team is a group of enthusiasts who are developing a means to remotely communicate with our cars, and are having fun while doing it.
+
+The OVMS module is a low-cost hardware device that you install in your car simply by installing a SIM card, connecting the module to your car's Diagnostic port connector, and optionally positioning a cellular antenna. Once connected, the OVMS module enables remote control and monitoring of your car.
+

docs/source/userguide/components.rst

@@ -0,0 +1,79 @@
+==========
+Components
+==========
+
+---------------
+The OVMS Module
+---------------
+
+.. image:: module1.jpg
+  :width: 200px
+  :align: right
+
+The OVMS v3 module is housed in a plastic enclosure; held secure by four small screws. Once open, you can see the main OVMS v3 motherboard, and an optional modem board.
+
+At one end of the module is the main DB9 connector you will use to connect to the vehicle, as well as GSM (cellular) and GPS (positioning) antenna connections.
+
+.. image:: module2.jpg
+  :width: 200px
+  :align: right
+
+At the other end of the module is the DA26 expansion connector, the USB diagnostic connector, and a Micro SD card slot.
+
+If removing/installing optional expansion boards (such as used for cellular connectivity), please take care to ensure you secure screw down the expansion board using the four pillar posts provided. Also, please ensure that the cellular modem connections are correct (follow the printed table on the modem board to know which antenna is which).
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+| **Warning!**
+| The OVMS v3 enclosure is not waterproof, and the components can be damaged by water. Do not get the module wet, and do not connect it to your vehicle if it is wet.
+
+-------------------------------------
+Cellular Modem Option and GSM Antenna
+-------------------------------------
+
+The cellular modem option allows you to control your vehicle when out of wifi coverage range. The majority of OVMS users choose this option, and you will require it if you want to monitor your vehicle when away from home or office.
+
+Each OVMS modem module is provided with a Hologram SIM card pre-installed. This low cost service allows you to get cellular connectivity simply. It also allows you to roam between countries without worry.
+
+Depending on settings, verbosity towards the OVMS server, rhythm of GPS tracking, etc, OVMS v3 will use between 1 and 3 Megabytes per month of data (when using the v2 server protocol).
+
+You do not have to use the Hologram service. If you use another cellular provider, the Sim Card format required is 4FF Nano. Micro Sim cards are hard to recut into the smaller format, so please be careful to not damage the socket; otherwise, ask your operator for a swap (some do it for free).
+
+If you are using the cellular option, you should attach a suitable cellular antenna to the module, using the antenna connector labeled "GSM".
+
+----------------
+GPS/GNSS Antenna
+----------------
+
+Some OVMS vehicles can read the GPS signals from the car communication networks directly, and do not require any additional hardware. For others, the OVMS v3 modem option also includes a GNSS/GPS satellite tracking receiver.
+
+If you are using this option, you should connect a suitable active GPS antenna to the connector labelled "GPS".
+
+------------------
+Vehicle Connection
+------------------
+
+The connection to the vehicle is by the DB9 connector labelled "VEHICLE". This provides power to the OVMS module, as well as connection to the vehicle communication networks.
+
+Different vehicles require different cables, so you should refer to the appropriate vehicle section of this user guide to determine which is correct for yours.
+
+--------------
+OVMS Server v2
+--------------
+
+The OVMS Server v2 protocol is a proprietary protocol used to communicate between the vehicle and an OVMS v2 server, as well as from that server to the cellphone apps. To provide compatibility with existing OVMS v2 cellphone apps and servers, OVMS v3 includes full support for the OVMS v2 protocol.
+
+--------------
+OVMS Server v3
+--------------
+
+The OVMS Server v3 protocol is MQTT. This is an industry standard protocol, and means an OVMS v3 module can communicate with any standard MQTT server. While this is the future of OVMS, support for this is experimental at the moment and production users should use OVMS Server v2 protocol.
+
+-------------------------------
+Upgrading from OVMS v1/v2 to v3
+-------------------------------
+
+The antenna and vehicle connectors for OVMS v3 are the same as for OVMS v2, and existing cables/antennas can generally be re-used for OVMS v3. Note, however, that the frequency ranges supported by individual 3G networks may be different than 2G, so may benefit from an antenna specifically designed for the 3G frequency ranges used
+

docs/source/userguide/index.rst

@@ -0,0 +1,12 @@
+==========
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   warnings
+   components
+   installation
+

docs/source/userguide/installation.rst

@@ -0,0 +1,240 @@
+============
+Installation
+============
+
+----------------------
+Pre-Installation Steps
+----------------------
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+| **Warning!**
+| Prior to connecting the OVMS module to the vehicle, or computer via USB, if you have the GSM cellular option we recommend you connect a GSM antenna. GSM systems are designed to always operate with an antenna, and powering on one without could damage the equipment.
+
+Prior to installation, please make sure you have the following available:
+
+#. The OVMS v3 module in it's enclosure.
+#. A small screwdriver, for opening the module (if necessary).
+#. A micro-usb cable suitable for connecting to your computer.
+#. A laptop or desktop computer (if necessary).
+#. A cable suitable for connecting to your vehicle.
+#. A GSM antenna (if you are using the cellular option).
+#. A GPS antenna (if your vehicle type requires one).
+
+You should also have ready access to this User Guide, and wifi connectivity to the Internet.
+
+---------------------------
+OVMS v2 Server Registration
+---------------------------
+
+Prior to installation, you should create an account, and register your vehicle on one of the public OVMS v2 servers:
+
+#. https://www.openvehicles.com/
+   This OVMS v2 server is run by the project. It is hosted in Hong Kong.
+
+#. https://dexters-web.de/
+   This OVMS v2 server is hosted in Europe.
+
+During the registration process you will need to decide a VehicleID (unique ID to be identify your vehicle), and a Server Password (password to be used on cellphone apps, servers, and vehicle modules). The server itself will also have a specific hostname and port it uses for OVMS protocol v2 communications.
+
+-------------------
+Hologram Activation
+-------------------
+
+OVMS has partnered with Hologram and is providing a Hologram SIM pre-installed in every OVMS modem board. In addition, Hologram have provided our community a coupon code valid for US$5 off data usage:
+
+Hologram Coupon Code: **OVMS**
+
+When activating your Hologram SIM, you'll need to enter the ICCID written on the SIM itself. You can also get that electronically (without having to open up the package) from the web or terminal shells with the following command:
+
+``OVMS# metric list m.net.mdm.iccid``
+
+The ICCID is also displayed during the setup process and on the modem configuration page when using the web user interface.
+
+------------------------
+OVMS Module Installation
+------------------------
+
+^^^^^^^^^^^^^^^^^^^
+Powering the module
+^^^^^^^^^^^^^^^^^^^
+
+If you intend to configure the module on your desk before connecting it to the vehicle, make sure your USB port delivers power (around 500mA, depending on modem and wifi activity). We recommend using a USB hub with a separate power supply or a direct port of your laptop / PC.
+
+^^^^^^^^^^^^^^
+Server account
+^^^^^^^^^^^^^^
+
+If you want to use the OVMS App and/or server based telemetry services, you'll need a server account. If you have not registered for an OVMS server account yet, you can do so before starting the wizard to avoid needing to switch networks in between. There are currently two public OVMS servers:
+
+Asia-Pacific: https://www.openvehicles.com/
+Europe:	https://dexters-web.de/
+
+You will need to create a user account first. Within your user account you then need to create a vehicle account. You'll need to pick a unique vehicle ID for this, e.g. your vehicle license plate number.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Initial Connection (Wifi and Browser)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the factory, or after a factory reset, your OVMS module will be running an access point, with the following credentials:
+
+SSID:		OVMS
+Password:	OVMSinit
+
+As this is insecure, you should take care not to leave the module running unconfigured.
+
+Using your laptop/tablet/phone, establish a wifi connection to the module. You should see an IP address in the range 192.168.4.x allocated, with a gateway at 192.168.4.1.
+
+Launch your web browser, and connect as follows:
+
+URL:		http://192.168.4.1/
+
+Once connected, you will be presented with a screen as follows:
+
+.. image:: setup1.jpg
+
+^^^^^^^^^^^^
+Setup wizard
+^^^^^^^^^^^^
+
+The first thing to do is run the setup wizard. Click **Start setup now**. The wizard takes you through the initial setup in five simple steps, telling you what it is doing and what to expect for each step.
+
+.. image:: setup2.jpg
+
+The wizard will need to reconfigure the module for the Wifi setup, read the notes and be prepared to reconnect to the module as necessary.
+
+Note: we recommend not to use a password manager during the setup process. Some browsers, e.g. Chrome, will fill in the module ID as the username, which is wrong. The login username needs to be **admin**.
+
+The wizard should be able to restore access after problems occurring in the process. As a last resort if it fails to recover at some point, you can always do a factory reset and start over again.
+
+^^^^^^^^^^^^^^^^^^^^
+Manual configuration
+^^^^^^^^^^^^^^^^^^^^
+
+After finishing the wizard or if you prefer to do a manual setup, the configuration menus will provide single pages for each module function. These also contain advanced options for the features, so it's worth having a look.
+
+^^^^^^^^^^^^^^^^^^^^^
+Vehicle Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+Go to Config / Vehicle:
+
+.. image:: setup3.jpg
+
+You'll want to enter your vehicle type, Vehicle ID (the same as you registered on the OVMS server), and distance units. You can also optionally enter your timezone (see https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html for an article on GLIBC timezones for information on the format of this, a list of suitable zone strings can also be found here: https://remotemonitoringsystems.ca/time-zone-abbreviations.php).
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+OVMS Server v2 Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Go to Config / Server V2 to configure the connection to the OVMS v2 server you will be using:
+
+.. image:: setup4.jpg
+
+You should enter the server host (api.openvehicles.com, or ovms.dexters-web.de, usually), and vehicle password (aka *server password* - as entered on the server when you registered your vehicle). The Vehicle ID field should already be there, and the other parameters are optional.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+Auto Start Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+OVMS has a powerful scripting language that can be used for complex configurations, but to get started it is simplest to use the Auto Start system. You get to this from the web interface by clicking Config / Autostart.
+
+.. image:: setup5.jpg
+
+You will usually want to click to **Enable auto start**, and **Start server v2**. The other fields should have been populated correctly automatically for you. If you are using the optional modem module, you should also click **Start modem** to enable the modem.
+
+Once complete, you can **Save & reboot** to activate your new configuration.
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+| **Warning!**
+| Do not set the Wifi mode to **AP+Client** or **Client** before having configured your Wifi network. Also, do not use client scan mode with **AP+Client**, as this is not supported! The web interface will prevent these combinations.
+ 
+If you have configured this combination manually, the Wifi network will not start automatically. You need to log in using a USB terminal and either do a factory reset (see Module Factory Reset) or (better) issue **enable** to enter secure mode, then issue **config set auto wifi.mode ap** and reboot.
+
+^^^^^^^^^^^^^^^^^^
+Networking Options
+^^^^^^^^^^^^^^^^^^
+
+OVMS v3 has a number of networking options to choose from. You can either use these individually, or combine them to provide failover and alternative network connectivity arrangements.
+
+#. Wifi Client. OVMS can connect to a WiFi Access Point, using standard WiFi (802.11 b/g/n) protocols, to connect to a SSID (Access Point name) with associated password. In simple client mode, you can connect only to a single pre-specified SSID. Alternatively, you can use the scanning client mode to connect to any known WiFi Access Point when within range (note, however, that this is not possible when you run both client and access point on the same OVMS device).
+
+#. Wifi Access Point. OVMS can operate as a WiFi Access Point itself, using standard WiFi (802.11 b/g/n) protocols. This allows users to connect to the OVMS module itself. Note that OVMS v3 is not intended to be a hotspot and users cannot access the Internet via the OVMS module. Wifi Access Point mode can be combined with simple Wifi Client mode, to provide an access point for maintenance of the module, as well as a client to access the Internet via another Access Point within range.
+
+#. Cellular Data. OVMS supports optional modems to provide cellular connectivity. These are configured via Config / Modem.
+
+.. image:: setup6.jpg
+
+^^^^^^^^^^^^^^^
+Firmware Update
+^^^^^^^^^^^^^^^
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+The factory firmware that is provided with the module may be quite out of date. You should perform a firmware update to ensure that you have the latest firmware. You can do this either over Wifi client connections, or via an SD CARD.
+
+We recommend using the auto update system. This will be preconfigured if you have used the setup wizard. The automatic updates are done within a selectable hour of day, and only if Wifi connectivity is available at the time.
+
+^^^^^^^^^^^^^^
+Flash from Web
+^^^^^^^^^^^^^^
+
+.. image:: setup7.png
+
+You can typically just press the **Flash now** button and wait for completion.
+
+^^^^^^^^^^^^^^^
+Flash from File
+^^^^^^^^^^^^^^^
+
+Using an SD CARD formatted as FAT, download the firmware update and place it in a file called **ovms3.bin** in the root directory of the SD CARD. Once the SD CARD is inserted the firmware update will start immediately.
+
+^^^^^^^^^^^^^^^
+12V Calibration
+^^^^^^^^^^^^^^^
+
+The 12V voltage is measured using the incoming voltage that powers the OVMS. You can calibrate it using:
+
+``config set system.adc factor12v <factor>``
+
+The <factor> has to be calculated using:
+
+``oldFactor * (displayedVoltage / actualVoltage)``
+
+* oldFactor is the old value set. If you have not changed it yet it is 195.7
+* displayedVoltage is the Voltage as displayed by the OVMS.
+* actualVoltage is the Voltage as measured by hand using a voltmeter.
+
+The voltage is read once per second and smoothed over 5 samples, so after changing the factor, wait 5-10 seconds for the new reading to settle.
+
+The initial 12V reference voltage (= fully charged & calmed down voltage level) on startup & after reset can be set by
+
+``config set vehicle 12v.ref <voltage>``
+
+The default reference voltage is 12.6. The value will be updated automatically if your vehicle supports the v.e.charging12v flag.
+
+The 12V alert threshold can be set by
+
+``config set vehicle 12v.alert <voltagediff>``
+
+The 12V alert threshold is defined by a relative value to the 12v reference voltage with a default value of  1.6. If the actual 12V reading drops below 12v.ref - 12v.alert, the 12V alert is raised.
+
+Related metrics:
+
+===================== ============= =======
+Metric                Example Value Meaning
+===================== ============= =======
+v.b.12v.current       0.6A          Momentary current level at the 12V battery
+v.b.12v.voltage       13.28V        Momentary voltage level at the 12V battery
+v.b.12v.voltage.ref   12.51V        Reference voltage of the fully charged & calmed down 12V battery
+v.b.12v.voltage.alert no            If the 12V critical alert is active (yes/no).
+v.e.charging12v       yes           If the 12V battery is charging or not (yes/no)
+===================== ============= =======
+

docs/source/userguide/warnings.rst

@@ -0,0 +1,19 @@
+================
+General Warnings
+================
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+| **Warning!**
+| OVMS is a hobbyist project, not a commercial product. It was designed by enthusiasts for enthusiasts. Installation and use of this module requires some technical knowledge, and if you don't have that we recommend you contact other users in your area to ask for assistance.
+
+.. image:: warning.png
+  :width: 100px
+  :align: left
+
+| **Warning!**
+| The OVMS module is continuously powered by the car, even when the car is off. While the OVMS module uses extremely low power, it does continuously draw power from the car's battery, so it will contribute to 'vampire' power drains. Do not allow your car battery to reach 0% SOC, and if it does, plug in and charge the car immediately. Failure to do this can result in unrecoverable failure of the car's battery.
+
+