readme.rst: Clarify DKMS install command

[elmcan.git] / readme.rst

diff --git a/readme.rst b/readme.rst
index d2aced218fb744c4dfd48895c2590bf73660b3fc..7facff87f1ce155b0cd822c3ef434cb2df46649d 100644 (file)
--- a/readme.rst
+++ b/readme.rst
@@ -4,19 +4,20 @@ Linux SocketCAN driver for ELM327
 Authors
 --------
 
-Max Staudt <elmcan@enpas.org>
+Max Staudt <max-linux@enpas.org>
 
 
 
 Motivation
 -----------
 
-CAN adapters are expensive, few, and far between.
-ELM327 interfaces are cheap and plentiful.
-
 This driver aims to lower the initial cost for hackers interested in
 working with CAN buses.
 
+CAN adapters are expensive, few, and far between.
+ELM327 interfaces are cheap and plentiful.
+Let's use ELM327s as CAN adapters.
+
 
 
 Introduction
@@ -26,8 +27,8 @@ This driver is an effort to turn abundant ELM327 based OBD interfaces
 into full-fledged (as far as possible) CAN interfaces.
 
 Since the ELM327 was never meant to be a stand-alone CAN controller,
-the driver has to switch between its modes asa quickly as possible in
-order to approximate full-duplex operation.
+the driver has to switch between its modes as quickly as possible in
+order to fake full-duplex operation.
 
 As such, elmcan is a best-effort driver. However, this is more than
 enough to implement simple request-response protocols (such as OBD II),
@@ -43,6 +44,21 @@ known limitations in older controllers and clones.
 
 
 
+Requirements
+-------------
+
+This requires Linux 4.11 (for 431af779256c), and has been tested on 4.19.
+
+Also, elmcan depends on ``can-dev``:
+
+    sudo modprobe can-dev
+
+Install
+-------------
+    cd module/
+
+    sudo dkms install .
+
 Data sheet
 -----------
 
@@ -56,6 +72,7 @@ How to check the controller version
 ------------------------------------
 
 Use a terminal program to attach to the controller.
+The default settings are 38400 baud/s, 8 data bits, no parity, 1 stopbit.
 
 After issuing the "``AT WS``" command, the controller will respond with
 its version::
@@ -67,6 +84,9 @@ its version::
 
     >
 
+Note that clones may claim to be any version they like.
+It is not indicative of their actual feature set.
+
 
 
 How to attach the line discipline
@@ -92,10 +112,27 @@ sheet. This needs to be done before attaching the line discipline.
 
 
 
+Module parameters
+------------------
+
+- ``accept_flaky_uart`` - Try to live with a bad controller or UART line
+
+       Some adapters and/or their connection are unreliable. Enable this
+       option to try and work around the situation. This is a best-effort
+       workaround, so undefined behavior will likely occur sooner or later.
+       Without this option, the driver will bail on the first unrecognized
+       character it receives from the TTY.
+
+       LOAD TIME::
+
+               module/kernel parameter: accept_flaky_uart=[0|1]
+
+
+
 Known limitations of the controller
 ------------------------------------
 
-- Clone "v1.5" devices
+- Clone devices ("v1.5" and others)
 
   Sending RTR frames is not supported and will be dropped silently.
 
@@ -113,8 +150,8 @@ Known limitations of the controller
 
 - All versions
 
-  No automatic full duplex operation is supported. The driver will
-  switch between input/output mode as quickly as possible.
+  No full duplex operation is supported. The driver will switch
+  between input/output mode as quickly as possible.
 
   The length of outgoing RTR frames cannot be set. In fact, some
   clones (tested with one identifying as "``v1.5``") are unable to
@@ -293,9 +330,28 @@ Rationale behind the chosen configuration
 
 
 
+A note on CAN bus termination
+------------------------------
+
+Your adapter may have resistors soldered in which are meant to terminate
+the bus. This is correct when it is plugged into a OBD-II socket, but
+not helpful when trying to tap into the middle of an existing CAN bus.
+
+If communications don't work with the adapter connected, check for the
+termination resistors on its PCB and try removing them.
+
+
+
+Thanks
+-------
+
+Thanks go out to Oliver Neukum for his early reviews and suggestions.
+
+Several more people have encouraged me to finish this - thank you all.
+
+
+
 To Do list for future development
 ----------------------------------
 
-- DMA capable rx/tx buffers
-
-- flushing of ``tx_work`` is too late in ``ldisc_close()``
+- None currently