Completed conversion of documentation to readthedocs

docs/source/index.rst

@@ -15,10 +15,3 @@ Open Vehicles Monitoring System
    :caption: Vehicle Specific Guides:
 
    components/vehicle_*/docs/index*
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/source/userguide/boot.rst

@@ -0,0 +1,26 @@
+===========
+Boot Status
+===========
+
+OVMS maintains a record of the reason for each boot, in RAM that survives a reboot. It can show you how long the module has been running for, and the reason for the last reboot::
+
+  OVMS# boot status
+  Last boot was 2244 second(s) ago
+    This is reset #9 since last power cycle
+    Detected boot reason: SoftReset
+    Crash counters: 0 total, 0 early
+    CPU#0 boot reason was 12
+    CPU#1 boot reason was 12
+
+If an unexpected (not ‘module reset’) reboot occurs within the first 10 seconds of startup (usually during the boot-time auto-loading of modules, scripts, etc), the crash counters are incremented. If those crash counters reach 5 (without a clean reset in between), then the auto-loading of modules is disabled for the 6th boot.
+
+In case of a crash, the output will also contain additional debug information, i.e.::
+
+  Last crash: abort() was called on core 1
+    Backtrace:
+    0x40092ccc 0x40092ec7 0x400dbf1b 0x40176ca9 0x40176c6d 0x400eebd9 0x4013aed9
+    0x4013b538 0x40139c15 0x40139df9 0x4013a701 0x4013a731
+
+If the module can access the V2 server after the crash reboot, it will also store this information along with the crash counters in the server table “\*-OVM-DebugCrash”, which will be kept on the server for 30 days.
+
+Please include this info when sending a bug report, along with the output of “ota status” and – if available – any log files capturing the crash event (see Logging to SD CARD). If you can repeat the crash, please try to capture a log at “log level verbose”.

docs/source/userguide/configuration.rst

@@ -0,0 +1,44 @@
+=============
+Configuration
+=============
+
+OVMS stores all it’s configuration in a standardised protected configuration area accessed by the ‘config’ command. The configurations are organised as follows::
+
+  <parameter> <instance> = <value>
+
+For example:
+
+========= ======== =====
+Parameter Instance Value
+========= ======== =====
+vehicle   id       OVMSBOX
+wifi.ssid MYSSID   MyPassword
+auto      init     yes
+========= ======== =====
+
+Each parameter can be defined (by the component that owns it) as having readable and/or writeable attributes, and these act as access control for the parameters.
+
+* A ‘writeable’ parameter allows values to be created, deleted and modified.
+* A ‘readable’ parameter allows values to be seen. Instance names can be seen on non-readable parameters (it is just the values themselves that are protected).
+
+For example, the ‘vehicle’ parameter is readable and writeable::
+
+  OVMS# config list vehicle
+  vehicle (readable writeable)
+    id: MYCAR
+    timezone: HKT-8
+
+But the ‘wifi.ssid’ parameter is only writeable::
+
+  OVMS# config list wifi.ssid
+  wifi.ssid (protected writeable)
+    MYSSID
+    MyOtherSSID
+    MyNeighbour
+
+The ‘config’ command is used to manipulate these configurations, as is fairly self-explanatory::
+
+  OVMS# config ?
+  list                 Show configuration parameters/instances
+  rm                   Remove parameter:instance
+  set                  Set parameter:instance=value

docs/source/userguide/console.rst

