readme.rst: Remove empty To-Do list

[elmcan.git] / readme.rst

diff --git a/readme.rst b/readme.rst
index 8a3592535347acd04f0134ed80569e1738d19aad..d7ccbab20bc259dfdea30f694d1dc3cc7f23be86 100644 (file)
--- a/readme.rst
+++ b/readme.rst
@@ -4,19 +4,20 @@ Linux SocketCAN driver for ELM327
 Authors
 --------
 
 Authors
 --------
 

-Max Staudt <elmcan@enpas.org>
+Max Staudt <max-linux@enpas.org>

 
 
 
 Motivation
 -----------
 
 
 
 
 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.
 
 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
 
 
 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,
 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),
 
 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
 -----------
 
 Data sheet
 -----------
 


@@ -56,6 +72,7 @@ How to check the controller version
 ------------------------------------
 
 Use a terminal program to attach to the controller.
 ------------------------------------
 
 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::
 
 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
 
 
 How to attach the line discipline


@@ -84,7 +104,7 @@ The line discipline can be attached on a command prompt as follows::
            --noparity \
            --onestopbit \
            --iflag -ICRNL,INLCR,-IXOFF \
            --noparity \
            --onestopbit \
            --iflag -ICRNL,INLCR,-IXOFF \

-           26 \
+           29 \

            /dev/ttyUSB0
 
 To change the ELM327's serial settings, please refer to its data
            /dev/ttyUSB0
 
 To change the ELM327's serial settings, please refer to its data


@@ -92,13 +112,46 @@ 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
 ------------------------------------
 
 Known limitations of the controller
 ------------------------------------
 

+- Clone devices ("v1.5" and others)
+
+  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
 
 - 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
 
   The length of outgoing RTR frames cannot be set. In fact, some
   clones (tested with one identifying as "``v1.5``") are unable to


@@ -170,11 +223,6 @@ Known limitations of the driver
   helpful here, however SocketCAN does not currently provide a facility
   to make use of such hardware features.
 
   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
 
 
 Communication example


@@ -230,8 +278,8 @@ For this to function, the controller must be configured for 11 bit CAN
 ID sending mode (using "``AT PB``", see code or datasheet).
 
 
 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::
 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,15 +305,46 @@ incomplete) data frame::
 
 
 
 
 
 

-To Do list for future development
-----------------------------------
+Rationale behind the chosen configuration
+------------------------------------------
+
+``AT E1``
+  Echo on
+
+  We need this to be able to get a prompt reliably.
+
+``AT S1``
+  Spaces on
+
+  We need this to distinguish 11/29 bit CAN addresses received.
+
+  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
+------------------------------
+
+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.

 
 

-- Rename ``elm327_panic()``

 
 

-- No auto-restart in ``elm327_panic()``?

 
 

-- Stop current function when in ``elm327_panic()``
+Thanks
+-------

 
 

-- DMA capable rx/tx buffers
+Thanks go out to Oliver Neukum for his early reviews and suggestions.

 
 

-- flushing of ``tx_work`` is too late in ``ldisc_close()``
+Several more people have encouraged me to finish this - thank you all.