Silence unused parameter in elmcan_do_set_bittiming()

[elmcan.git] / readme.rst

diff --git a/readme.rst b/readme.rst
index 2ff9fe4b4f4d9a51675dbb855815d1bb4853cd7e..f05bb635f404e0427245a37f4fa59f2ca5a8edd8 100644 (file)
--- a/readme.rst
+++ b/readme.rst
@@ -4,7 +4,7 @@ Linux SocketCAN driver for ELM327
 Authors
 --------
 
-Max Staudt <elmcan@enpas.org>
+Max Staudt <max-linux@enpas.org>
 
 
 
@@ -26,7 +26,7 @@ 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
+the driver has to switch between its modes as quickly as possible in
 order to approximate full-duplex operation.
 
 As such, elmcan is a best-effort driver. However, this is more than
@@ -43,6 +43,13 @@ known limitations in older controllers and clones.
 
 
 
+Requirements
+-------------
+
+This requires Linux 4.11 (for 431af779256c), and has been tested on 4.19.
+
+
+
 Data sheet
 -----------
 
@@ -84,7 +91,7 @@ The line discipline can be attached on a command prompt as follows::
            --noparity \
            --onestopbit \
            --iflag -ICRNL,INLCR,-IXOFF \
-           26 \
+           29 \
            /dev/ttyUSB0
 
 To change the ELM327's serial settings, please refer to its data
@@ -92,9 +99,40 @@ 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.
+
+       LOAD TIME::
+
+               module/kernel parameter: accept_flaky_uart=[0|1]
+
+
+
 Known limitations of the controller
 ------------------------------------
 
+- Clone "v1.5" devices
+
+  Sending RTR frames is not supported and will be dropped silently.
+
+  Receiving RTR with DLC 8 will appear to be a regular frame with
+  the last received frame's DLC and payload.
+
+  "``AT CSM``" not supported, thus no ACK-ing frames while listening:
+  "``AT MA``" will always be silent. However, immediately after
+  sending a frame, the ELM327 will be in "receive reply" mode, in
+  which it *does* ACK any received frames. Once the bus goes silent
+  or an error occurs (such as BUFFER FULL), the ELM327 will end reply
+  reception mode on its own and elmcan will fall back to "``AT MA``"
+  in order to keep monitoring the bus.
+
+
 - All versions
 
   No automatic full duplex operation is supported. The driver will
@@ -170,11 +208,6 @@ Known limitations of the driver
   helpful here, however SocketCAN does not currently provide a facility
   to make use of such hardware features.
 
-- No BUS-OFF state and automatic restart
-
-  We currently reset the ELM327 and generate error frames manually.
-  In the future, we may be able to use ``can_bus_off()`` and its siblings.
-
 
 
 Communication example
@@ -230,8 +263,8 @@ For this to function, the controller must be configured for 11 bit CAN
 ID sending mode (using "``AT PB``", see code or datasheet).
 
 
-Once a frame has been sent and wait-for-reply mode is on (ATR1,
-configured on listen-only=off), or when the reply timeout expires and
+Once a frame has been sent and wait-for-reply mode is on (``ATR1``,
+configured on ``listen-only=off``), or when the reply timeout expires and
 the driver sets the controller into monitoring mode (``ATMA``), the ELM327
 will send one line for each received CAN frame, consisting of CAN ID,
 DLC, and data::
@@ -257,19 +290,48 @@ incomplete) data frame::
 
 
 
-To Do list for future development
-----------------------------------
+Rationale behind the chosen configuration
+------------------------------------------
 
-- Handle ``write()`` error
+``AT E1``
+  Echo on
 
-- Rename ``elm327_panic()``
+  We need this to be able to get a prompt reliably.
 
-- No auto-restart in ``elm327_panic()``?
+``AT S1``
+  Spaces on
 
-- Stop current function when in ``elm327_panic()``
+  We need this to distinguish 11/29 bit CAN addresses received.
 
-- DMA capable rx/tx buffers
+  Note:
+  We can usually do this using the line length (odd/even),
+  but this fails if the line is not transmitted fully to
+  the host (BUFFER FULL).
+
+``AT D1``
+  DLC on
+
+  We need this to tell the "length" of RTR frames.
+
+
+
+A note on CAN bus termination
+------------------------------
 
-- fixup constants, constant for '``>``'
+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.
+
+
+
+To Do list for future development
+----------------------------------
+
+- DMA capable rx/tx buffers
+  (is this relevant for this driver?)
 
 - flushing of ``tx_work`` is too late in ``ldisc_close()``
+  (is this still the case?)