@@ -0,0 +1,161 @@
+================
+The OVMS Console
+================
+
+-------------------
+Console Connections
+-------------------
+
+OVMS v3 includes a powerful command line console that can be accessed in various ways:
+
+1. Using a micro USB cable to a host computer.
+
+  If the OVMS is not recognised via USB download the driver from `SILABS website <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_). You will also need a suitable terminal emulator. The baud rate is 115200, and you should not enable hardware flow control.
+
+2. TELNET (over wifi).
+
+  Note that for security reasons, the telnet server component is not enabled in the default production firmware (but may be available in custom builds). If Telnet is available telnet to the IP address of the module (or <vehicleid>.local MDNS address).
+
+3. SSH (over wifi).
+
+  SSH to the IP address of the module (or <vehicleid>.local MDNS address). Note that when first booted with a network connection, the module takes a minute or so to generate server side keys (which are stored in the config store).
+
+4. Web Console SHELL tab.
+
+  Use a web browser to connect to the IP address of the module (or  <vehicleid>.local MDNS address). A SHELL tab is available for direct command line console access.
+
+5. Remote Apps.
+
+  The OVMS Android App currently includes a shell screen that can be used to issue command line console commands via the OVMS server v2. This functionality is not currently available in the iPhone/iPad App.
+
+6. SMS.
+
+  Console commands can be issued via SMS.
+
+^^^^^^^^^^^
+USB Console
+^^^^^^^^^^^
+
+Our recommendations for the USB console are as follows:
+
+1. You can use a Windows, Linux, Mac OSX workstation or an Android device with a USB OTG adapter cable.
+
+2. If your operating system does not have the SILABS USB driver, you can download the driver from `SILABS website <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_. If you use Linux and your distribution includes the braille display driver “brltty”, you may need to uninstall that, as it claims any CP2102 device to be a braille device. This applies e.g. to openSuSE 15.0.
+
+3. Plug in the module to your PC/laptop, using a micro USB cable. Check to ensure a serial port appears (using the SILABS driver). For OSX and Linux this will normally appear as /dev/tty.SLAB_USBtoUART or /dev/ttyUSB0 (or 1/2/… if other serial devices are connected). List your devices using “ls /dev/\*USB\*”.
+
+4. Once the serial port is available you will need a terminal emulator.
+
+  * For OSX, the simplest is the built-in SCREEN utility. You run this as ``screen -L /dev/tty.SLAB_USBtoUART 115200`` But note that the device path may be different for you - check with ‘ls /dev/\*USB\*’. You can use ‘control-a control-\ y’ or ‘control-a k y’ (three key sequences) to exit the screen. The “-L” option tells screen to capture a log of your session into the file “screenlog.<n>”.
+  * For Linux, the SCREEN utility is also simple to get. If it is not included with your distribution, you can simply *yum install screen*, or *apt-get install screen* (depending on your distribution). From there, the command is the same as for OSX. Alternatively, you can use minicom (which is included with many linux distributions).
+  * For Windows, a simple approach is to download the free PUTTY terminal emulator. This supports both direct ASYNC (over USB) connections, as well as SSH (network). You can download putty `using this link <https://www.putty.org/>`_.
+  * For Android, there are `multiple USB serial Apps in the Play store <https://play.google.com/store/search?q=usb+serial+terminal&c=apps>`_. A good recommendation is `Serial USB Terminal by Kai Morich <https://play.google.com/store/apps/details?id=de.kai_morich.serial_usb_terminal>`_.
+
+5. Once you have established the connection, press ENTER to see the “OVMS>” prompt.
+
+^^^^^^^^^^^
+SSH Console
+^^^^^^^^^^^
+
+A workstation (Mac, Linux, Window), on the same wifi network as the OVMS module, can use the ssh protocol to connect. In Windows you can use the free PUTTY ssh client. In Linux and OSX ssh is built-in.
+
+The syntax is simply:
+
+  ``ssh user@ip``
+
+Where ‘user’ is the username (normally ‘ovms’) and ‘ip’ is the IP address of the OVMS v3 module. In environments supporting mDNS networking, you should also be able to connect using the mDNS name *<vehicleid>.local*. The password you enter is the module password.
+
+If you use ssh public/private key pairs, you can store your public key on the OVMS v3 module, to take advantage of passwordless login.
+
+  ``OVMS# config set ssh.keys <user> <public-key>``
+
+In this case, ‘user’ is the username you use to ssh, and the public key is your RSA public key (the long base64 blob of text you find in id-rsa.pub between ‘ssh-rsa’ and your username/comment).
+
+You can also use SCP to copy files to and from the OVMS v3 VFS.
+
+A note about OpenSSH: with version 6.6, cipher aes128-cbc has been disabled by default and needs to be enabled manually, either on the command line:
+
+  ``ssh -c aes128-cbc user@ip``
+
+…or by adding a host entry to your *~/.ssh/config*.
+
+--------------
+Console Basics
+--------------
+
+Let’s use SSH to demonstrate this::
+
+  $ ssh ovms@ovms.local
+
+  Welcome to the Open Vehicle Monitoring System (OVMS) - SSH Console
+  Firmware: 3.1.003-2-g7ea18b4-dirty/factory/main
+  Hardware: OVMS WIFI BLE BT cores=2 rev=ESP32/1
+
+  OVMS#
+
+When first connecting using USB, the console will be in non-secure mode (as indicated by the “OVMS>” prompt). Here, only a limited number of commands are available (such as viewing network status, modem status, or system time). To get to secure mode, enter the command ‘enable’, and provide the module password. The prompt will then change to “OVMS#”::
+
+  OVMS> enable
+  Password:
+  Secure mode
+  OVMS#
+
+You can enter the ‘disable’ command to get out of secure mode, and ‘exit’ to exit the console completely.
+
+When connecting via a pre-authenticated protocol such as SSH, you will be in secure mode automatically.
+
+At any time, you can use “?” to show the available commands. For example::
+
+  OVMS# ?
+  .                    Run a script
+  boot                 BOOT framework
+  can                  CAN framework
+  charge               Charging framework
+  co                   CANopen framework
+  config               CONFIG framework
+  disable              Leave secure mode (disable access to most commands)
+  egpio                EGPIO framework
+  enable               Enter secure mode (enable access to all commands)
+  event                EVENT framework
+  exit                 End console session
+  help                 Ask for help
+  homelink             Activate specified homelink button
+  location             LOCATION framework
+  lock                 Lock vehicle
+  log                  LOG framework
+  metrics              METRICS framework
+  module               MODULE framework
+  network              NETWORK framework
+  notify               NOTIFICATION framework
+  obdii                OBDII framework
+  ota                  OTA framework
+  power                Power control
+  re                   RE framework
+  script               Run a script
+  sd                   SD CARD framework
+  server               OVMS Server Connection framework
+  simcom               SIMCOM framework
+  stat                 Show vehicle status
+  store                STORE framework
+  test                 Test framework
+  time                 TIME framework
+  unlock               Unlock vehicle
+  unvalet              Deactivate valet mode
+  valet                Activate valet mode
+  vehicle              Vehicle framework
+  vfs                  Virtual File System framework
+  wakeup               Wake up vehicle
+  wifi                 WIFI framework
+
+You can also use “?” as part of a command to expand on the available options within that command root::
+
+  OVMS# wifi ?
+  mode                 WIFI mode framework
+  scan                 Perform a wifi scan
+  status               Show wifi status
+
+The TAB key can also be used to expand on commands or parameter options::
+
+  OVMS# wifi <TAB>
+  mode scan status
+