X-Git-Url: https://git.enpas.org/?a=blobdiff_plain;ds=sidebyside;f=readme.rst;h=d7ccbab20bc259dfdea30f694d1dc3cc7f23be86;hb=fb48aed84a6cd0c6cb471fd8bdd7ae6faa3334b7;hp=8a3592535347acd04f0134ed80569e1738d19aad;hpb=4773fcf3beb4375a6663fbe79de1d9160c294069;p=elmcan.git diff --git a/readme.rst b/readme.rst index 8a35925..d7ccbab 100644 --- a/readme.rst +++ b/readme.rst @@ -4,19 +4,20 @@ Linux SocketCAN driver for ELM327 Authors -------- -Max Staudt +Max Staudt 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 @@ -84,7 +104,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,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 ------------------------------------ +- 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 - 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 @@ -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. -- 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 +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). -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,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.